IIB Intro POT Labs 1 6 July 2015
Descripción
IBM Software WebSphere
Discovering the Value of IBM Integration Bus V9 – a Proof of Technology Lab Exercises
An IBM Proof of Technology
© Copyright IBM Corporation, 2014 US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
Contents LAB 1
GETTING STARTED ................................................................................................................................... 6 BUILDING AND EXECUTING A SIMPLE MESSAGE FLOW ...................................................................... 6 GETTING TO KNOW THE TOOLKIT .................................................................................................... 7 BUILDING A SIMPLE FLOW ............................................................................................................. 12 TESTING THE FLOW ..................................................................................................................... 28
LAB 2
MESSAGE MODELS AND WORKING WITH XML MESSAGES.............................................................. 45 OVERVIEW ................................................................................................................................. 45 USING THE XML PARSER ............................................................................................................ 45 CREATING A MESSAGE MODEL FROM AN XSD ............................................................................... 51 RE-RUNNING THE TEST CLIENT .................................................................................................... 65
LAB 3
CONTENT BASED ROUTING AND THE DEBUGGER ............................................................................ 68 OVERVIEW ................................................................................................................................. 68 ADD ROUTING LOGIC .................................................................................................................. 68 TEST WITH THE DEBUGGER .......................................................................................................... 85 A CLOSER LOOK AT THE DEPLOYMENT PROCESS ........................................................................... 99
LAB 4
USING PUBLISH/SUBSCRIBE WITH IBM INTEGRATION BUS ........................................................... 107 OVERVIEW ............................................................................................................................... 107 USING THE NOMATCH TERMINAL ................................................................................................ 167
LAB 5
MESSAGE MODELING WITH DFDL. ..................................................................................................... 170 OVERVIEW ............................................................................................................................... 170 CREATING A MESSAGE MODEL FROM A COBOL COPYBOOK......................................................... 170 TESTING THE MESSAGE MODEL ................................................................................................. 192 USING THE TRACE FACILITY ....................................................................................................... 201
LAB 6
BUILDING A WEB SERVICE USING PATTERNS AND MAPPING ....................................................... 207 LAB OVERVIEW ......................................................................................................................... 207 TEST THE MESSAGE FLOW ......................................................................................................... 252
Page 5
Lab 1
Getting Started
Building and Executing a Simple Message Flow In this lab, you will build and execute a simple message flow. A message flow is like a program but is developed using a visual paradigm. The flow will be deployed to an Integration Server in an Integration Node where it will execute. An Integration Server is an operating system process where user flows execute. The flow will then be available to process messages. There is no need to restart the Integration Node or the Integration Server for the deployment of a new or changed message flow. The unit of deployment is a Broker Archive file (BAR). Broker archive files have a file extension of “bar”. It is essentially a zip file with a deployment descriptor. The deployment descriptor allows certain properties of the message flow to be overridden. The Broker Archive file will hold the artifacts to be deployed to a specific Integration Server in a specific Integration Node. It may contain applications and libraries as well as message flows, message sets, XSL Transformations (XSLT) Style Sheets, Java™ Archive (JAR) files, XML schema files or WSDL files. In addition, the related source files may also be included. When you add a message flow to the BAR file, additional validation of the message flow is performed. The BAR file is then deployed to the Integration Node. The final validation of the artifacts is done by the Integration Node. If errors are found by the Integration Node, they will be reported back in the Event Log. As a convention for these labs, a red box will be used to identify a particular area, and when information is to be entered and/or an action is to be taken, it will be in bold characters. Red lines may be used to indicate where nodes are to be placed when building your message flow. Tools that you will use as part of these labs include: • • •
Page 6
Integration Toolkit Integration Console Integration Bus Explorer (WebSphere MQ Explorer)
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
Getting to know the Toolkit On your workstations you will likely launch the IIB and WMQ toolset components from the Windows My Programs list. Feel free to create shortcuts on your desktop for these tools as we go along, if that would make things easier for you, as some of the tools will be launched several times. You should have either the IBM Integration Bus Developer Edition V9 or the IBM Integration Bus Advanced Edition V9 installed. If so you should see the product components in the Windows My Programs list. You should see something along these lines:
Page 7
__1.
To start the IBM Integration Toolkit, click on the link highlighted below:
The splash screen is displayed when starting the IBM Integration Toolkit.
Page 8
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
You are prompted to select an Eclipse Workspace – you will take the default here but this is a nice facility to allow you switch between workspaces when starting the toolkit. __2.
Verify that the C:\student\workspace directory is selected.
__3.
Click OK.
Page 9
__4.
Page 10
Now take a look around at the Toolkit.
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
Key Idea: The Toolkit The Integration Toolkit is based on Eclipse and includes components from IBM Rational® Application Developer. It provides one Perspective specifically for IBM Integration Bus as well as additional Perspectives from Rational Application Developer and Eclipse. This system is using the default installation. During the labs and lectures, you will be learning more about the components in a typical development and runtime environment. The screenshot on the previous page is of the Integration Development perspective. It is divided into multiple views (or panes). Each view is identified by a tab at the top of the view. On the lower left is the Outline view On the upper left is the Navigator view, which has tabs for projects (Integration Development) and patterns (Patterns Explorer). The Navigator view contains the projects that are available within the Eclipse workspace. There is a set of resources already provided for your use during the labs. The area below the navigator view is the summary area. The Integration Nodes tab will show all defined local nodes as well as connections to remote nodes that have been created. The large area on the right is used by the resource editors. When an editor has opened a resource, it will also be represented by a tab. Below the editor view is a pair of views for Properties and Problems. On the top right are tabs for the perspectives that have been opened. To change an open perspective, you can simply click on its tab. Quick Start wizards are displayed as links in the center of the screen, which is the default blank palette within the Editor view. You can also access these by right clicking whitespace in the Applications view on the left. The wizards do some of the initial work for creating various types of solutions. The Integration Toolkit provides several Quick Start wizards plus a number of pre-defined patterns to assist in creating Applications and Libraries. We will see more of these in later labs. Eclipse is project oriented – artifacts are organized into projects. A project is typed. Project types that are specific to IBM Integration Bus are Applications and Libraries. Also, legacy projects of type Message Flow Project and Message Set Project can be created or imported into the toolkit. Since they pre-date the concept of Applications and Libraries, they will be visible in the hierarchy under a Folder called “Independent Resources”.
Page 11
Building a simple flow __1.
Right click in the white space of the Application Development pane.
__2.
Select New Application.
As an alternative, you can click File on the Menu Bar, and select New Other, type Application in the selection box, and click Next. Note: These actions are also available as icons on the toolbar.
Page 12
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
You are prompted to enter a name for your Application. __3.
Enter IntroLab for the Application name.
__4.
Click Finish.
Page 13
Now you will create a new message flow. __5.
Under the IntroLab, click on (New…).
__6.
Select Message Flow.
The options for the New action will be different depending on how the request is made. For example, when using the File New from the Menu bar, all of the options will be listed. However, in this case, by starting from an Application, the only options shown are those that are related to the selected project.
Page 14
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
Here you are asked to name the message flow. An Application may contain multiple message flows. __7.
Enter IntroMessageFlow in the Message flow name box.
__8.
Click Finish.
Page 15
You are placed into the Message Flow Editor where you can compose the message flow. When you click on the Message Flow Editor, information about the message flow appears in the Properties pane. __9.
Select the Properties tab.
__10.
Select the Description tab.
__11.
Enter the following: • • •
Page 16
Enter 1.0 for the Version field; Enter Introduction to IBM Integration Bus V9.0 for the Short description field; Your choice of information in the Long description field.
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
A message flow must begin with an Input node. An input node establishes the environment for the flow. There is an Input node for each of the various protocols that IBM Integration Bus supports. We will process a WebSphere MQ message with this flow so we need an MQInput node. The MQInput node is in the WebSphere MQ drawer. __12.
Open the WebSphere MQ drawer by clicking on it. If a drawer is open, it will close when clicked.
__13.
Highlight the desired node (MQInput).
__14.
Either drag it to the canvas or move the mouse to the canvas and click again.
Page 17
When a node is initially added, its name can be changed immediately by over-keying the default name – or – by entering a new value in the Node name field in the Description tab of the Properties. A “best practice” is to provide a new name for each node that is descriptive of the function that it provides. For most of the labs, you will be renaming the nodes. If you use the names as suggested it will make it easier to follow the lab guide. Another “naming convention” for MQInput and MQOutput nodes is to use the queue name that the node is accessing. __15.
Change the name of the node to XML_Input.
__16.
Press the Enter key to complete the rename.
The Queue name in the node properties must be set. The Basic tab should be selected. A Queue name is required and this is indicated by a message in red. __17.
Select the Basic tab in the Properties pane.
__18.
Enter LAB.IN as the Queue name. Queue names are case sensitive. All queue names in the labs are upper case.
Page 18
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__19.
Select the Description tab. This section is used for documentation. The name of the node may also be changed. The node name is shown in the message flow editor. It does not affect the operation of the message flow.
__20.
Enter Q:LAB.IN in the Short description field.
__21.
Enter your choice of text for the Long description (Getting Started is shown in the screen shot).
Page 19
__22.
Hold the mouse pointer over the node name.
The information in the Short description field is displayed. When there are multiple nodes on the canvas, if you move from node to node with the mouse, the same tab in the Properties will be displayed.
Page 20
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
The Trace node is in the Construction drawer. __23.
Open the Construction drawer by clicking it with the mouse.
__24.
Select the Trace node and place it on the canvas to the right of the XML_Input node. As shown in the example, when you place the cursor on a node name, a description is shown. You do not need to rename the Trace node.
__25.
Press the Enter key to accept the default node name (Trace).
Page 21
__26.
In the Basic tab, use the pull down list on the Destination field to select File.
__27.
In the File Path field, enter C:\XML_Input_Trace.txt.
The information in the Pattern box tells the node what information to produce in the trace output. If you type a line of raw text, it is echoed to the output. __28.
Enter a line of your choice in the Pattern box – no quotes are needed.
__29.
In the Pattern box, enter the string ${Root} exactly as indicated – this tells the trace node to dump out the entire contents of the message that enters the node. Important – the pattern uses curly braces, not parenthesis. The expression between the curly braces will be evaluated at run time.
Double-check that Destination is set to File, and that the Pattern is specified exactly as ${Root}! __30.
On the Palette, open the WebSphere MQ drawer.
__31.
Select an MQOutput node from the drawer.
__32.
Place it to the right of the Trace node.
Page 22
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__33.
While the node name is highlighted, enter Send_As_XML as the new name.
__34.
Press the Enter key to accept the new node name.
__35.
Click the Basic tab on the Properties tab.
__36.
Set the Queue name to LAB.SEND.AS.XML. Queue names are case sensitive. It is a Best Practice to separate words in the queue name with a dot.
__37.
Make sure you did not enter this information in the Queue manager name field!!
Page 23
Key Concept: Node Terminals
As you work with the various nodes, you will also be working with their Input and Output terminals. Input terminals are typically named In. Most nodes have an Output terminal named Out. They may have several others. Some of these will have common names such as Failure or Catch and others will be unique to that particular node. Some nodes allow you to define the terminals. The terminals are given a name when they are defined. The lab instructions will identify the Output terminal to be used when connecting nodes together. If you hover the mouse pointer over a terminal, a small popup will appear that identifies the name of the terminal. You will now wire the nodes together to create a logical path for the message to follow through the message flow. You want to wire the Out terminal of the XML_Input node to the In terminal of the Trace node. There are two techniques: One – position the mouse over the Out terminal (in the middle), click and drag to the target and click again. Two – right click on a node and select Create Connection. This is an example of a Terminal Selection presented as a result of the Create Connection. The rest of the Lab instructions show the first method for wiring. __38.
Right click on the XML_Input node.
__39.
Select Create Connection from the menu.
Page 24
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
Page 25
A list of the available Output terminals for this particular node type is shown __40.
Select the Out terminal.
__41.
Click OK.
You now have a “rubber-band” connector. __42.
Position the connector over the Trace node.
__43.
Click the left mouse button to anchor it, creating a connection between the two nodes.
__44.
Place your mouse pointer on the connection. A pop up a summary of “from-to” information will appear.
Page 26
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
The same steps will be used to make a connection from the Trace node to the Send_As_XML node. __45.
Right click on the Trace node.
__46.
Select Create Connection. This time you immediately get a “rubber-band” connector. No selection list of terminals is presented because there is only an Out terminal on the Trace node.
__47.
Position the mouse pointer over the Send_As_XML node.
__48.
Click the left mouse button to create the connection.
Your message flow should now look like the above diagram. Notice the small asterisk next to the message flow name. This indicates that the message flow has not been saved to disk.
__49.
It is time to save your work – hold down the Ctrl key and press the S key to save the message flow. You can also click on the “diskette” icon or use File Save to perform a save.
The following graphic will be used as a reminder when it is time to save your work.
Page 27
Testing the Flow The message flow is now complete. The next step is to send it to the runtime environment for testing. The integrated Test Client will be used to test the message flow. __1.
Select the MQInput node (which we called XML_Input).
__2.
Press the right mouse button.
__3.
Select Test… from the menu.
__4.
Click OK to the popup.
Page 28
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
Take a moment to familiarize yourself with the Test Client:
Key Concept: Test Client Test Client instances can be created for MQ, JMS, HTTP, SOAP and SCA input nodes. They exist as a single file in the workspace with a .mbtest file extension. They can be embedded into the Applications or Libraries and thus passed from developer to developer with a project. The Test Client has many useful features such as monitoring all supported output paths through a flow and storing sample messages to a data pool. It also encapsulates the build and deploy process, and can be used to launch the debugger. Since it encapsulates a full test, including data, it can be used for regression testing.
Page 29
__5.
Page 30
Select Import Source…
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__6.
Navigate to the C:\student\Intro_XML_Message folder.
__7.
Select IN_Request file. The Type should be XML Document.
__8.
Click Open.
Page 31
The XML sample message is now loaded into the Test Client. __9.
Select the Configuration tab.
__10.
Select Deployment.
__11.
Click the Change button in Section 3: Deployment Location.
Page 32
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
Note that the local Integration Node (IB9NODE) and the Integration Server (default) are displayed. __12.
Select the default integration server.
__13.
Click Finish.
Page 33
Page 34
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__14.
Switch back to the Events tab.
__15.
Click the green Play button. (The Send Message button will also do the same thing.)
Page 35
What happened? We received an error when the Test Client attempted to launch. It could not connect to the queue and gives us a clue by asking whether or not it has been created. We did indeed forget to create our queues!
To create the queues, we will switch to the Administrator tool called the MQ Explorer, which includes Integration Bus Explorer (IBX) as well. __16.
Find the WebSphere MQ Alert Monitor in the Windows system tray.
__17.
Press the right mouse button.
__18.
Select WebSphere MQ Explorer from the menu.
Page 36
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
Take a moment to familiarize yourself with the Explorer. This tool will be used again in later labs.
Key Concept: Integration Explorer (sometimes also called MQ Explorer) The Integration Explorer is a lightweight eclipse tool for the administration of your Integration Bus and MQ topology. Technically, the Integration Explorer is an extension to the MQ Explorer that adds Integration Bus administrative capabilities to the tool. A few examples of these tasks include adding/modifying/deleting Brokers, access control, the deployment and modification of Apps and Libraries, viewing Administrative and Event logs, and administering the MQ Pub/Sub engine.
Page 37
__19.
Expand IB9QMGR (if necessary).
__20.
Right click on the IB9QMGR Queues folder.
__21.
Select New Local Queue.
Page 38
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__22.
In the dialog, for the Name of the queue, enter LAB.IN.
__23.
Click Finish.
Page 39
__24.
Click OK to close the dialog. The dialog confirms that the queue was created successfully.
Now we are ready to retry the Test Client. __25.
Switch back to the Test Client in the WebSphere Message Broker Toolkit.
__26.
On the left, select the Event called Invoke Message Flow.
__27.
Press the right mouse button.
__28.
Select Re-run from the menu.
Page 40
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
This time it runs to completion. Recall that the output from our flow was a queue. By selecting the event starting with MQ Queue Monitor…, we see the output message. In other words, the Test Client did a “GET” operation off of the output queue and displays the message.
Page 41
__29.
Select File Save to save the IntroLab.mbtest test client configuration.
__30.
In the dialog that appears, select the IntroLab application.
__31.
Click Finish.
Page 42
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
The output of the Trace Node in the file system will be examined next. __32.
Bring up Windows Explorer.
__33.
Select the Local Disk (C:) folder (root directory).
__34.
Double click on XML_Input_Trace.txt.
Page 43
Viewing the contents of the trace file you can see the line of raw text you configured for the Trace node to display, as well as some detailed information about the message. __35.
To see the actual payload or application data scroll down to the bottom (Ctrl+End).
Hmmmm…what’s going on here? The message is a BLOB – a Binary Large Object. Just a string of bytes shown in hexadecimal. What happened to the XML message? Where are the tags? What about the data! All will be resolved soon!
__36.
Close the Notepad window.
__37.
Minimize the Windows Explorer window.
Each time that you test the message flow new data will be appended to the end of the trace file. You will need to scroll down to the end of the file to see the latest information.
This is the end of Lab 1.
Page 44
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
Lab 2
Message Models and Working with XML Messages
Overview In this lab, the IntroMessageFlow will be modified to identify the parser (XMLNSC) to be used to process the message. The steps are very simple. The properties of the Input node will be modified. The Test Client will be used to run another test. The trace file contents will be viewed to see the difference.
Using the XML Parser __38.
Return to the IBM Integration Toolkit.
__39.
Click on the IntroMessageFlow tab to bring the message flow into view.
__40.
Click on the XML_Input node to bring its properties into view.
Page 45
The message flow will be modified so that it uses the XMLNSC parser to process the input message. __41.
On the Properties view at the bottom of the screen, click the Input Message Parsing tab. Since nothing was specified when the node was added, the Message domain (i.e. the parser) defaults to BLOB – which you saw in the trace.
__42.
Click the pull-down for the Message domain. The various parsers are listed along with a short description. Depending on the Message domain selection, the other fields may be enabled or disabled.
__43.
Select the XMLNSC parser. The XMLNSC parser that supports Namespaces (the NS part) and builds a more efficient or compact tree (the C part). The compact tree uses less memory.
__44.
Save the message flow (Ctrl+S).
Key Idea: Parsers and Message Domains IBM Integration Bus supplies a range of parsers to parse and write messages in different formats. A parser is called when the bit stream that represents an input message must be converted to the format that is used internally by the broker; this process is known as parsing. The input is a bit stream, and the output is a logical tree representation of the message. A serializer is called when a logical tree structure must be converted into a bit stream (for example on an Output node). This process is known as serializing. Each parser is suited to a particular class of messages, known as a message domain. The following list contains some examples of the message domains used in IBM Integration Bus: • • • •
XMLNSC – for XML documents DFDL – for general text or binary data streams including industry standards JSON – for JSON documents DataObject – for data without a stream representation (used by adapters)
Page 46
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
Now, let’s re-run the Test Client. __45.
Switch back to the Test Client (IntroLab tab).
__46.
Select one of the Invoke Message Flow items.
__47.
Press the right mouse button.
__48.
Select Re-run from the menu.
Page 47
You again see the same output message from the Test Client.
This is only what the output message looks like after it arrives on the output queue. Let’s see what the message looked like while it was passing through the message flow.
Page 48
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__49.
Return to Windows Explorer.
__50.
Navigate to the file at C:\XML_Input_Trace.txt.
__51.
Double click on XML_Input_Trace.txt file.
Page 49
Scroll to the end of the file (Ctrl + End).
__52.
Trace output is placed at the end of any existing content in a file so scroll down to the bottom of the file and view the results. Much more pleasing…here is a nicely formatted message tree that will allow you to conveniently access the fields in the XML message by name. Notice: •
The XMLNSC Domain name (which is what we set on the input node).
•
All of the element types are String represented by the (CHARACTER)! Why is that? The answer requires understanding both Parsers and Message Models.
__53.
Close the Notepad window.
__54.
Minimize Windows Explorer.
Page 50
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
Creating a Message Model from an XSD In this portion of the lab, we will use a message model to parse the XML message. Key Idea: Message Models Much of the business world relies on the exchange of information between applications. This information is contained in messages that have a defined structure that is known and agreed by the sender and the receiver. Applications typically use a combination of message formats, including those message formats that are defined by the following structures or standards: • • • •
Comma Separated Values (CSV) COBOL, C, PL1, and other language data structures Industry standards such as SWIFT, X12 or HL7 XML including SOAP
You can model a wide variety of message formats so that they can be understood by IBM Integration Bus message flows. When the message format is known, the broker can parse an incoming message bit stream and convert it into a logical message tree for manipulation by a message flow. Some message formats are self-defining and can be parsed without reference to a model. However, most message formats are not self-defining, and a parser must have access to a predefined model that describes the message if it is to parse the message correctly. An example of a self-defining message format is XML. In XML, the message itself contains metadata in addition to data values, and it is this metadata that enables an XML parser to understand an XML message even if no model is available. Another example of a self-defining format is JSON. Examples of messages that do not have a self-defining message format are CSV text messages, binary messages that originate from a COBOL program, and SWIFT formatted text messages. None of these message formats contain sufficient information to enable a parser to fully understand the message. In these cases, a model is required to describe them. Even if your messages are self-defining, and do not require modeling, message modeling has the following advantages: • •
•
• • •
Runtime validation of messages. Without a message model, a parser cannot check whether input and output messages have the correct structure and data values. Enhanced parsing of XML messages. Although XML is self-defining, all data values are treated as strings if a message model is not used. If a message model is used, the parser is provided with the data type of data values, and can cast the data accordingly. Code completion assistance when coding transformation. When you are creating ESQL programs for your message flows, the ESQL editor can use message models to provide code completion assistance. Graphical mapping. Without message models, you cannot use the Message Mapping editor. Reuse of message models, in whole or in part, by creating additional messages that are based on existing messages. Generation of documentation.
Page 51
•
Provision of version control and access control for message models by storing them in a central repository.
Message models allow the full use of the facilities that are offered by IBM Integration Bus. To speed up the creation of message models, importers are provided to read metadata such as C header files, COBOL copybooks, and EIS (Enterprise Information System, such as SAP®) metadata, and to create message models from that metadata. Additionally, predefined models are available for common industry standard message formats such as SWIFT, EDIFACT, X12, FIX, HL7, and TLOG. The XML Parser was run in programmatic mode where it parsed the XML message, so it assumed everything was a string. By parsing with a model, we can get a message with typed elements and one that is subject to constraints (such as required fields, max field lengths, etc.). The toolkit provides wizards to import your existing models (such as WSDLs, XSDs, copybooks, etc.) __55.
In the Application Development view (project navigator) on the left, right click the whitespace.
__56.
Select New Message Model… from the menu.
Page 52
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__57.
Select the Other XML radio button (under XML).
__58.
Check out some of the other options for which there are import wizards.
__59.
Click Next.
Page 53
__60.
Select the I already have an XML schema for my data radio button.
__61.
Click Next.
Page 54
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__62.
Click the New.. button next to the Application or Library field.
Page 55
__63.
In the popup dialog, select Library.
__64.
Click OK.
__65.
In the popup dialog, type IntroLabLib as the Library name.
__66.
Click Finish.
Page 56
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__67.
Back in the Message Model wizard, check the radio button Select file from outside workspace.
__68.
Click Browse…
Page 57
__69.
Navigate to C:\Student\Intro_XML_Message folder.
__70.
Select IN_Request.xsd.
__71.
Click Open.
Page 58
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__72.
Back in the Message Model Wizard, click Finish.
Page 59
You now have a Library project with the XML message model for the input message.
Key Idea: Library Projects Applications and libraries are deployable containers of resources, such as message flows, message definitions (DFDL, XSD files), JAR files, XSL style sheets, and WebSphere Adapters files. A library is a logical grouping of related code, data, or both. A library contains references to reusable resources, such as a message model or map. A library can refer to a resource that is contained in another library. Libraries are optional. They are typically used to reuse resources. Libraries can be either embedded in an application (private) or obtained by a message flow (that is not part of an application) dynamically at run time (execution group level). Use multiple libraries to group related resources (for example, by type or function). Consider using libraries if you want to share routines and definitions across multiple teams, projects, or brokers. Libraries are also useful if you need to use different versions of a coherent set of routines and definitions. Using a library is typically not necessary if you do not need to regularly reuse IBM Integration Bus routines or definitions.
Page 60
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
Notice that the XSD is opened for you after import and is visible using the XML Schema Editor, an editor in the toolkit which shows you both a GUI representation of your XML schema as well as the source. In_Request is the only Global element. If you double click on it, you can drill down into its structure. __73.
Double click on the In_Request element to view the message elements.
The message model should now be visible.
__74.
Select the Detailed view.
Page 61
Some elements, such as customerNumber and customerCreditScore, are integers (ints) and not strings.
__75.
Close the IN_Request.xsd tab.
Now, let’s update the message flow to use the message model when parsing incoming messages. __76.
In the project view on the left, select the IntroLab application.
__77.
Press the right mouse button.
__78.
Select Manage Library references.
Page 62
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__79.
Select the IntroLabLib check box.
__80.
Click OK.
We need to tell the parser to run in schema-driven mode, rather than operate in programmatic mode. __81.
Click on the Intro_MessageFlow.msgflow tab to return to the message flow editor.
Page 63
__82.
Single click on the XML_Input node, in order to edit its properties.
__83.
In the Properties view, click on the Validation tab.
__84.
In the Validation dropdown, select Content.
__85.
Select the Parser Options tab.
__86.
Select the Build tree using XML schema data types check box.
__87.
Page 64
Save the message flow (Ctrl+S).
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
Re-running the Test Client The flow will now be run again. The trace output will then be examined. __88.
In the editor, select the IntroLab.mbtest tab (or re-open from the App in the navigator).
__89.
Right click Invoke Message Flow.
__90.
Click Re-run.
The tooling will automatically re-build and redeploy the App with the dependent Library included.
Page 65
__91.
Return to the Windows Explorer window.
__92.
Double click the C:\XML_Input_Trace.txt file.
__93.
Scroll down to the end of the file (or use Ctl+End), and view the new trace output.
__94.
Close the Notepad window.
__95.
Minimize Windows Explorer.
Page 66
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
This is the end of lab 2.
Page 67
Lab 3
Content Based Routing and the Debugger
Overview In this lab, you will perform simple routing. Input messages will be sent to one of three destinations depending on the country code. Addresses in the United States will be sent to a US shipping queue, while addresses in Canada will be sent to a Canadian shipping queue, and those that are not in the United States or Canada will be sent to a third queue.
Add Routing Logic __1.
Return to the Integration Bus Toolkit.
__2.
Select the IntroMessageFlow message flow in the message flow editor.
__3.
Select the Trace node.
__4.
Press the Delete key.
Page 68
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__5.
Expand the Routing drawer in the Palette.
__6.
Select a Route node and place it between the XML Input and Send_As_XML nodes.
__7.
Change the name of the new routing node to CheckCountry.
__8.
Press the Enter key to complete the rename operation.
__9.
Wire the Out terminal of the XML_Input node to the In terminal of the CheckCountry node.
__10.
Wire the Default terminal of the CheckCounty node to the Send_As_XML node.
Page 69
Terminals will now be added to the CheckCountry routing node for US and Canadian addresses. __11.
Select the CheckCountry route node.
__12.
Press the right mouse button.
__13.
Select Add Output Terminal from the menu.
__14.
Enter US as the name of the new output terminal.
__15.
Press the OK button to continue.
The steps will now be repeated to add a terminal called Canada. __16.
Select the CheckCountry node.
__17.
Press the right mouse button.
__18.
Select Add Output Terminal from the menu.
__19.
Enter Canada as the name of the new output terminal.
__20.
Press the OK button to continue.
Page 70
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
Two additional output destinations will now be added. One will be for addresses within the United States and a second one will be for addresses within Canada. All other addresses will be sent to the existing output queue. __21.
On the Palette expand the WebSphere MQ drawer.
__22.
Select an MQOutput node.
__23.
Place the new node below the Send_As_XML node.
__24.
Change the name of the node to LAB.US.OUT
__25.
Press the Enter key to complete the rename operation.
__26.
In the Properties pane select the Basic tab.
__27.
Enter LAB.US.OUT as the Queue name parameter.
Page 71
__28.
Select the MQOutput node in the WebSphere MQ drawer again.
__29.
Move the mouse pointer to a point below the LAB.US.OUT node.
__30.
Press the left mouse button to place the new node below the LAB.US.OUT node.
__31.
Change the name to LAB.CANADA.OUT.
__32.
Press the Enter key to complete the rename operation.
__33.
In the Properties pane select the Basic tab.
__34.
Enter LAB.CANADA.OUT as the Queue name parameter.
__35.
Right click the CheckCountry route node.
__36.
Select Create Connection from the menu.
Page 72
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__37.
In the Terminal Selection popup, select US.
__38.
Click OK.
__39.
Drag the wire that appears to the LAB.US.OUT node.
__40.
Press the left mouse button to complete the connection.
__41. Another way to make a connection is just to click on the terminal itself. Try this by selecting the output terminal of the CheckCountry node. __42.
Press the left mouse button.
Page 73
Since there are too many terminals to individually depict graphically, a dialog box appears allowing you to select the proper terminal. __43.
Select the Canada terminal.
__44.
Press the OK button.
__45.
Drag the wire that appears to the LAB.CANADA.OUT node.
__46.
Press the left mouse button to complete the connection.
Page 74
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
The criteria to be used by the CheckCountry routing node must now be specified. __47.
Select the CheckCountry node.
__48.
In the Properties pane select the Basic tab.
__49.
Press the Add button.
__50.
Use the drop down menu to select the US terminal as the Routing output terminal.
__51.
Press the Edit… button.
Page 75
__52.
Expand $Root.
__53.
Select (Add Data Type …).
Page 76
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__54. Select In_Request. Note: If you do not see In_Request in the list, then you must add a reference to the Library by right clicking the IntroLab application and selecting Manage Library references. __55.
Press the OK button to continue.
Page 77
__56.
Expand the tns:In_Request customerDetails elements.
__57.
Select the customerCountry element and drag it into the XPath Expression dialog box.
Page 78
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__58.
Drag an equal sign from the Operators pane to the end of the expression.
__59.
Append the letters ‘US’ (including the single quotes) after the equal sign.
__60.
Press the Finish button to complete the XPath expression.
Page 79
__61.
Press the OK button to complete the Filter table entry.
The filter pattern for the US terminal should now be visible. The process will now be repeated to create a Filter table entry for the Canada terminal. __62.
Page 80
Press the Add button to enter a filter pattern for the Canada terminal.
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__63.
Use the drop down menu to select the Canada terminal as the Routing output terminal.
__64.
Press the Edit… button.
Page 81
__65.
Expand Root tns:In_Request customerDetails. Tip: If you do not see In_Request in the Viewer, re-add it as done in steps 53-56.
__66.
Select the customerCountry field and drag it to the XPath Expression window.
Page 82
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__67.
Complete the XPath Expression by typing =’CA’.
__68.
Press the Finish button to complete the XPath expression.
Page 83
__69.
Press the OK button to complete the Filter table entry.
The filter pattern for the Canada terminal should now be visible.
The updates to the message flow are now complete. __70.
Page 84
Save the message flow.
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
Test with the Debugger Next, we are going to test the application with the graphical debugger.
Key Idea: The Graphical Debugger Use the flow debugger in the IBM® Integration Bus Toolkit to track messages through your message flows. Use the Debug perspective in the IBM Integration Toolkit to use the flow debugger. The diagram above introduces the Debug perspective and the views it presents. You can set breakpoints in a message flow, and then step through the flow. While you are stepping through, you can examine and change the message variables and the variables used by ESQL code and Java code. You can debug a wide variety of error conditions in flows, including the following: •
Nodes that are wired incorrectly (such as outputs that are connected to the wrong inputs)
•
Errors in transformation or logic within your code or maps
•
Incorrect conditional branching in transition conditions
•
Unintended infinite loops in flow
Page 85
From a single IBM Integration Toolkit, you can attach the debugger to one or more integration servers, and debug multiple flows in different integration servers (and therefore multiple messages) at the same time. However, an integration server can be debugged by only one user at a time. Therefore, if you attach your debugger to an integration server, another user cannot attach a debugger to that same integration server until you have ended your debugging session. By default, the debugger is disabled. The first time you use it you must enable it and assign a port. The recommended port number is 14999. The next few steps will walk you through this one-time task.
Page 86
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__1.
In the Integration Toolkit, go to the Integration Nodes view in the bottom left, right click on the Integration Server called default., and select Launch Debugger (Port is 0).
__2.
Click Configure…
__3.
Specify a port number of 14999, and click OK.
Page 87
__4.
A pop-up will occur while the port is being set.
__5.
This pop-up will appear once the port has been set.
__6.
The debugger will be launched. Once complete, this pop-up will occur:
Page 88
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__7.
Return to the message flow editor, right-click the wire between the XML_Input node and the Check Country route node.
__8.
Select Add Breakpoint from the menu.
__9.
In the main editor view, bring into focus the IntroLab Test Client.
__10. Along the bottom of the Test Client select the Configuration tab.
Page 89
__11.
Page 90
Along the right within the Deployment Location section, click the box called Change.
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__12.
In the popup dialog, select the checkbox labeled Trace and Debug.
__13.
Press the Finish button.
The debugger will now run next time the Test Client is run.
Page 91
__14. Switch back to the Events tab. __15. Right click on the last Invoke Message Flow in the Message Flow Test Events. __16. Select Duplicate from the menu.
Page 92
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__17. In Detailed Properties, the Body should now show Edit as text. If not, use the drop down to select it.
Page 93
__18. Edit the input message. Locate the customerCountry element. __19. Change the data value to US. __20.
Run the test client by clicking Send Message.
A popup will confirm switching the eclipse perspective to the Debug perspective. __21.
Page 94
Press the Yes.
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__22. Ensure that the IntroMessageFlow thread is selected in the top left view. You should see a yellow halo around the breakpoint. The yellow halo indicates that this is where execution of the flow has been suspended.
__23. In the top right Variables view, expand Message XMLNSC In_Request customerDetails. __24. You will see the value is set to US.
Page 95
__25. To interactively change this, single click the Value column of the customerCountry element. __26. Change the value in the editor box to CA. __27. Press Enter to update the value.
Page 96
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__28. Right click on the wire between the CheckCountry node and the LAB.CANADA.OUT node. __29. Select Add Breakpoint from the menu.
__30. Select the Step Over button along the actions menu panel to run the Route node logic. Alternatively, you can press F6 to step over.
__31. Verify that the Route node has sent the message down the Canada terminal.
__32. Select Resume or Step Over to finish the flow (or press F8 or F6, respectively).
Page 97
You can now re-run the test without overriding the customerCountry element in order to validate the path to the LAB.US.OUT queue. Return to the Integration Development perspective and the Test Client, and “Re-run” the last Invoke Message Flow. __33. When finished testing the debugger (the debugger should be in a terminated state), right click on the Debug perspective. __34. Select Close from the menu.
Page 98
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
A Closer Look at the Deployment Process Up to this point, we have been utilizing the Test Client to initiate our unit testing and it has been handling the deployment process for us “under the covers”. To finish this lab, we will briefly examine the deployment process and manually do our own deploy. Key Idea: The Deployment Process When you create application resources such as message flows in the IBM® Integration Toolkit, you must distribute them to the nodes on which you want them to run. Data for message flows and associated resources is packaged in a broker archive (BAR) file before being sent to the node. You can initiate a deployment in the following ways: • • • •
From the IBM Integration Toolkit From the Integration Explorer By using the mqsideploy command By using functions defined by the Integration Bus CMP API
Depending on your work patterns, you might use all these methods at different times. The Integration Toolkit provides a Nodes view in the lower left hand corner of the Integration Development perspective. If you expand a integration node, all the integration servers in that node are displayed, as well as deployed message flows and their associated resources. You can drag an Application or Library, message flow, or a broker archive (BAR) file from the Application Development view onto an execution group to deploy it. Alternatively, you can right click on an execution group to select an Application or Library, message flow, or BAR file to deploy to the selected execution group. If you are working with an application and want to deploy and test it quickly, you can deploy just that resource. Drag the resource onto the execution group to which you want to deploy it. A BAR file is generated automatically, and deployed to the node. If libraries are referenced, they are added automatically to the BAR file and deployed. If a message flow contains a subflow that is defined in a “.subflow” file, the subflow is automatically included in the BAR file, and deployed with the message flow. If you drag a flow that is contained in an Application or Library, you will see a message saying that the whole application or library will be deployed, because you cannot deploy a message flow on its own if it belongs to an Application or Library. Key Idea: The BAR file The unit of deployment to a Broker is a BAR file. It is a .zip file which contains the flows, models, .jar files, maps, and any other resources in the workspace needed to run your Applications. The BAR file also contains a deployment descriptor .xml file, which exposes flow and node properties for override at build or deploy time. The following sequence of events illustrates how to deploy with a BAR file: 1. Create a broker archive. 2. Add files to the broker archive. 3. If necessary, you edit the configurable properties of the message flows or applications in the broker archive. 4. Deploy the BAR file by sending it to the broker, from where its contents are distributed to the integration servers.
Page 99
A BAR file can be deployed in two ways: • Incremental BAR file deployment. Deployed files are added to the execution group. Files that exist in the execution group are replaced by the new version. •
Complete BAR file deployment. Files that are already deployed to the execution group are removed before the entire contents of the BAR file are deployed. Therefore, nothing is left in the execution group from previous deployments.
__1.
Return to the Integration Development perspective in the toolkit.
__2.
Select a blank area in the Navigation view on the left.
__3.
Press the right mouse button.
__4.
Select New BAR file from the menu.
Page 100
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__5.
Enter Lab3 as the name of the new broker archive file.
__6.
Select Finish.
__7.
In the BAR editor, select the IntroLab Application.
__8.
Click the Build and Save… button.
Page 101
__9.
If prompted to Save, click Yes.
__10.
Press the OK button.
Page 102
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__11.
In the BAR editor, select the Manage tab.
__12.
Expand the IntroLab app and select the various resources.
__13.
Look at the Properties view below to see what properties are exposed in order to be overridden within the BAR file. For example, select the LAB.US.OUT node. You can see that the Queue Name property can be overridden at deployment time.
Page 103
__14.
To deploy, find the Lab3.bar file in the navigator in the BARs container.
__15.
Drag and drop it onto the default integration server of the IB9NODE.
__16.
Once deployment is complete, click the default integration server to open it to see the assets deployed to it. The IntroLab application has been deployed, which included the Intro_MessageFlow message flow and the library was included, which contains the IN_Request XML Schema.
Finally, the Test Client will be updated to use this BAR rather than generating its own. __17.
In the editor, select the Test Client.
Page 104
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__18.
Select the Configuration tab.
__19.
Select the Deployment tab.
__20.
On the right inside the Specify Broker Archive box, select Browse.
Page 105
__21.
In the dialog box, select Lab3.bar.
__22.
Click OK.
__23.
__24.
Save the Test Client.
Close all the open editor tabs but leave the toolkit running.
This is the end of Lab 3.
Page 106
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
Lab 4
Using Publish/Subscribe with IBM Integration Bus
Overview In this lab you will explore how IBM Integration Bus can interact with and extend the Publish/Subscribe capabilities of WebSphere MQ in a number of useful and powerful ways. You will explore this by implementing a business scenario for a fictitious company called JK Enterprise. The scenario is this: The JK Enterprise division responsible for issuing lines of credit to preferred customers has been instructed to more closely scrutinize customers with lines of credit that have a credit rating below a certain number. Historically, JK Enterprise’ credit division has automatically extended credit to existing customers with a good payment history who have a FICO credit rating of at least 500. It was decided to continue this practice, but to do additional monitoring when customers have a credit rating below 650. A separate process will be set up to perform this monitoring, in the form of a COBOL program to which credit-related messages are to be directed. A message flow to generate messages related to credit activity will be completed. The message flow accepts both message and file inputs. This would allow other applications to use this capability later. A Publication node will be used to publish the credit activity messages. Subscriptions will be registered using different content filters to specify the particular messages the monitoring programs are interested in (e.g. credit requests that have been Approved and that have a FICO rating between 500 and 650). In this lab, a Mapping node and a Publication node will be added to a skeleton flow that is provided. The final result should look like the following when complete.
Page 107
__25.
Go to the Windows Start menu and expand All Programs. Locate and expand the “IBM Integration Toolkit” folder, and click on Integration Toolkit 9.0.0.2 to launch the IIB Toolkit.
__26.
Press the Browse button to locate the workspace to use.
Page 108
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__27.
Navigate to the C:\student\ps\workspace directory.
__28.
Press the OK button.
__29.
Press the OK button to open the selected workspace.
In the Navigator view you should see the project folders shown above. An Application project folder (PubSubLab) and a Library project folder (PubSubLabLIB) have been provided for you as part of this lab. The Application project folder contains a message flow that is partially constructed, which you will complete as part of this lab. The Library project folder
Page 109
contains an MRM message definition that serves as a model for the messages that will be processed by the flow.
Page 110
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__30.
Expand the folders for these projects, as shown below.
__31.
Notice that message flow PubSubLabMsgFlow and message definition JKE_Account have been provided for you.
__32.
Open the PubSubLabMsgFlow message flow by double clicking on it.
Page 111
__33.
Open the Routing drawer in the Palette.
__34.
Select a Publication node and position it to the left of the PUBSUB.NOHIT node.
Page 112
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__35.
Open the Transformation drawer in the Palette.
__36.
Select a Mapping node.
__37.
Drag the mapping node to the left of the Publication node as shown.
__38.
Change the name of the node to SetTopic.
Page 113
Your message flow should now look something like the above. The Mapping node will be used to assign the topic to which the message is to be published, as well as some additional control information. The Publication node will communicate with WebSphere MQ to publish the messages on the specified topic. __39.
Double-click the SetTopic Mapping node. The Mapping wizard is launched.
Page 114
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__40.
Verify that the Container is PubSubLab and the Map name is PubSubLabMsgFlow_SetTopic, and click Next.
__41.
Expand the PubSubLabLIB folder for both map inputs and map outputs, as shown above.
__42.
Select the msg_JKEACCOUNTREQUEST message definition for both the map input and map output by clicking on the respective check boxes, as shown above. Then click Next.
Page 115
__43.
Verify that the Output domain is MRM. Then click Finish.
__44.
Note that the Properties folder is automatically mapped, something that is normally very helpful. In this case the mapping must be modified slightly to override one of the properties – the default Topic property must be overridden with the value to be used in this lab. You will do this in the next few steps.
Page 116
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__45.
In the output Message Assembly (on the right-hand side of the mapping editor), expand the Properties folder, and locate the Topic property.
Page 117
__46.
Right-click the Topic property, and in the Context menu click Create Assign. An Assign mapping will be created in the center of the editor. Assign mappings are used to assign fixed values to map fields.
Page 118
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__47.
Click on the Properties tab at the bottom of the editor, and in General properties, in the Value field, enter account/credit.
__48.
Now take a closer look at that Assign mapping object.
__49.
Note the alert icons in the upper left. The The
icon indicates that there is an error in the map.
icon indicates that there are suggestions available for how to correct the error.
Page 119
__50.
Hover the mouse pointer over the
icon.
__51.
The error message associated with the alert is displayed.
What’s the problem? The Mapping editor has determined that there is already an action specified for this property – do you recall the Move mapping that was automatically created for the entire Properties folder when you originally opened the Mapping node? The Mapping editor does not know how this custom mapping should be handled relative to the mapping that was automatically generated. __52.
Now hover the mouse pointer over the
__53.
Suggestions are provided as to how to correct this error.
__54.
Click on the first suggested quick fix (“Group the conflicting transforms in an override group”).
Page 120
icon.
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
The quick fix is applied automatically, in the form of an Override Group that combines the mapping actions, with the Assign mapping of the Topic value being applied after the Move mapping that was automatically created for the entire Properties folder. The Topic property has been set to the topic string to which you intend to publish. In many cases this is all that is needed to publish messages. However, recall the scenario outlined at the start of this lab: • Subscribers are written in COBOL and expect a flat message format • Subscribers will use content filters to filter the publications they are interested in. To satisfy these subscriber requirements, the publisher (your message flow) must include some additional control information, to be used by IBM Integration Bus at publication time, to decide whether or not a given publication should be delivered to a particular subscriber. To do that, some properties must be added to the message to be published, in the form of an MQ RFH2 header. You will use this same message map to do this.
Page 121
__55.
Click on the output Message Assembly (on the right-hand side of the Mapping editor), and in the Properties view at the bottom of the editor click the Properties hotspot for Headers and folders.
Page 122
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__56.
In the Add or Remove Headers and Folders dialog window, expand the MQ Headers folder.
__57.
Expand the MQRFH2 header folder.
__58.
Select the checkbox for the MQRFH2C parser item. Note that the MQMD will be selected automatically when an RFH2 header is added.
__59.
Press the OK button.
__60.
In the Mapping editor, collapse the Properties folder in the output Message Assembly. You should now see MQMD and MQRFH2C folders beneath the output Properties folder.
Page 123
__61.
Expand the MQMD folder.
Page 124
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__62.
Right-click on the Format field of the MQMD, and in the Context menu click on Create Assign. An Assign mapping will be created in the center of the editor. Assign mappings are used to assign fixed values to map fields.
Page 125
__63.
Click on the Properties tab at the bottom of the editor, and in General properties, in the Value field, enter MQHRF2. Note! Be careful that the value is entered correctly – MQHRF2 is the correct spelling!
Page 126
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__64.
In the output Message Assembly, in the MQMD folder, right-click on the Version field, and in the Context menu click on Create Assign. An Assign mapping will be created in the center of the editor. Assign mappings are used to assign fixed values to map fields.
Page 127
__65.
Click on the Properties tab at the bottom of the editor, and in General properties, in the Value field, enter the number 2 The MQMD changes are complete.
Page 128
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__66.
Collapse the MQMD folder in the output Message Assembly, and expand the MQRFH2C folder.
In the following steps you will be setting some control information in the RFH2 header to allow subscribers to take advantage of a feature of WebSphere MQ and IBM Integration Bus called Extended Message Selection.
Page 129
Key Idea: Extended Message Selection Most messaging providers, including WebSphere MQ, support the concept of message selectors. A WebSphere MQ message selector is a string with syntax that is based on a subset of the SQL92 conditional expression syntax. Applications can subscribe to a topic, but then qualify that subscription using a message selector, enabling the application to limit the stream of publications to only those messages that have properties that satisfy the query that the selection string represents. WebSphere MQ provides an interface that allows Extended Message Selection, which enables providers to extend the capabilities and scope of message selection beyond what WebSphere MQ itself provides. IBM Integration Bus leverages this feature to enable subscribers to specify message selectors that reference not only message properties, but the message payload content as well. This capability (sometimes referred to as content filtering) enables subscribers to be very specific as to which messages they are interested in having delivered to them, eliminating the network and application server overhead of having messages delivered to a subscriber that will in turn simply discard them. If a message is not using a self-defining structure such as XML, the publisher must provide information for IBM Integration Bus to use when evaluating Extended Message Selectors on behalf of subscribers. The following steps demonstrate how this can be done.
__67.
In the input Message Assembly, click on the Properties folder (on the left-hand side of the editor), drag it to the mcd folder of the RFH2 (on the right-hand side of the editor), and drop it.
Page 130
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__68.
A Local map mapping is created in the center of the editor, along with the pop-up as shown above. You will use this local, or nested map, to create the mappings from the input Properties folder to the mcd folder of the RFH2 header in the output message assembly. Click on the “Click here to edit the nested map” link.
Page 131
__69.
In the mcd folder (on the right-hand side of the editor), right-click on the Msd field, and in the Context menu click on Create Assign. An Assign mapping will be created in the center of the editor. Assign mappings are used to assign fixed values to map fields.
Page 132
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__70.
Click on the Properties tab at the bottom of the editor, and in General properties, in the Value field, enter MRM
Page 133
__71.
Click on the MessageSet input property (on the left-hand side of the editor), drag it to the Set property in the mcd folder of the RFH2 (on the right-hand side of the editor), and drop it. Note that a Move mapping is created in the center of the editor.
Page 134
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__72.
Repeat this step for the MessageType input property (on the left-hand side of the editor) - drag it to the Type property in the mcd folder of the RFH2 (on the right-hand side of the editor), and drop it. Note that another Move mapping is created in the center of the editor.
Page 135
__73.
Repeat this step once again for the MessageFormat input property (on the left-hand side of the editor) - drag it to the Fmt property in the mcd folder of the RFH2 (on the right-hand side of the editor), and drop it. Note that another Move mapping is created in the center of the editor.
Page 136
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__74.
Verify that the local map looks like the above screenshot. Input Properties MessageSet , MessageType and MessageFormat (on the left-hand side of the editor) should each have a connector to a Move mapping (in the center of the editor), and these in turn should have connectors to the Set, Type and Fmt properties in the mcd folder of the RFH2 (on the right-hand side of the editor). In addition, there should be an Assign mapping connected to the Msd property. With the local map complete, click the small gold to the parent map.
on the right side of the editor map to return
Page 137
__75.
The last step is to create a mapping between the input and output payloads. Click on the msg_JKEACCOUNTREQUEST folder in the input Message Assembly (on the lefthand side of the editor), drag it to the msg_JKEACCOUNTREQUEST folder in the output Message Assembly (on the right-hand side of the editor), and drop it. Note that Move mapping is created in the center of the editor. The map is now complete.
__76.
__77.
the map.
Close the Mapping Editor.
Page 138
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
The new nodes will now be wired into your message flow, as shown here. __78.
Connect the Out terminal of the PUBSUB.IN node to the In terminal of the SetTopic node.
__79.
Connect the Out terminal of the FileInput node to the In terminal of the SetTopic node.
__80.
Connect the Out terminal of the Set Topic node to the In terminal of the Publication node.
__81.
Connect the NoMatch terminal of the Publication node to the In terminal of the PUBSUB.NOHIT node.
__82.
Click on the Publication node to display its properties. The Properties sheet for the Publication node has very few properties. That’s because Publish/Subscribe is highly dynamic. The relationship between publisher and subscriber is established when subscriber(s) register, not when the message flow is constructed. The properties that are available are for specialized purposes that are not being used in this lab.
__83.
the message flow.
Page 139
__84.
To deploy this solution, the supplied Broker Archive (BAR) file must be rebuilt. To do this, return to the Navigator pane at the upper left of the Toolkit, expand the BARs folder, right-click on the PubSubLab.bar file, and select Build and Save Broker Archive from the context menu.
__85.
Click OK to continue. The BAR file will be built and saved.
Page 140
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__86.
Now you will deploy the BAR file. First, make sure that the Brokers view at the lower left side is visible, then click on the PubSubLab.bar BAR file, drag it to the default Integration Server under IB9NODE, and drop it.
__87.
Wait for the deployment to complete and the pop-up to disappear.
Page 141
__88.
When the deployment is complete you should see the PubSubLab Application, and the PubSubLabLIB Library, deployed to the default Execution Group.
__89.
Just as in the Development view, the PubSubLab Application and the PubSubLabLIB Library are containers. Click on the twisties next to each and expand their contents.
Page 142
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__90.
Inside the PubSubLab Application container you see the following: __a. The PubSubLab message flow __b. The PubSubLabMessageFlow_SetTopic map __c. The PubSubLabLIB Library which contains the MRM message definition for JKE_Account You also see another instance of the PubSubLabLIB Library, outside the PubSubLab Application. Why is this needed? Recall the business scenario described at the beginning of this lab – credit activity messages are to be published, to which subscribers will be registered using different content filters to specify the particular messages they are interested in. Since the subscribers are not implemented as part of the PubSubLab Application, any subscribers that use a content filter must have access to the MRM definition for JKE_Account - thus an instance of the message definition must also reside outside the PubSubLab Application container. The message flow is now configured for publish/subscribe and has been deployed. The next task is to explore the administrative interface for publish and subscribe in the WebSphere MQ Explorer.
Page 143
__91.
If it is not already running, launch the Integration Explorer: Go to the Windows Start menu and expand All Programs. Locate and expand the “IBM Integration Bus 9.0.0.2”, and click on the IBM Integration Explorer to launch the Integration Explorer.
Page 144
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__92.
Make sure the MQ Explorer – Content view is selected (on the right), then in the Navigator view (on the left) expand the IB9QMGR queue manager entry.
__93.
Click on Subscriptions.
__94.
If the system objects are not displayed select the Display System Objects icon (upper right).
This will display all active subscriptions currently registered with the queue manager.
Page 145
The subscriptions displayed can be filtered by specific topic or subscription name, topic string, users, etc. By default, all active subscriptions currently registered with the queue manager are displayed. You may see a different number of subscriptions as this is a dynamic environment. But you should see these two included. You can rearrange the columns if you want. Some subscriptions are used internally by the queue manager or broker for various functions. It is a best practice to not delete or modify these. Review the information in each column (you will have to scroll to the right): Subscription Name is a name that is assigned to a subscription when the subscription is created. Topic Name is an optional object that can be used to establish a subscription point within the topic hierarchy. Topic string is the topic this subscriber has registered an interest in. In these subscriptions you may see examples of the use of the topic level separator character “/”, which is used to provide a hierarchical structure to the topic space. You may also see examples of the single-level wildcard character ″+″, which matches one, and only one, topic level. And you see examples of the multilevel wildcard character ″#″, which can be used to match any number of levels within a topic. Wildcard Usage allows the use of different wildcard characters. This is primarily for compatibility with older versions of WebSphere MQ. Destination Name identifies the queue that matching publications will be sent to.
Page 146
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__95.
To display only the user subscriptions (and not system subscriptions) select the Display System Objects icon again.
The system subscriptions should now be hidden (although you may still see some additional subscriptions present). You will now create some additional subscriptions for use in this lab.
__96.
You will be using the RFHUtil tool to register subscribers. You should have downloaded this to your workstation if you did not have it installed previously. Launch the tool either from the location your downloaded it to, or from the shortcut on the Windows Desktop if you created one. .
Page 147
The PS tab is used with publish and subscribe support introduced in Version 7 of WebSphere MQ. The “PubSub” tab is for supporting older pub/sub implementations. Note! You will not be making use of the “PubSub” tab in this lab- only the PS tab! __97.
When the RFHUtil tool is started, ensure that queue manager IB9QMGR is selected, and then click on the PS tab (not the PubSub tab) at the top.
Page 148
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__98.
You can use this view of RFHUtil to register a subscription.
__99.
Enter the Topic string account/credit, which is the topic the message flow will be publishing on.
__100. The Selection string field is where content filters can be entered. Leave that blank for now. It will be used later in the lab. __101. Use the drop down menu to enter PUBSUB.SUB1 as the subscription Queue name. This indicates where messages with matching publications will be delivered to. __102. Leave the Managed Sub and Durable Sub boxes unchecked. __103. Enter CreditSub1 as the subscription name. __104. Press the Subscribe button. This will register your subscription with the queue manager.
Page 149
Note! Be careful that the Topic name is entered in lower case, and the Subscription Queue name is entered in upper case.
The subscription should be created.
__105. Return to the WebSphere MQ Explorer, and select the Subscriptions folder (if necessary). You should now see the subscription you registered. It may be necessary to press the refresh button. As before, you may want to rearrange the columns so that your view approximates the screenshot above. Two additional subscriptions will now be created. This time content-based filters will be specified as part of the subscription. The content filters will refer to fields in the body of the message.
__106. Launch a second RFHUtil instance, using the shortcut on the Windows Desktop if you created one.
Page 150
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__107. As before, when the RFHUtil tool is started, click on the PS tab (not the PubSub tab) at the top.
Page 151
__108. Use the drop down menu to change the subscription Queue Name to PUBSUB.SUB2. __109. Change the Subscription Name to CreditSub2. __110. The Topic should be set to account/credit as in the previous subscription. __111. Enter Body.DECISION LIKE ‘Y’ in the Selection string field. Note! Be careful that the Filter is entered in exactly as shown, and the Subscription Queue name is entered in upper case. Tip: If you do not want to type the content filter, you can copy and paste the filter string from the file FilterExpression_2.txt, which can be found in the C:\student\ps\resource folder.
Page 152
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__112. Press the Subscribe button. The subscription should be created as shown.
__113. Launch a third RFHUtil instance.
Page 153
__114. When the RFHUtil tool is started, click on the PS tab (not the PubSub tab) at the top.
Page 154
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
One more subscription will be created. __115. Use the drop down menu to change the Queue Name to PUBSUB.SUB3. __116. The Topic should be set to account/credit as in the previous subscription. __117. Enter CreditSub3 as the Subscription Name. __118. For the Selection string enter the following: Body.DECISION LIKE 'Y' AND Body.CUSTOMER_DETAILS.CREDIT_SCORE BETWEEN 500 AND 650
Note! In the screenshot the filter is truncated on the left, so be certain you enter the entire filter expression! Tip: If you do not want to type the content filter, you can copy and paste the filter string from the file FilterExpression_3.txt, which can be found in the C:\student\ps\resource folder.
Page 155
__119. Click the Subscribe button to register your subscription; the subscription should be created as shown. This last subscription is the one that meets our requirements as stated at the beginning of this lab. The other two subscriptions are for demonstration purposes.
Page 156
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
Review what you have done up to this point.
__120. Switch to the WMB Toolkit. You have completed the message flow shown above to act as the publisher of messages that originate as either MQ messages or as records in a file. These will be published to the topic account/credit.
__121. Hover the mouse pointer over the RFHUtil icon in the Windows Quicklaunch toolbar. You will see the three RFHUtil instances you configured to act as subscribers to the topic account/credit.
__122. Return to the WebSphere MQ Explorer, and in the Navigator pane select Subscriptions.
Page 157
__123. You should see the three subscriptions. Note the names, and verify that the topic and destination (queue) names are registered correctly for each.
__124. Scroll to the right to view the content filters (selectors).Verify that the content filters are specified correctly. The publishing message flow and the subscribers are ready for testing. The following steps will test the scenario.
__125. In the MQ Explorer Navigator view, select the Queues folder for queue manager IB9QMGR.
__126. Verify that you have the highlighted queues defined and that their Current queue depth is zero. The changes will now be tested using the file input path of the message flow.
Page 158
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
Here is the file you will be using to test your subscriptions, AccountUpdate.batch. Note the following: •
There are ten records in the file.
•
Eight of these records have the Approved flag set to ‘Y’.
•
Of these, three records have a credit rating that falls into the range that was specified in the second content filter (these are on the far right, but because they are integer fields they cannot be read in this display).
Page 159
__127. To test the flow, open Windows Explorer and navigate to C:\student\ps\data directories. __128. Right-click the AccountUpdate.batch file. __129. Select Copy (not Cut).
__130. Paste the file into the C:\student\ps\files\Input directory.
Page 160
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
The FileInput node will detect the arrival of a file that meets its specifications and will process the individual records from the file. Each record will be sent to the Publication node.
Once the file has been processed, it will be removed from the Input folder.
Page 161
__131. Return to the MQExplorer display (note that it may take a few seconds for the file to be processed and the MQExplorer screen to refresh). Ensure that Queues is selected in the Navigator view. Here is what you should see, and why: •
PUBSUB.SUB1 should contain 10 messages, one for each record in the file (AccountUpdate.batch). All 10 records are here because no content filter was used in the subscription.
•
PUBSUB.SUB2 should contain 8 messages, one for each record in the file (AccountUpdate.batch) with a ‘Y’ in the Decision field. A content filter was used in the subscription to select only these messages.
•
PUBSUB.SUB3 should contain 3 messages, one for each record in the file (AccountUpdate.batch) with a ‘Y’ in the Decision field and with a credit rating between 500 and 650. A content filter was used in the subscription associated to select only these messages
•
PUBSUB.NOHIT does not contain any messages since all the published messages matched at least one subscription.
Page 162
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
To confirm that the correct 3 records are in the PUBSUB.SUB3 queue, you can use RFHUtil to examine the records. __132. Bring the third RFHUtil session (CreditSub3) into focus. __133. Press the Get Msg button.
__134. A published message should be read from the subscription queue (PUBSUB.SUB3 in this case).
Page 163
__135. Select the Data tab __136. Select Both for the Data Format radio button (to format the payload in both Hex and Character). __137. The messages in this queue should correspond to the 3 records in the file that indicated a credit approval decision of ‘Y’ and that had a credit rating between 500 and 650. The CREDIT-SCORE field is a binary integer and so is shown in hexadecimal. If the score is between x’1F4’ and x’28A’ then the correct record has been selected by the content filter.
Page 164
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__138. Select the RFH tab. The published message has an RFH2 header with a mcd folder that was added by the Mapping node in the message flow. The mcd folder indicates the type of user data that follows the RFH2 header. There is also another folder that is displayed on the other tab. This folder was added by the publication node.
__139. Select the Other tab to display the mqps folder contents.
Page 165
__140. Return to the PS tab. __141. Repeat the above steps to review the rest of the messages in the queue.
__142. After reading the messages press the Close Sub button. __143. Close the RFHUtil session. __144. Repeat the above two steps for the two other RFHUtil sessions. At this point the subscription queues should be drained of messages. If all of the messages were not read by using the Get Msg button then there will still be some messages in the queues and the queue depths displayed by the MQ Explorer will be different then shown in the lab guide.
Page 166
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
Using the NoMatch terminal One of the implications of Publish/Subscribe and its decoupling of message consumers from producers is that, if there are no consumers (subscribers) that match a publication, it is discarded. Strictly speaking, this should not be a problem; publishers are just making data available for possible consumption – if no one is interested, no harm should be done if the data is discarded. Or is there? In the real world, of course, a publisher might be very interested in the fact that it is publishing data that no one is interested in; if the data was important the publisher could then take some action to ensure the data is not lost, perhaps saving the data off to some other location and generating an alert. WebSphere MQ does provide the ability for a publisher to be notified if there were no subscribers that matched a particular publication. And IBM Integration Bus makes this option available to message flow developers through an output terminal on the Publication node, called the NoMatch terminal. This section will demonstrate how this capability can be used.
__145. Return to the MQ Explorer window, and select Subscriptions. Verify that there are no credit subscriptions currently active. Note! If you still see subscriptions from previous steps in this lab, you must not have closed one or more of the RFHUtil sessions you had open – You should go back and do that now.
__146. Open the Windows Explorer, and navigate to the C:\student\ps\data directory. __147. In the data directory, highlight the AccountUpdate.batch file. __148. Press the right mouse button. Page 167
__149. Select Copy (not Cut).
__150. Paste the file into the C:\student\ps\files\Input directory. The FileInput node will detect the arrival of a file that meets its specifications and will process the individual records from the file. Each record will be sent to the publication node.
Page 168
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__151. Return to the MQExplorer display, and select Queues (note that it may take a few seconds for the file to be processed and the MQExplorer screen to refresh). Here is what you should see, and why: •
PUBSUB.NOHIT should contain 10 messages, one for each record in the AccountUpdate.batch file. All 10 records are here because no subscriptions were active. Therefore the messages were sent out the NoMatch terminal on the publication node, which is wired to an MQOutput node that specifies this queue as its destination.
__152. Close the Integration Toolkit, Windows Explorer and any remaining RFHUtil windows. __153. Minimize the MQ Explorer window.
This is the end of Lab 4.
Page 169
Lab 5
Message Modeling with DFDL.
Overview The next lab (Lab 5) will demonstrate the use of Graphical Mapping using a DFDL message model. This lab will demonstrate how such a message model can be created. Some data formats do not require a model – such data formats are referred to as self-defining. XML is an example of a self-defining data format. A model (or schema) may be used but is not required in many cases. But many data formats are not self-defining. It is not possible to “understand” the data without a model to serve as a guide. This lab will explore how message models can be created for these non-XML data formats. In this lab, you will create a Message Model from a COBOL Copybook. Then you will test parse it against a valid data file and a malformed data file. In this last part you will be able to take a look at the trace facility.
Creating a Message Model from a COBOL Copybook
Testing the Message Model
Using the Trace faclity
Creating a Message Model from a COBOL Copybook This lab shows you how to create a Message Model based on a fixed length COBOL Copybook format. To do that, you will use the message model wizard taking a .cpy file as input.
Page 170
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__1.
Right-click in the white space of the Application Development pane.
__2.
Select New Library.
Page 171
__3.
Call the new library MessageModellingLibrary. Press Finish.
__4.
Under MessageModellingLibrary, click New…, then Message Model…
Page 172
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__5.
In the Message Model wizard, select COBOL and click Next.
Page 173
__6.
Page 174
Leave the default option selected, and click Next.
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__7.
MessageModellingLibrary should be preselected for “Application or Library”. If it is not, you can use the Browse button at top to select it. Select "Select source file from outside workspace". Click the Browse button at bottom.
Page 175
__8.
Page 176
Browse in C:\student\MessageModeling\resources\ and select the file "PURCHASES.cpy". Then click Open.
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__9.
Click Next.
Page 177
__10.
Click on the ">>" button to select all found objects (just one in this case) and click Next. Do not click Finish.
Page 178
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__11.
Leave most of the default values, but select “Recognize null values for all fields”. Then click Next.
Page 179
__12.
Page 180
Leave all the defaults values, and click Finish.
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__13.
The DFDL editor opens with the newly created DFDL message model called PURCHASES.xsd.
__14.
Notice the wizard automatically added a file called "CobolDataDefinitionFormat.xsd" under the Schema Definitions in MessageModellingLibrary. This file is referenced by PURCHASES.xsd as a schema import, and it contains COBOL-specific defaults for all the DFDL properties, and some pre-defined simple types.
Page 181
__15.
Expand the "Other Resources" folder under the MessageModelingLibrary library. Expand the "importFiles" folder and you will find the PURCHASES.cpy file that the wizard has automatically imported.
Page 182
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__16.
Double-click on PURCHASES.cpy to open it in the editor.
Page 183
This is a simple copybook with: • • •
__17.
Page 184
14 string fields PurchaseCount: binary field with the number of the Purchase structure occurrences Purchase: Repeating structure o PurchaseId, Amount: numeric fields. o Price: numeric field with 2 decimal places.
Switch to the DFDL editor. For the PURCHASES.xsd This shows the string fields, defined as "PICX_string" by the import wizard:
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__18.
In the DFDL Editor click on the CustomerLastName field to see its properties.
Page 185
In the properties view, look for the "Content" section. Note that the field was modeled as "text" representation, with a fixed (explicit) Length of 20 bytes, because the cpy file defined it as a "PIC X(20)"
Page 186
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__19.
Again, in the DFDL Editor, click on the PurchaseCount field to see its properties.
This field, which was defined as binary in the copybook file ("PIC 9(3) USAGE COMP"), was created as "PIC9_Comp_short" by the Import wizard. You can see the details of this field in the properties view, where its length is set to "2", its Length Units to "bytes" and its representation to "binary". Also, in the "Binary Content" section, its Binary Number Representation is set to binary. This property can take 4 different values: •
• • •
packed: represented as a packed decimal. Each byte contains 2 decimal digits except for the least significant byte, which contains a sign in the least significant nibble bcd: represented as a binary coded decimal with 2 digits per byte. binary: represented as 2' complement for signed types and unsigned binary for unsigned types. ibm4690Packed: used by the IBM 4690 retail store devices
Page 187
__20.
Now click on the Price field, in the Purchase structure.
__21.
In the Properties view, look at the Content section.
Page 188
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__22.
Look at the Text Content section of the Properties view.
Note that the "text number representation" is defined as "zoned", with a pattern of 8 integer numbers and 2 decimal places.
Page 189
__23.
Page 190
Click on the Purchase element to open its properties.
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__24.
Look for the Occurrences section inside the properties view, and expand the Occurs Count Kind property.
This property, as defined by the DFDL specification, can take different values: • • •
fixed: uses the "maxOccurs" property. expression: uses the value defined by the expression in "occursCount" property. parsed: the number of occurrences is determined by normal speculative parsing.
In this case, the "OccursCountKind" property is set to "expression", and "occursCount" is set to point to the "PurchaseCount" element. This means that the number of occurrences of the "Purchase" repeating structure will be defined by the PurchaseCount element. This was defined by the Import wizard to reflect the cpy file, which stated:
Purchase OCCURS 0 TO 99 TIMES DEPENDING ON PurchaseCount.
Notice also that the MinOccurs property is set to "0" and the MaxOccurs property is set to "99", as the cpy file stated.
__25.
Save your message model (PURCHASES.xsd), by either using Ctrl+S, or File->Save.
Page 191
Testing the Message Model 1.
Now you will test that the message model correctly models the COBOL data. Click the "Test Parse Model" icon.
Page 192
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
2.
In the Parser Input section, select "Content from a data file" and click the Browse button.
Page 193
3.
In the File Selection dialog, select the "Select an input file from the file system" option. Click on the Browse button.
Page 194
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
4.
Navigate to "C:\student\MessageModeling\data\" and select the "purchases.dat" file. Click the Open button.
Page 195
5.
Click OK on both windows.
Page 196
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
6.
Click on the checkbox "Remember my decision", and click Yes.
7.
The DFDL Test perspective will open, with the Test Parse view in focus. A message balloon will appear, indicating the parsing was successful. Close it by clicking on the "x", or by clicking anywhere else in the workbench.
Page 197
8.
Inspect the "Test - Logical Instance" view. Navigate through the message tree parsed from the input file.
Note that the parser shows "10.30" (2 decimal places) because the COBOL field was defined as PIC 9(8)V99.
Page 198
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
9.
In the DFDL Editor, click on any element on the Message Model and you will see the relevant data underlined in the input text below:
Page 199
10.
Now click on the PurchaseCount element.
Since it's a binary field, the highlighted value isn't readable with this editor.
11.
Now click on the Show hex button (top right of the lower pane, as highlighted below).
Notice that the binary field is now readable, and has a value of "00 04" which corresponds to the 4 occurrences of the "purchase" element. Click the Show Hex to revert to normal display.
Page 200
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
Using the Trace facility 1.
Next you are going to test the message model using a malformed message. In the DFDL Test perspective, "DFDL Test - parse" view, click on the Browse button.
2.
In the File Selection dialog, select the "Select an input file from the file system" option. Click on the Browse button.
Page 201
3.
Navigate to the "C:\student\MessageModeling\data" directory and select the "purchases_MALFORMED.dat" file.
Click OK.
Page 202
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
4.
In the "Offset" textbox, enter "298", and scroll right to find the highlighted character (byte 298 will be highlighted in blue). Note that at this position ("Price" field's position) there is a string "MALFORMED!" instead of the expected decimal number. Now click on the "Run parser" button to test the message model (green arrow at upper right as highlighted below).
5.
An error message will appear with the cause of the failed parsing.
Page 203
6.
Inspect the "DFDL Test - Logical Instance", you will see that the parsed tree is not complete. Go to the Purchase element, expand it, and check that it was correctly parsed until the "Amount" element. Note that the following fields beginning with "Price" are empty.
Page 204
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
7.
In the "DFDL Test - Trace" view, you will find an execution log of the parsing activities. At the end of the trace, there is a red colored line with the found error.
Look at the 2 lines before the error:
The first line states that it is starting to process the Price element. Then in the second, it has found a string "MALFORMED!" as the value of the element. Then the parser tries to convert the string to a decimal number, and an error appears.
Page 205
8.
Back in the DFDL Editor, scroll to the "Price" element. Note that it has an error icon next to its name.
9.
Place the cursor on the error icon and a message will appear, showing the same error cause you saw in the trace view.
This lab has provided a brief introduction to some of the new capabilities that have been provided with the DFDL parser. The DFDL domain should be the parser of choice for all non-XML data formats. This is the end of Lab 5.
Page 206
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
Lab 6
Building a Web Service using Patterns and Mapping
Lab Overview In this lab, a web service façade will be built on top of an existing MQ based service. The Patterns Wizard will be used to build a message set and a set of message flows based on a Web Services Description Language (WSDL) definition file that is provided. Using a pattern will produce a solution that includes additional function but that requires less effort to create. The generated pattern will be extended by defining the mapping between the back-end service format (based on COBOL copy books) and the Web Service data format (based on the imported WSDL file). The message flow will be tested using the Test Client. The following is what will be built and tested. This is the main request flow.
This is the main response flow.
Page 207
__1.
If necessary, close any open Editor Views. You should see the Quick Starts wizards list.
__2.
Click on Start from patterns in the list of Quick Starts.
Page 208
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__3.
The Patterns Explorer opens in the Navigator.
__4.
Select the MQ request-response pattern under Service Enablement Service Façade.
__5.
Take some time to read about the pattern and the solution it will generate.
Page 209
__6.
Click on the Create New Instance button to start the Pattern Generation wizard.
__7.
Enter OpenAcct_SOAP as the Pattern instance name.
__8.
Click OK.
Page 210
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__9.
Expand the Service Information section under Pattern Parameters. This section is marked with an exception, indicating a required parameter. Also expand the Service Information section under Pattern Parameters Details to see help for each parameter.
__10.
Click on Browse to the right of the Service WSDL input.
A selection dialog is shown. __11.
Click on the Import/Create New link.
Page 211
A library will be created to import the WSDL into. __12.
Click New… to the right of Application or Library.
Page 212
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__13.
Select the radio button for Library.
__14.
Click OK.
__15.
Enter OpenAcct_SOAP_Library for Library name.
__16.
Click Finish.
Page 213
__17.
Expand Independent Resources LabMaterials WSDL.
__18.
Select the WSDL_ServerService.wsdl resource.
__19.
Press the Next button.
Page 214
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
A WSDL may have multiple bindings. In this case there is only one. __20.
Click Finish.
__21.
Wait for the wizard to complete.
Page 215
When the wizard finishes several things have been done. A Library has been created (OpenAcct_SOAP_Library). The library contains schema definitions for all of the possible inputs to and outputs from the web service that are defined in the WSDL file, including the inclusion of the built-in SOAP schemas. __22.
Highlight the WSDL_ServerService.wsdl in the new OpenAcct_SOAP_Library.
__23.
Click OK.
__24.
The Import Wizard also opened the WSDL_ServerService.xsd schema. Click the X to close the schema view.
Page 216
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__25.
The OpenAcct_SOAP – Pattern Configuration window should be visible. The Service WSDL parameter is now complete.
__26.
Collapse the Service information section.
__27.
Expand the Provider Information section.
__28.
Change the Provider request queue field to IN (be sure to use uppercase – recall queue names are case sensitive).
Page 217
__29.
Expand the Response Information section.
__30.
Change the Response queue field to REPLY.
__31.
Change the Store queue field to STATE.
Page 218
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__32.
Collapse the Provider information and Response information sections.
__33.
Expand the Logging section.
__34.
Select the Logging required check box.
__35.
Accept the default value for the Log queue (LOG).
Page 219
__36.
Collapse the Logging section.
__37.
Expand the Error Handling section.
Basic error handling is included by default. There is nothing to change in this section.
Page 220
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__38.
Collapse the Error Handling section.
__39.
Expand the General section.
__40.
Enter OpenAcct_ in the Flow prefix field. Please note the trailing underscore!
__41.
Enter ACCTOPEN. in the Queue prefix field. Please do not forget the period at the end of the prefix.
__42.
Make sure that the entries are in the prefix fields.
__43.
Click on ‘Generate’ to build the pattern.
Page 221
When the wizard has completed, you will see the Summary for pattern instance OpenAcct_SOAP window, which provides a brief summary of the artifacts that have been created and some further tasks that must be completed, such as creation of the necessary queues. The wizard has created an Application project called OpenAcct_SOAP_Flows. This application contains two message flows, OpenAcct_Request and OpenAcct_Response, plus four subflows used by these message flows, OpenAcct_RequestProcessor, OpenAcct_ResponseProcessor, OpenAcct_Error, and OpenAcct_Log. You also will see the OpenAcct_SOAP Pattern Instance in your Application Development view. Under the Pattern Configuration folder, you will see the OpenAcct_SOAP_configuration.xml file, the saved pattern configuration, and the OpenAcct_SOAP_summary.html file, the summary screen, that can be used for later reference or pattern regeneration.
Page 222
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
The queues will now be created using MQ Explorer. The ACCTOPEN.IN queue already exists. It is used by the existing MQ-based account open service. In a real life scenario it is likely that the existing service would be running on a different system, in which case a remote queue definition would have to be made on the system that the node runtime is running on. It is possible to modify the MQOutput node that is used to send the message to route the message directly to the remote system by specifying a queue manager name. It is a better practice to keep the location of remote applications external from the applications themselves, including message flows. __44.
Switch to MQ Explorer.
__45.
If necessary, expand Queue Managers IB9QMGR so that Queues is visible.
Page 223
__46.
Select Queues.
__47.
Press the right mouse button.
__48.
Select New Local Queue from the menu.
__49.
Enter ACCTOPEN.REPLY as the Name of the new queue.
__50.
Press the Finish button to create the queue.
Page 224
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__51.
If the following notification appears, press the OK button to dismiss it.
__52.
Repeat steps 72 – 75 to create the following queues:
•
ACCTOPEN.STATE
•
ACCTOPEN.LOG
•
ACCTOPEN.ERROR
__53.
Minimize the MQ Explorer window.
__54.
Return to the Integration Toolkit and close the OpenAcct_SOAP_summary and OpenAcct_SOAP – Pattern Configuration tabs.
__55.
Select the new OpenAcct_SOAP_Flows application.
__56.
Press the right mouse button.
__57.
Select Manage Library references from the menu.
Page 225
__58.
Select the MQ_Service_Library.
__59.
Click OK.
__60.
You will see that the MQ_Service_Library library has been added to the References.
Page 226
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__61.
Click on the small triangular icon on the project navigator in the Application Development tab.
__62.
Select ‘Edit Active Working Set …’ from the menu.
__63.
Select the MQ_Service_Library check box. Do not remove any selections.
__64.
Click Finish.
Page 227
The response message flow needs to be configured for the message format sent by the MQ back-end service. __65.
Expand OpenAcct_SOAP_Flows Flows mqsi.
__66.
Double Click on the OpenAcct_Response.msgflow.
__67.
Select the Get Response input node.
Page 228
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__68.
Select the Input Message Parsing tab in the Properties view.
__69.
Select DFDL for Message domain using the drop-down menu.
__70.
Press the Browse button next to Message.
__71.
Select the ACCOUNTREQUEST{} message definition under MQ_Service_Library.
__72.
Press the OK button.
Page 229
__73.
The message should now be visible in the node properties.
__74. __75.
Save the flow (Ctrl+S). Close the Message Flow editor.
Now you need to create the mappings between the web services message format and the MQ back-end service format. These mappings will be placed in the OpenAcct_RequestProcessor and OpenAcct_ResponseProcessor subflows. __76.
Double click the OpenAcct_RequestProcessor.msgflow message flow.
Page 230
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__77.
Expand the Transformation drawer.
__78.
Drag a Mapping node from the palette directly on the connector between the Input node and the Passthrough node.
__79.
Drop the node when the connector color changes to blue.
The Mapping node should now been connected with both existing nodes. __80.
Change the name of the mapping node to SOAP2Cobol.
__81.
Double click the new mapping node (SOAP2Cobol).
Page 231
__82.
Accept the default values for the map name and location.
__83.
Press the Next button to continue.
Page 232
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__84.
Expand the OpenAcct_SOAP_Library DFDL and XML Schemas folder in the map inputs.
__85.
Select In_Request as map input.
__86.
Expand the MQ_Service_Library DFDL and XML Schemas folder in the map outputs.
__87.
Select ACCOUNTREQUEST as map output.
__88.
Press the Next button to continue.
Page 233
__89.
Confirm that the Output domain is set to DFDL.
__90.
Press the Finish button to create the map.
The Mapping editor will open. __91.
Drag the _In_Request source to the ACCOUNTREQUEST target.
The source and target are complex structures. A local mapping operation will be generated. __92.
Click the Local map link.
Page 234
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
The local map will open. __93.
Select the auto map icon to start an auto map operation.
Page 235
__94.
Select the check box for Create mappings when source and target names are more similar than.
__95.
Set the % match to 50 using the slider bar or by overtyping the value.
__96.
Uncheck the box for Alphanumeric characters.
__97.
Click Next.
A comparison of the names will be performed and the results shown on the next screen.
Page 236
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
In this case the CUSTOMER_ACCOUNT_NUMBER target has two sources. This is not right. It will now be corrected. __98.
Select the line with two sources (CUSTOMER_ACCOUNT_NUMBER).
__99.
Click on the Edit button.
Page 237
__100. Uncheck the box for customerCountry as this is not the proper source for this target. __101. Click OK to remove the incorrect mapping.
Page 238
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
The CUSTOMER_ACCOUNT_NUMBER target field now has a single correct source. __102. Click the Finish button to perform the auto map function.
There are some required fields not mapped automatically so you need to add them now. __103. Use drag and drop to map the source customerCity field to the target CITY field.
__104. Map the source customerCountry field dragging it onto the target COUNTRY field.
Page 239
__105. Right click on the DECISION field in the target half. __106. Select Create Assign from the menu.
__107. With the new Assign map selected go to the Properties tab. __108. Select the General tab. __109. Enter a single character Y as the Value for this assignment. The letter should be upper case.
__110. Right click on the ACTION_REQUEST field in the target half. __111. Select Create Assign from the menu.
Page 240
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__112. With the new Assign map selected go to the Properties tab. __113. In the Properties pane select the General tab. __114. Enter a single character (letter) O as the value for this assignment. The letter should be upper case.
Now it is time to deal with the two warnings within the generated map. __115. Locate the Move map for the customerCreditLimit. Hover over the warning symbol (a small yellow triangle containing an exclamation mark) to reveal the details of the warning. The warning text is: The string simple type input does not match the simple type output. Use a Convert transform to ensure proper conversion.
__116. Move the cursor to hover over the light bulb (just next to the warning symbol). __117. Select the quick fix that is being offered: Use convert to ensure the proper conversion.
Page 241
Repeat this process to resolve the remaining warning in the map. __118. Locate the Move map for the customerCreditScore. __119. Once again move the cursor to hover over the light bulb (just next to the warning symbol). __120. Select the quick fix that is being offered: Use convert to ensure the proper conversion.
The local map is now complete. __121. Return to the top level map by clicking the upward yellow arrow.
There is one more consideration for the map to be complete. The input message arrives over an HTTP transport. The output message will be sent over WebSphere MQ. The input message will contain an HTTP input header, which should be removed before sending the message to MQ. The removal of the HTTP header could also be accomplished using an HTTPHeader node. However, in this case the mapping node will be used to remove the header. This is accomplished by adding the header on the target side of the map but not mapping anything to it. The MQMD header will then be added by the MQ Output node as this puts a message to the queue. __122. In the output Message Assembly select the small blue “i” symbol to the right. __123. Click the Header: Properties link.
Page 242
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__124. Expand the HTTP Headers folder (Do not select all the headers at this level). __125. Select the check box next to the HTTPInputHeader header. __126. Press the OK button to add the header.
Page 243
The HTTPInputHeader is now shown in both the graphical map (shown here with the target properties minimized) and the Headers and folders property. Since nothing is mapped to this header it will be deleted from the map output.
This finishes the request mapping. __127.
Save the map (Ctrl+S).
__128. Close the Map editor.
__129.
Save the OpenAcct_RequestProcessor message flow (Ctrl+S).
__130. Close the OpenAcct_RequestProcessor message flow editor tab.
Page 244
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__131. Double click the OpenAcct_ResponseProcessor.msgflow message flow.
__132. Expand the Transformation folder. __133. Drag a Mapping node from the palette directly on the connector between the Input node and the Passthrough node. __134. Drop the node when the connector color changes to blue.
Page 245
The mapping node should now be connected with both existing nodes. __135. Change the name of the mapping node to Cobol2SOAP.
__136. Double click the new Cobol2SOAP mapping node
Page 246
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__137. Accept the default values for the map name and location. __138. Press the Next button to continue.
Page 247
__139. In the left hand pane, expand the MQ_Service_Library DFDL and XML Schemas folders. __140. Check the box next to ACCOUNTREQUEST. This will be the input message for the mapping. __141. In the right hand pane, expand the OpenAcct_SOAP_Library DFDL and XML Schemas folders. __142. Check the box next to Out_Response. This will be the output message for the mapping. __143. Click Next.
Page 248
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
The output message will be the reply to the web service in SOAP XML. __144. Leave XMLNSC selected as the Output domain. __145. Click Finish.
__146. Map the ACCOUNTREQUEST input to the Out_Response output.
A local mapping operation will be created. __147. Click the Local map operation.
Page 249
Expand the source and target message bodies. __148. Create assignments by drag and drop: __a. DATE_REQUEST to DateRequest __b. CUSTOMER_ACCOUNT_NUMBER to customerNumber __c. CUSTOMER_COMPANY_NAME to customerName __d. DECISION to requestDecision __e. COMMENTS to message
Page 250
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
This finishes the response mapping. __149. Click the yellow up arrow to return to the top level map.
__150.
Save the map (Ctrl+S).
__151. Close the Map editor.
__152.
Save the OpenAcct_ResponseProcessor message flow (Ctrl+S).
__153. Close the OpenAcct_ResponseProcessor message flow.
Page 251
Test the message flow The Test Client can be used to test flows that begin with MQInput, HTTPInput, JMSInput, SCAInput or SOAPInput nodes. The Test Client will automate much of that process for us. It will create and populate a BAR file, deploy the BAR file to the integration server, submit a test message, monitor any output nodes for results and display the results. The message flow depends on a message flow in the MQ_Service application. This message flow simulates a back end account open service based on MQ. This application will be deployed first. __1.
Select the small triangle on the right near the top of the project navigator.
__2.
Select Edit Active Working Set from the menu.
Page 252
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__3.
Ensure the check boxes next to the MQ_Service and MQ_Service_Library projects are checked.
__4.
Press the Finish button.
Page 253
__5.
Drag the MQ_Service application to the default integration server.
A deployment operation will start.
Page 254
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
The MQ_Service application should be visible under the default integration server.
__6.
Select the OpenAcct_Request message flow.
__7.
Hold down the Ctrl key and select the OpenAcct_Response message flow.
__8.
Press the right mouse button.
__9.
Select Test Message Flow from the context menu. This starts the Test Client.
Page 255
__10.
Press the OK button to dismiss the warning.
__11.
Use the Body pull-down menu to select the Edit as text option.
__12.
If a warning is displayed press the Yes button. This warning will not appear if the check box was selected in an earlier lab.
Page 256
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__13.
Click the Import Source button.
Page 257
__14.
Navigate to the C:\student\SOAP_InputMessages directory.
__15.
Select the Account_Open_Request.xml file.
__16.
Click the Open button.
Page 258
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__17.
Click on the Configuration tab.
__18.
Select MQ Settings.
__19.
Remove the selection from the Stop when the first MQ message is received check box.
__20.
Change the Select purge or browse option to ‘Browse message from MQ output queue’.
Page 259
__21.
Switch back to the Events tab.
__22.
Press the Send Message button to initiate the test.
Page 260
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__23.
Highlight the default integration server.
__24.
Click Next (this time only).
Page 261
__25.
Verify that you have a value of 40 as the Seconds to wait for deployment completion and Seconds to wait on launching the debugger for tracing purpose fields.
__26.
Enter 120 as the Seconds to wait for test client to stop.
__27.
Make sure the Add or modify … check box is checked.
__28.
Click Finish.
__29.
Press the Yes button to continue.
Page 262
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
The Test Client should start. A progress screen shows the test client deploying the message flows and associated artifacts. The progress of these actions is detailed in the Troubleshooting log.
Page 263
__30.
When the response is received, it is displayed.
__31.
Select the Received HTTP reply message for “SOAP Input” line.
__32.
If necessary use the small blue box icon to stop the test.
__33.
Close the Test Client.
Page 264
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
__34.
Select Yes to save the test. The same test can be used again later without needing to rebuild it.
Page 265
The ability to save multiple configurations and messages can be used to build a “test suite”. This could be used for regression testing in the future, for example. __35.
Highlight the OpenAcct_SOAP_Flows project.
__36.
Click Finish to save the Test Client configuration.
__37.
Close all open editors.
This is the end of Lab 6.
Page 266
Discovering the value of IBM Integration Bus V9 for your ESB and SOA
Lihat lebih banyak...
Comentarios
