JCJR 9YVSER Workbook

IBM Software An IBM Proof of Technology
Discovering the value of IBM

Integration Bus v10
Lab exercises
An IBM Proof of Technology
JCJR-9YVSER
© Copyright IBM Corporation, 2015

US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
IBM Software
Contents
LAB 1 GETTING STARTED .......................................................................................................................................... 6
1.1 BUILDING AND EXECUTING A SIMPLE INTEGRATION APPLICATION ................................................................... 6
1.2 GETTING TO KNOW THE IBM INTEGRATION TOOLKIT .................................................................................... 6
1.3 BUILDING A SIMPLE APPLICATION ............................................................................................................. 11
1.4 TEST THE FLOW USING THE FLOW EXERCISER .......................................................................................... 27
1.5 MESSAGE MODELS AND WORKING WITH XML MESSAGES ........................................................................... 42
1.6 USING THE XML PARSER ....................................................................................................................... 42
1.7 USING MESSAGE MODELS ....................................................................................................................... 52
1.8 PROJECT REFERENCES .......................................................................................................................... 68
1.9 TEST AGAIN USING THE FLOW EXERCISER ................................................................................................ 69
LAB 2 CONTENT-BASED ROUTING.......................................................................................................................... 79
2.1 OVERVIEW ............................................................................................................................................ 79
2.2 ADD ROUTING LOGIC .............................................................................................................................. 79
2.3 TEST CONTENT-BASED ROUTING USING THE FLOW EXERCISER ................................................................... 96
2.4 GENERATING DOCUMENTATION FROM YOUR APPLICATION OR SERVICE....................................................... 113
2.5 A CLOSER LOOK AT THE DEPLOYMENT PROCESS ...................................................................................... 117
2.6 LAB CLEAN-UP ..................................................................................................................................... 125
LAB 3 USING PATTERNS TO WORK WITH FILES ................................................................................................. 128
3.1 SELECTING AND CONFIGURING THE FILESYSTEM LOCATION ....................................................................... 128
3.2 PREPARING THE IIB TOOLKIT WORKSPACE ............................................................................................. 128
3.3 CONFIGURING AND GENERATING THE PATTERN INSTANCE ......................................................................... 131
3.4 RUNNING THE GENERATED IIB APPLICATION ........................................................................................... 134
3.5 SUMMARY ........................................................................................................................................... 137
3.6 INSTALLING A NODE.JS RUNTIME............................................................................................................ 137
3.7 DEPLOYING THE MOCKNODEJS IIB APPLICATION .................................................................................... 139
LAB 4 MODELING FIXED-LENGTH DATA USING A COBOL COPYBOOK ........................................................... 142
4.1 INTRODUCTION .................................................................................................................................... 142
4.2 CREATING A MESSAGE MODEL FROM A COBOL COPYBOOK ..................................................................... 142
4.3 TESTING THE MESSAGE MODEL .............................................................................................................. 163
4.4 USING THE TRACE FACILITY .................................................................................................................. 171
LAB 5 WEB ADMINISTRATION INTERFACE AND FILE-BASED SECURITY ........................................................ 177
5.1 INTRODUCTION .................................................................................................................................... 177
5.2 PREPARE THE IB10NODE APPLICATIONS .............................................................................................. 179
5.3 OVERRIDING BAR FILE ......................................................................................................................... 186
5.4 EXPLORE WEB ADMIN INTERFACE (NO SECURITY) ................................................................................... 188
5.5 INTEGRATION NODE AND SERVER PROPERTIES........................................................................................ 192
5.6 CONFIGURE ROLE-BASED SECURITY FOR WEB USERS............................................................................... 196
5.7 USING THE WEB ADMIN INTERFACE WITH SECURITY ................................................................................. 201
5.8 INTEGRATION TOOLKIT AUTHORIZATION .................................................................................................. 219
5.9 RESOURCE STATISTICS......................................................................................................................... 223
5.10 SUMMARY ........................................................................................................................................... 228
LAB 6 IMPLEMENTING A SERVICE INTERFACE ................................................................................................... 229
6.1 IIB CONFIGURATION ............................................................................................................................. 230
6.2 IMPLEMENTING A SERVICE INTERFACE LAB WORKSPACE ........................................................................... 230
6.3 IMPLEMENTING A SERVICE INTERFACE LAB DEPLOYMENT .......................................................................... 235
6.4 IMPLEMENTING THE SERVICE INTERFACE ................................................................................................ 236
6.5 DEPLOY THE EMPLOYEESERVICE_SOAP INTEGRATION SERVICE ............................................................. 264
6.6 EXPLORE INTEGRATION SERVICE USING WEB ADMIN ............................................................................... 282
6.7 SUMMARY ........................................................................................................................................... 285
LAB 7 CREATING A REST API SERVICE................................................................................................................ 286
7.1 IIB REST API CONFIGURATION ............................................................................................................ 287
7.2 REST API LAB WORKSPACE ................................................................................................................. 287
7.3 REST API LAB DEPLOYMENT ................................................................................................................ 292
7.4 EXPLORE THE EMPLOYEESERVICEV1 JSON DOCUMENT ......................................................................... 295
7.5 USING THE SWAGGER EDITOR ............................................................................................................... 297
7.6 CREATE THE REST API SERVICE .......................................................................................................... 308
7.7 DEPLOY THE EMPLOYEESERVICE_REST REST API .............................................................................. 354
Contents Page 3
IBM Software
7.8 TESTING THE EMPLOYEESERVICE_REST REST API ............................................................................. 356

7.9 SUMMARY ........................................................................................................................................... 369
LAB 8 EXCEPTION HANDLING AND THE INTERACTIVE FLOW DEBUGGER ..................................................... 370
8.1 OVERVIEW .......................................................................................................................................... 370
8.2 LAB SETUP .......................................................................................................................................... 370
8.3 UNDERSTANDING EXCEPTIONS IN IBM INTEGRATION BUS......................................................................... 373
8.4 DIAGNOSING FAILURES ......................................................................................................................... 416
8.5 USING THE INTEGRATED FLOW DEBUGGER ............................................................................................. 424
8.6 MODIFY FLOW AND RERUN USING THE FLOW EXERCISER.......................................................................... 448
8.7 LAB CLEAN-UP ..................................................................................................................................... 459
APPENDIX A. NOTICES ........................................................................................................................................................ 461
APPENDIX B. TRADEMARKS AND COPYRIGHTS ............................................................................................................. 463
Page 4 Discovering the value of IBM Integration Bus v10

IBM Software
Icons
The following symbols appear in this document at places where additional

guidance is available.
Icon Purpose Explanation
This symbol calls attention to a particular step or command.

Important! For example, it might alert you to type a command carefully
because it is case sensitive.
This symbol indicates information that might not be

Information
necessary to complete a step, but is helpful or good to know.
Trouble- This symbol indicates that you can fix a specific problem by
shooting completing the associated troubleshooting information.
Icons Page 5
IBM Software
Lab 1 Getting started
1.1 Building and executing a simple Integration Application

In this lab, you will build and execute an Integration Application, consisting of a single message flow. The
Application will then be deployed to an Integration Server in an Integration Node, where it will execute.
To explain these terms, in order:
 An Application is a container that holds all the artifacts that make up an Integration
Solution.
 A message flow is like a program but is developed using a visual paradigm.
 An Integration Server is an operating system process where user flows execute.
 An Integration Node is a collection of operating system processes, including one or more

Integration Servers, that together act as an Integration Control Point. This is sometimes
referred to as a Broker.
The Integration Application you build will be deployed to an Integration Server, where it will execute. The
unit of deployment is a Broker Archive (BAR) file. Broker Archive files have a file extension of “.bar”, and
are essentially a .zip file with a deployment descriptor. The deployment descriptor allows certain
properties of the message flow to be overridden. Once deployed, the flow will then be available to
process requests, messages, events, and more.
There is no need to restart the Integration Node or the Integration Server for the deployment of a
new or changed message flow.
Broker Archive (BAR) files and their use are explained in more detail at the end of Lab 2.
As a convention for these labs, a red box will be used to identify a particular area, and when information
is to be entered or an action is to be taken, it will be in bold characters. Red arrows or 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:

 Integration Toolkit
 Flow Exerciser
 XPath Expression Builder
A number of sections will be labeled “Key Idea” or “Key Concept”. Be sure to review these sections when
you come across them, as they will explain concepts of IBM Integration Bus (IIB) that you will explore in
some detail in the early labs, but in more detail as you continue to work through the more advanced labs.
1.2 Getting to know the IBM Integration Toolkit

__1. To start the IBM Integration Toolkit, click the icon shown below:

IBM Software
The following screen is displayed when starting the IBM Integration Toolkit.
You are prompted to select an Eclipse Workspace. Select the default here, but be aware that this
facility allows you switch between workspaces when starting or using the toolkit.
__2. Verify that the C:\student10\workspaces\GettingStarted directory is selected.
If not, enter C:\student10\workspaces\GettingStarted.
Click OK.
Lab 1 - Getting started Page 7

IBM Software
If you are not prompted to select a workspace:

Follow these steps to switch to the desired workspace.
__a. From the Menu bar select File > Switch Workspace > Other
__b. Enter C:\student10\workspaces\GettingStarted, or use the Browse button to navigate

to that location. Click OK.
__c. The current workspace will be saved, and the Toolkit will restart with the new workspace.

IBM Software
__3. If this workspace is being opened for the first time, you will see the Welcome screen.
Click Go to the Integration Toolkit to dismiss this screen.

IBM Software
__4. Now familiarize yourself with aspects of the Toolkit.
1.2.1 Key Idea: The Toolkit
The Integration Toolkit.

Read the section below for additional information on the
IBM Integration Toolkit.
The Integration Toolkit is based on Eclipse and includes components from IBM Rational® Application
Developer. It provides several perspectives 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 above 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 are several additional
views, such as the Integration Nodes view.

IBM Software
On the upper left is the Navigator view, which has tabs for projects (Application Development) and
patterns (Patterns Explorer). The Navigator view contains the projects that are available within the
Eclipse workspace. In this screenshot there are no projects at present; so what you see are a set of New
Project wizards, for kick-starting the development of Applications, Integration Services, REST APIs and
Libraries. You can also access these by right-clicking in the white space of the Application Development
view.
The area below the Navigator view is the summary area. Several views are present in this region—the
Integration Nodes view will show all defined local nodes as well as connections to remote nodes that
have been created. Integration Servers and the resources deployed, as well as their status, will be
shown here as well (the default integration server is shown in the screenshot above).
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.
At upper right are tabs for the one or more Perspectives that have been opened. To switch between
Perspectives, you can simply click the desired tab.
The Integration Toolkit also provides links to a number of predefined patterns. In later labs you will
explore how these are used.
Eclipse is project oriented; artifacts are organized into projects. A project is typed. Project types that are
specific to IBM Integration Bus include Applications, Integration Services, REST APIs and Libraries.
Also, legacy projects of type Message Flow Project and Message Set Project can be created or imported
into the toolkit. Since they predate the concept of Applications and Libraries, they will be visible in the
hierarchy in a folder called “Independent Resources”.
1.3 Building a simple application

__5. In the Application Development pane, click the New Application link.
Alternatively, you can click File on the menu bar, and select New > Application, or use the
drop-down list under File. Use these when you want to create project types other than those
represented by the four wizards.

IBM Software
You are prompted to enter a name for your Application.
__6. Enter IntroLab for the Application name. Click Finish.
Now you will create a new message flow.
__7. Under IntroLab, click (New).
__8. Select Message Flow.
The options for the New action will be different depending on how the request is made. For
example, when using File > New from the Menu bar, all of the options will be listed. However, if
you start from an Application, as you did in this case, the only options shown are those that are
related to the selected project type.

IBM Software
__9. Here you are asked to name the message flow.
Note: An Application may contain multiple message flows.
__10. Enter IntroMessageFlow in the Message Flow name box.
Click Finish.
You should see the first of several editors you will use. This one is the Message Flow Editor,
which is used for message flow composition.
__11. Click the white space in the Message Flow Editor. Information about the message flow will
appear in the Properties pane.
__12. Select the Properties tab.
__13. Select the Description tab.

IBM Software
__14. Enter the following:
Enter 1.0 for the Version field.
Enter Introduction to IBM Integration Bus V10 for the Short description field.
Enter your choice of information in the Long description field.
A message flow must begin with an input node. An input node establishes the runtime context
for the flow. There is an input node for each of the many protocols that IBM Integration Bus
supports. You will process an HTTP request with this flow so you need an HTTPInput node.
The HTTPInput node is in the HTTP drawer.
__15. Click on the drawer to open it.

IBM Software
__16. Hover over the node. You will see a brief description of the node’s function.
__17. Click the node, and either drag it to the canvas or move the mouse to the canvas
and click again.
When a node is initially added, its name can be changed immediately by typing over 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.
Note:
If you use the names as suggested it will make it easier to
follow this lab guide.

IBM Software
__18. Change the name of the node to “IntroLab_Listener.”
Press Enter to complete the rename.
Select the Basic tab in the Properties pane.
The Path suffix for URL in the node properties must be set. Mandatory fields that are not set
are indicated by a message in red.

IBM Software
__19. Note the hotspot on the right.
Click this for a brief description of the node’s function. In addition, there is a hyperlink provided to
the Help section that describes the node in detail.
__20. Click in the Path suffix for URL field.
__21. Hover over the icon that appears. Field-level help is available by clicking on these when they
appear.
__22. Enter /IntroLabService as the Path suffix for URL.
Note:
This name is case sensitive.
The path suffix must begin with “/”.

IBM Software
__23. 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.
__24. Enter URL Suffix: IntroLabService in the Short description field.
__25. Enter your choice of text for the Long description (Getting Started is shown in the screen
shot).
__26. In the flow editor, hover 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.

IBM Software
__27. The Trace node is in the Construction drawer.
Click the drawer to open it.
Hover over the node to see a brief description of the node’s function.
__28. Select the node and place it on the canvas to the right of the IntroLab_Listener node.
You do not need to rename the Trace node.

IBM Software
__29. Press Enter to accept the default node name (Trace).
__30. Click the Trace node.
__31. In Properties, click the Basic tab.

IBM Software
__32. Use the pull down list on the Destination field to select File.
__33. In the File Path field, enter C:\IntroLabTrace.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.
__34. Enter a line of ==================================== in the Pattern box.
Note: You can actually enter any free-form text you like. You are doing this to make it easier to
separate trace entries in the trace file, but this is not a requirement.
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 syntax tree that enters the node.
Note:
The pattern uses curly braces, not parentheses!
The pattern is case sensitive!
The expression between the curly braces will be evaluated at run time.

IBM Software
Review the values you entered into the Pattern box. Does it match what you see below?
__35. Double-check that Destination is set to File, the File path and name are valid (for example,
there are no embedded spaces), and that the Pattern is specified exactly as ${Root}
__36. On the Palette, return to the HTTP drawer and open it.
__37. Select an HTTPReply node from the drawer.
__38. Place it to the right of the Trace node.
__39. Press Enter to accept the default node name of HTTP Reply.
__40. Click the HTTPReply node.

IBM Software
__41. Review the properties for this node. You will be using the default values.
The nodes for this flow are configured. Next you will wire the flow together using the Node
Terminals.
1.3.1 Key Concept: Node Terminals
Key Concept: Node Terminals.

Read the section below for additional information on Node
Terminals and their use.
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.
You can hover the mouse pointer over the node terminals to see their names.

IBM Software
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 path of control for the message to follow through the
message flow.
Wire the Out terminal of the IntroLab_Listener node to the In terminal of the Trace node. There are two
techniques that can accomplish this:
One – position the mouse over the Out terminal (second from the top), click and drag to the
target and click again.
Two – right-click a node and select Create Connection. What follows is an example of terminal
selection presented as a result of using Create Connection.
The rest of the Lab instructions show the second method for wiring.
__42. Right-click the IntroLab_Listener node.
Select Create Connection from the menu.
__43. The Add Connection selection box is displayed.
The list of the available output terminals for the selected node is shown on the left.
A list of available input terminals for the nodes in the flow is shown on the right.

IBM Software
__44. Select IntroLab_Listener.Out on the left.
__45. Select Trace.In on the right.
__46. Click OK.
The connection will be created.
The same steps will be used to make a connection from the Trace node to the HTTP Reply
node.
__47. Right-click the Trace node.
__48. Select Create Connection.
The Add Connection selection box is displayed.

IBM Software
__49. Select Trace.Out on the left.
__50. Select HTTP Reply.In on the right.
__51. Click OK.
The connection will be created.
Your message flow should now look like the above diagram.

IBM Software
Notice the small asterisk next to the message flow name. This indicates that the message flow
has not been saved to disk.
__52. 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 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.
1.4 Test the flow using the Flow Exerciser

The message flow is now complete. The next step is to test it. The integrated Flow Exerciser will be
used to test the message flow.
1.4.1 Key Concept: The Flow Exerciser
Key Concept: The Flow Exerciser

Flow Exerciser.
The IBM Integration Bus Flow Exerciser provides the ability to capture a "snapshot" of the message
assembly as it is processed from node to node in a flow. These snapshots capture the state of the
message, as well as other structures in the message assembly, highlighting the path of control through
the message flow, providing an easy, visual way to test new or modified flows.
The recorded snapshot includes all syntax trees in the message assembly—message, local environment,
environment and the exception list—as well as several other properties such as a sequence number that
give more context to the recorded message.
When using the Flow Exerciser, recorded messages are displayed using an XML representation, which
shows the structure and content of the logical tree at each point in the message flow. This provides a
convenient visualization of the logical tree, and is a simplified version of the internal representation that
IIB uses to represent the logical tree.
Fields in the message tree can be modified, providing an easy way to exercise different paths in the
message flow.
A Flow Exerciser toolbar is located at the top of the flow editor. It has several icons, as described below.
Start the Flow Exerciser. Once started, clicking this icon again will stop it.

IBM Software
Create a message (or select an existing message or recorded message) to send through the flow.
View the path a message takes through the flow.
Using this toolbar, message recording and display can be performed with only a handful of mouse clicks.
This toolbar is activated when the user clicks the button to put the flow into record mode. This will deploy
the message flow, along with any dependent resources, and enable recording. Once the message flow
has been invoked, either by using an external client or injecting a message, the recorded message
assembly at each stage in the flow can be displayed.
Message injection is a feature of the Flow Exerciser that provides the ability to "inject" recorded
messages back into a flow, bypassing their normal transport method. For example, messages can be
injected in the MQTT subscribe node even when an MQTT server is unavailable.
When recorded messages are displayed, those that are valid for injection include a "Save" icon in the
top-right corner. Messages are saved to the same project as the message flow and can be shared with a
project interchange file or backed up to a repository for use in a test environment.
Message injection is supported on the following nodes:

● MQInput
● MQTTSubscribe
● SOAPInput
● HTTPInput
● FileInput
Input nodes will only process injected messages if they have no incoming data via their regular transport.
Output nodes "know" that a message has been injected and will deal with it differently from a normal
message.
In this section, you will use the Flow Exerciser to test your message flow.
__53. Click the Start control on the Flow Exerciser toolbar to start recording.

IBM Software
__54. If you did not save the flow before starting the Flow Exerciser, the following window will be
displayed:
Click OK.
__55. The application must be deployed to the default Integration Server of TESTNODE. This will be
done automatically for you by the Flow Exerciser:
__56. Once the application has been deployed, the following window will be displayed.
Review the information, and when ready, click Close.

IBM Software
__57. You are now ready to start recording. You will notice two changes:
1) The application has been deployed to the default Integration Server of TESTNODE. You
can see this by looking at the Integration Nodes view at the bottom left of the Toolkit:
2) The message flow is now “locked” – the background color of the flow editor has changed,
and you cannot modify the flow:
__58. To select a message to send, click the Send Message control on the Flow Exerciser toolbar.

IBM Software
__59. In the Send Message dialog, click the New message control.
__60. A new message (by default called new message 1) will be created.

IBM Software
__61. Change the name to “Test message,” select Import from file, and click File system.
__62. In the Import from file dialog, navigate to C:\student\IntroLabMessage, select the
IN_Request.xml file, and click Open.

IBM Software
__63. The selected file will be loaded.
Click Send to inject the message into the message flow.

IBM Software
__64. The Flow Exerciser will start the flow, inject the message into the flow, and capture the HTTP
reply message for viewing.
Click Close when you are ready to proceed.
__65. When returned to the flow, you will be pointed to the injected message for analysis, capture
(saving), or both.
Note the different icons on the connectors:
This icon means the recorded message can be viewed, changed and/or saved.
This icon means the recorded message can only be viewed.
Click the icon to see the injected message.

IBM Software
__66. The Flow Exerciser will retrieve the recorded message tree, parse the folders that make up the
tree, and render them in XML format for easy viewing:

IBM Software
__67. When complete, the message tree will be displayed, with the Message portion of the tree
expanded.
Expand the other folders in the tree and examine them if you like.
__68. Focus on the Message portion of the tree.

IBM Software
You can see the folders representing the message Properties, followed by the HTTP Input
header, followed by the payload (in the <BLOB> folder).
The XML rendering of the message tree makes it easy to interpret.
__69. Compare this to a more literal representation of the tree.

IBM Software
The next node in your flow was a Trace node.
__70. Use the Windows Explorer to locate the file the Trace node was configured to write to.
Navigate to C:\IntroLabTrace.txt, and double-click the file to open it.
__71. Recall that you configured the Trace node to capture the “IIB-internal” view of the message tree.
Examine the Trace output. You see IIB-supplied parsers for interpreting the Properties
(“WSPROPERTYPARSER”) and HTTP Input Header (“WSINPHDR”). Trace output allows you to
see more detail about the structure of header and message fields, such as their type (for
example, CHARACTER, INTEGER, or BOOLEAN).

IBM Software
Although you see here IIB-supplied parsers for Properties (“WSPROPERTYPARSER”) and
HTTP Input Header (“WSINPHDR”), what is missing is a parser for the payload. Because “none”
is supplied, IIB treats the payload as a BLOB.
The next section will show how to tell IIB the payload is XML.
__72. Close the Notepad window.
__73. Return to the recorded message, and click the save icon in the upper right corner.

IBM Software
Note: If the recorded message is closed, you can double-click the icon to reopen it.
__74. Save the recorded message with the name “Test message 1”, and click OK.
__75. If still open, close the recorded message window.
__76. In the Application Development pane, expand the Other Resources folder under the IntoLab
project. You will see the recorded message you saved, with the name
IntroMessageFlow_recordedMessage.xml.
__77. Double-click this file to open it.

IBM Software
__78. The XML editor will open. You can see the name you assigned to the recorded message.
__79. Close the XML editor.
__80. Stop the Flow Exerciser.
__81. Click Yes on the pop-up.

IBM Software
__82. The Flow Exerciser is stopped, and the message flow is returned to editable mode.
Continue to the next section to see how to tell IIB that the payload is XML.
1.5 Message models and working with XML messages

In this section, 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 Flow Exerciser will be used to run another test.
 The recorded message, as well as the trace file contents, will be viewed to see the difference.
1.6 Using the XML Parser

__83. In the IBM Integration Toolkit, click the IntroMessageFlow tab to bring the message flow into
view.
__84. Click the IntroLab_Listener node to bring its properties into view.

IBM Software
The message flow will be modified so that it uses the XMLNSC parser to process the input
message.
__85. 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 Flow Exerciser as well as the Trace file.
__86. 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.
__87. Select the XMLNSC parser. The XMLNSC parser is the most modern and most efficient of the
three XML parsers supplied with IBM Integration Bus, and should be the parser of choice for
most if not all message flows that handle XML messages. The other parsers are there for
backwards compatibility.
__88. Save the message flow (Press Ctrl+S).
1.6.1 Key Idea: Parsers and message domains
Key Idea: Parsers and message domains.

Read the section below for additional information on
parsers and message domains.
As discussed previously, IBM Integration Bus supplies a range of parsers to parse message content and
serialize message trees in different formats.
A parser is called when the bit stream that represents an input request or event 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 message syntax tree representation of the bit stream.
A parser is also used to serialize a logical syntax tree structure into a bit stream (for example on an
output node). This process is known as serializing.

IBM Software
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 and connectors)
Now, with the parser for the payload identified, re-run the Flow Exerciser.
__89. Start the Flow Exerciser.
__90. If the flow needs to be saved you will see this pop-up. Click OK.
__91. The Flow Exerciser will start.
__92. Click Close to start recording.

IBM Software
__93. Click the Send message icon.
__94. The Input message from the previous run is still available. Click Test message.

IBM Software
__95. The test message will be loaded. Click Send.
__96. The Flow Exerciser will run. Once it stops, click Close.
__97. Click the highlighted message.

IBM Software
__98. Note the difference between this run and the previous one.
The Properties and HTTPInputHeader folders are there as before. But this time, instead of BLOB
and UnknownParserName, you see the XMLNSC parser was used to successfully parse the
message payload.
__99. Save this recorded message by clicking on the save icon in the upper right corner.

IBM Software
__100. Call this recorded message “Test message 2” and click OK.
__101. Close the Recorded Message window.

IBM Software
__102. Use the Windows Explorer to locate the file that the Trace node was configured to write to.

IBM Software
__103. Scroll to the bottom of the Trace file.
Again you see the IIB-supplied parsers for interpreting the Properties and HTTP Input Header.
But now you also see XMLNSC rather than BLOB for the payload parser, and you see the
payload has been parsed and interpreted.
One thing you will notice here is that all the XML fields are CHARACTER.
Without a schema, IIB has no way to tell if any of the fields are another type.
Next you will supply a schema and tell IIB to validate the payload against that schema.

IBM Software

IBM Software
__108. In the Application Development pane, expand the Other Resources folder. Double-click the
IntroMessageFlow_recordedMessage.xml file.
__109. The XML editor will open. You should now see two testData messages, with the names you
assigned to each.
__110. Close the XML editor.
The next section will show how to tell IIB to use a message model (XML schema) to validate the
message contents.
1.7 Using message models

In this section, the IntroMessageFlow will again be modified, this time to identify the XML Schema file
that the XMLNSC parser should use in order to correctly parse the input content and serialize the output,
as well as perform schema-based validation.

IBM Software
This is needed in this case because the XML data contains three fields that are not CHARACTER data.
A message model is needed for the XMLNSC parser to be able to correctly identify those fields.
1.7.1 Key Idea: Message models
Key Idea: Message models.

Read the section below for additional information on
message models and their purpose.
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
● REST APIs using JSON
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.
JSON is an example of a self-defining message format. Another is XML. With self-defining formats, the
message itself contains metadata in addition to data values, and it is this metadata that enables JSON
and XML parsers to understand these messages even if no model is available.
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.

IBM Software
● 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 or Java code as part of your message flows, the language editors can use
message models to provide code completion assistance.
● Re-use of message models, in whole or in part, by creating additional messages that are
based on existing messages.
● Generation of documentation.
 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, you can get a message with typed elements and one
that is subject to constraints (such as required fields or max field lengths). The toolkit provides wizards
to import your existing models (such as WSDLs, XSDs or copybooks).
__111. In the Application Development view (project navigator) on the left, right-click the whitespace.

IBM Software
__112. Select New > Message Model.

IBM Software
__113. Select the Other XML radio button (under XML).
Click Next.
__114. Select the I already have an XML schema for my data radio button.

IBM Software
Click Next.

IBM Software
__115. Click the New button next to the Application or Library field.
__116. In the pop-up window, select Library.
Click OK.

IBM Software
__117. In the New Library dialog, type “IntroLab_Lib” as the Library name.
Select the Static Library radio button. This means the contents of this library will not be shared
across applications and services.
Click Finish.

IBM Software
__118. Back in the message model wizard, select the radio button Select file from outside workspace.
__119. Click Browse.
__120. Navigate to the C:\Student10\IntroLabMessage folder.
Select IN_Request.xsd.

IBM Software
Click Open.

IBM Software
__121. Back in the message model wizard, click Finish.
You now have a Library project with the XML message model for the input message.

IBM Software
1.7.2 Key Idea: Library projects
Key Idea: Library projects.

purpose and use of library projects.
Applications and libraries are deployable containers of resources: The contents of these can include
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. Use multiple libraries
to group related resources (for example, by type or function).
Libraries can be either static (embedded in the applications or services that use them) or shared
(meaning they can be referenced across multiple applications or services).
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.
__122. The XML Schema Editor should be opened for you after import.
If it is not, double-click In_Request.xsd to open it.
__123. The message model should now be visible in the XML Schema Editor.

IBM Software
Double-click the In_Request element to view the message elements.
__124. Double-click the (IN_RequestType) title bar to expand the schema view.

IBM Software
__125. Note that some elements, such as customerNumber and customerCreditScore, are integers
(ints) and not strings.
__126. Close the IN_Request.xsd tab.
Now, in the message flow, you need to tell the parser to run in schema-driven mode, rather than
operate in programmatic mode.
__127. Click the IntroMessageFlow tab to bring the message flow into view.
__128. Click the IntroLab_Listener node to bring its properties into view.

IBM Software
__129. In the Properties view, click the Validation tab.
In the Validation dropdown, select Content.
__130. Select the Parser Options tab.
Select the Build tree using XML schema data types check box.
__132. Note that when the flow is saved, a warning appears on the Input node.
__133. Hover the mouse pointer over the node to see the warning.

IBM Software
__134. You can also see this warning if you click the Problems tab in the lower right window.
You could resolve this warning, but for now ignore it.
However, this is a good point to spend a minute reviewing how IBM Integration Bus handles parsing.
1.7.3 Key Concept: Parse timing
Key Idea: Parse timing.

Read the section below for information on on-demand vs
immediate parsing.
Parsers such as the XMLNSC parser simplify your integration projects by allowing you to work with the
logical message tree, as opposed to having to work directly with the wire-format message. And parsers
that support messages models such as XMLNSC and DFDL can also be used to validate the structure or
content of messages.
However, in many integration projects there is no need to parse the entire message. For example, you
may be simply routing a message based on a small subset of the information in the message (you will
see an example of this in the next lab). Or, you may be modifying the message, but only in a trivial way.
In such cases, parsing the entire message may incur needless overhead.
For this reason, IBM Integration Bus gives you the ability to dictate when and to what extent parsing is to
be performed. One example of this is parse timing.
By default, Integration Bus will use on-demand parsing. This means the message will only be parsed if
elements within it are referenced, the parsing will occur at the time of reference (“on demand”), and the
message will only be parsed up to the point of reference. In many cases, on-demand parsing will save
memory and processor overhead, particularly if referenced fields are near the beginning of a message.
On-demand parsing involves a trade-off, though: If a message is malformed, that fact may not be
discovered, as the malformation may be at a point in the message for which parsing was avoided.
Similarly, if validation is requested, it will only be performed for those parts of the message that are
parsed, and so an invalid message may not be detected.

IBM Software
The latter situation is the reason for the warning you see on the IntroLab_Listener node. As the warning
indicated, you requested that validation be performed on the content of the message, but the parse
timing was set to its default value of “On Demand”, creating the possibility that validation errors would not
be
detected.
If Parse Timing were set to “Immediate,” the result would be that the entire message would be parsed,
allowing validation to be performed against the full message.
As mentioned, you could resolve this warning, but for now ignore it. You will explore dealing with errors
and problem determination in a later lab, including parsing errors.
1.8 Project references

Because IntroLab_Lib is defined as a static library, the IntroLab application must have a reference to it
so that it is included when the application is deployed.
__135. In the Application Development pane, right-click the IntroLab application, and select Manage
Library References from the menu.

IBM Software
__136. Select the IntroLab_Lib checkbox.
Click OK.
__137. In the Application Development pane, you should now see that IntroLab includes a reference to
the IntroLab_Lib library.
You are now ready to test the application again, using the Flow Exerciser.
1.9 Test again using the Flow Exerciser

The flow will now be run again. The trace output will then be examined.

IBM Software
__138. In the IBM Integration Toolkit, click the IntroMessageFlow tab to bring the message flow into
view.
__140. If the flow needs to be saved you will see this pop-up. Click OK.
__141. The Flow Exerciser will start.

IBM Software
__144. The Input message from the previous tests is still available. Click Test message.

IBM Software
__145. The test message will be loaded. Click Send.
__146. The Flow Exerciser will run. Click Close after it stops.

IBM Software
__147. Click the highlighted message.
__148. Note that the elements the XML schema identified as integers look no different here than in your
previous test.
But that is correct, because the Flow Exerciser renders the message tree using an XML
representation, regardless of their format, and elements in those messages as strings, again
regardless of their actual type.

IBM Software
We can return to the Trace file to see the actual physical representation of tree elements, to see
if the schema was in fact used when parsing the message.
__149. Save this recorded message by clicking on the save icon in the upper right corner.

IBM Software
__150. Call this recorded message Test message 3 and click OK.
__152. Use the Windows Explorer to locate the file the Trace node was configured to write to.

IBM Software
__153. Scroll to the bottom of the Trace file (or use Ctl+End) to view the new trace output
Again you see the IIB-supplied parsers for interpreting the Properties and HTTP Input Header.
And you see XMLNSC for the payload parser, and you see the payload has been parsed and
interpreted.

IBM Software
However, this time the parser used the schema when constructing the message tree, and
correctly identified the type as “integer” for the three indicated elements.

IBM Software
END OF LAB 1

IBM Software
Lab 2 Content-based routing
2.1 Overview
In this lab, you will modify the flow you created in Lab 1 to perform simple routing. Input messages will
be sent to one of two destinations depending on the country code. Addresses in the United States will
be routed to a US reply path, while addresses in Canada will be routed to a Canadian reply path.
You will also include some basic exception handling, to deal with addresses that are not in the United
States or Canada.
2.2 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.
Drag the node down a short distance.
Lab 2 – Content-based routing Page 79

IBM Software
__4. Click the Out -> In connector shown – the connector will turn blue. Press the Delete key to
remove the connector.
__5. Click the other Out -> In connector shown – the connector will turn blue. Press the Delete key to
remove the connector.
__6. Leave the Trace node unwired for now. Do not delete it. You will be repurposing it in a later lab.
__7. Expand the Routing drawer in the Palette.

IBM Software
__8. Select a Route node and place it between the IntroLab_Listener and HTTP Reply nodes.
__9. Change the name of the new routing node to “CheckCountry.”
Press Enter to complete the rename operation.
__10. Expand the HTTP drawer in the Palette.

IBM Software
__11. Select an HTTPReply node and place it beneath the existing HTTP Reply node.
__12. Your flow should look something like this.
Do not rename the new HTTP Reply node; you will be renaming them both shortly.
Terminals will now be added to the CheckCountry routing node for US and Canadian addresses.
__13. Select the CheckCountry route node.
Click the right mouse button.

IBM Software
Select Add Output Terminal from the menu.
__14. Enter US as the name of the new output terminal.
Click OK to continue.
The steps will now be repeated to add a terminal called Canada.
__15. Select the CheckCountry node.
Click the right mouse button.

IBM Software
Select Add Output Terminal from the menu.
__16. Enter Canada as the name of the new output terminal.
__17. Notice that the shape of the CheckCountry node has changed slightly.
Once there are too many terminals to display discretely, they will be grouped together.

IBM Software
__18. Change the name of the HTTP Reply node to “Reply if US.”
Press Enter to complete the rename operation.
__19. Change the name of the HTTP Reply1 node to “Reply if Canada.”
Note:
Two HTTPReply nodes are not actually necessary – a
single one could have been used. But separate nodes
were used here for clarity, as well as to make the flow
more self-documenting.
__20. Press Enter to complete the rename operation.
__21. Another way to make a connection is just to click the terminal itself.
Try this by selecting the Out terminal (second from the top) of the IntroLab_Listener node.
__22. Wire the Out terminal of the IntroLab_Listener node to the In terminal of the CheckCountry
node.
__23. Hover the mouse pointer over the connector to verify that the correct terminals are wired.

IBM Software
__24. Click the group of output terminals on the CheckCountry route node.
__25. A Terminal Selection list will appear.
Select US and click OK.

IBM Software
__26. Verify that the correct terminals are wired.
__27. Again click the group of output terminals on the CheckCountry route node.
__28. Select Canada from the list.
Click OK.
__29. Verify that the correct terminals are wired.

IBM Software
The criteria to be used by the CheckCountry routing node must now be specified.
__30. Select the CheckCountry node.
In the Properties pane select the Basic tab.
Click Add.
__31. Use the drop down menu to select the US terminal as the Routing output terminal.
Click Edit.
__32. Expand $Root.

IBM Software
Select (Add Data Type).
__33. 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.

IBM Software

IBM Software
__34. Expand the tns:In_Request > customerDetails elements.
Select the customerCountry element and drag it into the XPath Expression dialog box.

IBM Software
__35. Drag an equal sign from the Operators pane to the end of the expression.
Append the letters ‘US’ (including the single quotes) after the equal sign.
Click Finish to complete the XPath expression.

IBM Software
__36. Click OK 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.
__37. Click Add to enter a filter pattern for the Canada terminal.
__38. Use the drop down menu to select the Canada terminal as the Routing output terminal.
Click Edit.

IBM Software
__39. Expand Root > tns:In_RequestcustomerDetails. Tip: If you do not see In_Request in the
viewer, re-add it as explained in steps 31-32.
__40. Select the customerCountry field and drag it to the XPath Expression window.
__41. Complete the XPath Expression by typing =’CA’.
Click Finish to complete the XPath expression.

IBM Software

IBM Software
__42. Click OK to complete the Filter table entry.
The filter pattern for the Canada terminal should now be visible.
Verify that the two Filter table entries appear as shown below.
The updates to the message flow are now complete.
__43. Save the message flow.
2.3 Test content-based routing using the Flow Exerciser

You will use the Flow Exerciser to test the flow. In this lab you will see some additional features of the
Flow Exerciser that make it a very useful tool when testing and debugging more complex message flows.
Note: The Trace node is still unwired. But this will not cause any problems.

IBM Software

IBM Software

IBM Software
__47. The Input message from the previous tests is still available. Click Test message.
In the Test message, locate customerCountry. The value should be USA.
__48. Change the value of customerCountry to “US”.
Click Send.

IBM Software

IBM Software
__50. The Flow Exerciser shows the path the US message took through the flow.

IBM Software
__51. Click the recorded message to view it.
__52. Note that the Recorded Message does reflect the change you made.

IBM Software
__53. Save this recorded message by clicking the save icon in the upper right corner.
__54. Call this recorded message “Test customerCountry=US.”
Click OK.
__56. Repeat these steps to test the Canada path in the message flow.

IBM Software
Click Send to configure another message.

IBM Software
__57. Select Test message.
Change customerCountry to “CA”
Click Send.

IBM Software
__59. This time the Flow Exerciser shows that the CA path was taken.
__60. Click the recorded message to view it.

IBM Software
__61. Note that the Recorded Message does reflect the change you made.

IBM Software
__63. Call this recorded message “Test customerCountry=CA.”
Click OK.
__65. In the Application Development pane, expand Other Resources.
Double-click IntroMessageFlow_recordedMessage.xml to open it.
__66. In the XML Editor, expand the two most recent testData entries. You should see the recorded
messages for US and CA.

IBM Software
__67. Close the XML Editor.
__68. You have tested your two expected paths (US and CA). But what will happen if some other
customerCountry value is received by the message flow?
__69. Click Send to configure another message.

IBM Software
__70. Click Test message. Change the customerCountry to “MX”. Click Send.
__71. Note that the message was sent but no HTTP Reply was received.
Click Close.

IBM Software
__72. In the Flow Exerciser, notice that control reached the CheckCountry node. But it stopped there.
Why did it stop?
__73. To answer that, look again at the flow.
Stop the Flow Exerciser.
Click the CheckCountry route node. Only US and CA are handled.

IBM Software
__76. Click the Output Terminal group.
__77. Review the available output terminals.

IBM Software
● US and Canada are wired. But MX is not going to match either of those.
● There was neither a match nor a failure.
● Default would be the terminal normally taken when there was no match. But this was not
wired. Therefore, the message was discarded. This might not be what you want to
happen.
One approach would be to wire the Default terminal to an “Unsupported Country” path.
But many things could potentially go wrong in a message flow. Rather than wire every possible
exception path on every node in a flow, you will explore approaches to dealing with situations
like this one in a later lab.
__78. Click Cancel to cancel the unattached connector.
In a later lab you will explore one approach for dealing with unexpected conditions such as this one, as
well as how to implement some basic flow-level exception handling.
2.4 Generating documentation from your application or service

In this section, you will see how the IBM Integration Bus Toolkit can be used to generate documentation
from application and service artifacts such as message flows.
The Document Generation feature of the toolkit uses information such as metadata from flows and other
development artifacts, as well as description information specified by solution developers.
This documentation can be combined with test messages and results to create a package of
documentation, testing artifacts and scenarios.

IBM Software
__79. In the Application Development pane, select the IntroMessageFlow.msgflow file, right-click the
file, and select Generate Documentation from the menu.
__80. In the Document Generation pop-up, specify:

a. Author (“Your Name”)
b. A suitable Title
c. A Location and name for the generated file (by default this is the current workspace)
Click Next.

IBM Software
__81. Make sure Generate documentation from the selected resource is selected.
Click Next.
__82. Accept the default layout and click Finish.

IBM Software
__83. Click Yes to view the generated report.
__84. Review the generated report (the first page of which is shown here).
Notice how the Toolkit uses both flow metadata as well as descriptions you entered, version
numbers, and additional information to generate the report.

IBM Software
Many of these fields were left blank in the labs you did, but a best practice would be for you to
make the fullest use possible of these fields, in order to make your integration solutions as well-
documented and maintainable as possible.
__85. Close Adobe Reader.
The next section will take a closer look at the deployment process.
2.5 A closer look at the deployment process

In the first two labs, you have been utilizing the Flow Exerciser to initiate your unit testing and it has been
handling the deployment process for you “behind the scenes”. To finish this lab, you will briefly examine
the deployment process, and you will manually do your own deploy.

IBM Software
2.5.1 Key Idea: The deployment process
Key Idea: The deployment process

Deployment of integration solutions up to this point
have been done implicitly – by virtue of your using the
Flow Exerciser. This section will explore other
approaches to solution deployment.
When you create an application, Integration Service or REST API project in the IBM Integration Toolkit,
you must distribute them to the Integration Nodes where you want them to run. Artifacts for message
flows and associated resources are packaged in a broker archive (BAR) file before being deployed to the
integration server.
You can initiate a deployment in the following ways:

● From the IBM Integration Toolkit
● From the IBM Integration Web UI
● By using the mqsideploy command
● By using functions defined by the IBM Integration API
Depending on your work patterns, you might use all these methods at different times.
The Integration Toolkit provides an Integration Nodes view in the lower left hand corner of the Integration
Development perspective. If you expand an Integration Node, all the Integration Servers in that node are
displayed, as well as deployed applications, services, REST APIs, and their underlying 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 Integration Server to deploy it.
Alternatively, you can right-click an Integration Server to select an application or library, message flow, or
BAR file to deploy to the selected Integration Server.
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 Integration Server to which you want to deploy it. A BAR file is
generated automatically and deployed. If static 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.

IBM Software
2.5.2 Key Concept: The BAR file
Key Concept: Broker archive (BAR) files.

The unit of deployment to an Integration Server is the
Broker Archive (BAR) file. This section will explore
what BAR files are and how you make use of them.
The Broker Archive (BAR) file is a .zip file that 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 applications, libraries, services, REST APIs, message flows and other flow
dependencies to the broker archive.
3. If necessary, edit the configurable properties of the message flows or applications in the
broker archive.
4. Deploy the BAR file by sending it to an Integration Server.
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.
__86. Return to the Integration Toolkit.
In the Application Development pane, right-click in the whitespace.
__87. Select New > BAR file from the menu.

IBM Software
__88. Enter “Lab2” as the name of the new broker archive file.
Click Finish.

IBM Software
__89. In the BAR editor, select the IntroLab checkbox.

IBM Software
__90. Select the Message flows, static libraries and other message flow dependencies radio
button.
__91. Select the IntroLab_Lib checkbox.
__92. Click the Build and Save button.
__93. If prompted to save the message flow, click Yes.
__94. Click OK.

IBM Software
__95. In the BAR editor, select the Manage tab.
Expand the IntroLab app and select the various resources.
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 IntroLab_Listener node. You can see that the
“Path suffix for URL” property can be overridden at deployment time.

IBM Software
To deploy, find the Lab2.bar file in the navigator in the BARs container.
Drag and drop it onto the default integration server on TESTNODE.
__96. Wait for deployment to complete.
__97. Once deployment is complete, click the default integration server to open it and see the assets
deployed to it.
The IntroLab application has been deployed, which included the IntroMessageFlow message
flow. The IntroLab_Lib static library, which contains the IN_Request XML Schema, has also
been deployed.

IBM Software
Note too that the deployment date and time should reflect the actual time of deployment.
Close all the open editor tabs but leave the Toolkit running.
2.6 Lab clean-up

Optionally, you can clean up the resources you created in Labs 1 and 2.
The following steps will delete the run-time artifacts from the TESTNODE server.
This will make things less cluttered while you continue through the remainder of the labs.
__98. In the Application Development pane, collapse any folders that are currently expanded.

IBM Software
__99. In the Integration Nodes pane, right-click the default Integration Server, and select
Delete > All Flows And Resources.
__100. Click OK to proceed.
__101. Wait while the default Integration Server is cleared.

IBM Software
__102. All deployed objects should be cleared from the default Integration Server.
__103. Close all the open editor tabs but leave the Toolkit running.
END OF LAB 2

IBM Software
Lab 3 Using patterns to work with files

In this lab will you will learn how to start from, configure and instantiate a pattern. You will also
implement file processing, content-based routing and file-to-HTTP protocol switching. The lab
implementation reads JSON files, routes them based upon the value of a country field, and calls an
HTTP web service that can be provided either by a Node.js application or an IIB application.
You will use the default integration node with a name starting with TESTNODE and the integration server
named default.
3.1 Selecting and configuring the filesystem location

In the section you will select and configure a filesystem location that IIB will read files from.
__1. Create or select a directory where IIB will read the input file and make note of its path (e.g.
C:\student10\Lab3). Under that path, create a subdirectory named file_to_http_sample .
__2. Set the MQSI_FILENODES_ROOT_DIRECTORY environment variable to the path in the prior
step. For example, on Windows, navigate to Control Panel > All Control Panel Items >
System, click Advanced system settings, then Environment Variables, then set this variable
as a system variable. Log out and log back in. (This step may already be done, depending on
the machine you use for this lab.)
This environment variable sets the starting point for the relative file paths (for example,
file_to_http_sample) used in this lab’s implementation.
3.2 Preparing the IIB Toolkit workspace

In the section you will prepare an empty IIB Toolkit workspace with the pattern.
__3. Double-click the desktop shortcut for the IIB V10 Toolkit. When prompted for a workspace, enter
a path for an empty workspace then click OK.

IBM Software
__4. Close the Welcome panel.
Lab 3 - Using patterns to work with files Page 129

IBM Software
__5. In the Toolkit’s upper left, click the Patterns Explorer tab. Then select Pattern Repositories >
Experimental OT4I GitHub Pattern Repository > File Processing > Record Distribution >
HTTP one-way to open the Pattern Specification editor for Record Distribution to HTTP: one-
way pattern. The Patterns Explorer view should indicate that this pattern currently is not
installed.
__6. In the lower right of the Pattern Specification editor, click Download and Install.
__7. Let the download complete. If prompted with a security warning, click OK to proceed. Upon
completion of the download, the Patterns Explorer should indicate that the HTTP one-way
pattern is now installed.

IBM Software
__8. Read all of the information on the Pattern Specification view for this pattern, including the links in
the Message Flows and Related Tasks sections.
__9. As mentioned in the Solution section of the above Pattern Specification, use of this pattern
requires installation of the Node.js runtime. Alternatively, you may elect to deploy an IIB
application that serves as an equivalent of the Node.js application. Choose between these two
options and follow the instructions for that choice. If you chose the Node.js application, follow
the instructions in section 3.6; if you chose the IIB application, follow the instructions in section
3.7.
3.3 Configuring and generating the pattern instance

__10. In the Patterns Explorer, select Patterns > File Processing > Record Distribution > HTTP
one-way and single-click. On the resulting Pattern Specification page, click Create New
Instance. (Note: The correct path is under the Patterns folder, not the sibling folder named
Pattern Repositories.)

IBM Software
__11. In the New Pattern Instance window, specify a name.

IBM Software
__12. On the Pattern Configuration editor, specify exactly the values shown in the screen capture
below. If you elected to use the IIB application as a substitute for the Node.js application, modify
the port number in each of the three URLs below with the value noted in Appendix B. Then click
Generate in the lower left of the panel and wait until pattern generation is complete.

IBM Software
__13. Select Window > Reset Perspective. In the Reset Perspective window, click Yes.
__14. If you elected to use the Node.js application rather than the IIB application as the web service
provider, start it now. Open a command prompt to the current workspace for the IIB Toolkit (for
example, C:\student10\workspaces\Lab3) then navigate to <pattern instance name>_HTTP-
oneway_sample/webserver. From there, run the start_server.<ext> script appropriate for your
platform; for example, start_server.bat on Windows. The first time you run the command, you
will see the messages preceded with dashes in the screen capture below. The “Listening on port
3000” message indicates that the web service is up and ready.
If you elected to use the IIB application as a web service provider, you should have followed the
instructions in Appendix B so that it is already deployed and running.
3.4 Running the generated IIB application

__15. In the Application Development view, expand the <pattern instance name>_HTTP one-way
application, select the RecordDistributor message flow, and double-click to open it in a
message flow editor. Review the flow, its node, their settings, and the Pattern Specification to
ensure that you understand what this flow does: reads JSON files from the file_to_http_sample
directory, parses them as JSON, routes them based upon the country specified in the JSON, and
submits an HTTP request to the URL appropriate for that country.
__16. With the RecordDistributor message flow still open in a message flow editor, click the red Flow
Exerciser button. If the toolkit presents a Ready to record message panel, select the box for Do
not show this message again then click Close.

IBM Software
The application should be deployed, and flow recording should start.
__17. In the Integration Nodes view in the Toolkit’s lower left, confirm that the <pattern instance
name>_HTTP one-way application deployed.
__18. Run the flow. In the Application Development view, navigate to Independent Resources >
<pattern instance name>_HTTP-oneway_sample and select the Record1.json file. Right-click
then select Copy to copy the file. Paste the file into the file_to_http_sample directory polled by
the flow’s File Input node. The RecordDistributor flow will read the file, route it based upon the
country value in the JSON, and send the request to the corresponding URL.
__19. Confirm that the web service has received the request sent by the IIB flow. If you are using the
Node.js application, look in the start_server window for the Record Saved message shown below.
If you are using the MockNodeJs IIB application, open the WebService.dat file in the out
subdirectory to see similar output from that web service.

IBM Software
Either of these outputs indicates successful execution of the message flow.
__20. Examine the path that the file data took through the message flow. At the top of the message
flow editor for the RecordDistributor flow, click the View Path icon.
Green highlighting will appear to indicate the path the previous file data took through the flow.
Click the envelope icon on the wire between the File Input and Record Processor nodes.
View the message data in the Recorded Message dialog. In particular, notice the value of the
country field.

IBM Software
Click the envelope icon on the green wire between the Route node and the HTTP Request 0
node. View the data in the new Recorded Message dialog. The Route subflow routed the
message through this path of the flow based upon the value of the country field.
__21. Rerun the RecordDistributor flow with different files. Repeat the prior three steps using the files
Record2.json and Record3.json. Because each of these files has a different country value, they
will take different paths through the flow.
3.5 Summary
This lab has provided an illustration of how to start from, configure, and instantiate a pattern. It has also
illustrated file processing, content-based routing, and file-to-HTTP protocol switching.
3.6 Installing a Node.js runtime

If you elected to use the Node.js application as the web service provider for this lab, follow the
instructions in this section to install the Node.js runtime.
__22. Use a browser to navigate to http://nodejs.org/download/.

IBM Software
__23. In the Downloads section of that webpage, click the link to download the Node.js installer for
your operating system. For example, if you are running 64-bit Windows, click the link indicated
in the screen capture below.
__24. Upon completion of the download, run the installer.
__25. As shown on the Node.js window below, choose to do a complete installation of Node.js.
__26. Follow the remaining screens to complete installation of the Node.js runtime. Upon completion,
click Finish in the window below.

IBM Software
3.7 Deploying the MockNodeJs IIB application

If you elected to use the MockNodeJs IIB application as the web service provider for this lab, follow the
instructions in this section to deploy an IIB application that serves as a substitute for the Node.js
application.
__27. Obtain the project interchange file named MockNodeJs_pi.zip from the IBM person leading
your workshop. Save it to a temporary directory on the machine where your IIB Toolkit runs.
__28. Within the IIB Toolkit workspace, import that project interchange file. Navigate to File > Import >
IBM Integration > Project Interchange and click Next. On the Import Project Interchange
Contents panel, set From zip file: to the full path of the project interchange file and make sure
that the MockNodeJs project is selected. Click Finish.

IBM Software
__29. Within the filesystem path referenced by the MQSI_FILENODES_ROOT_DIRECTORY

environment variable, create a subdirectory named out as a sibling of the file_to_http_sample
directory. The File Output node of the WebService message flow will write to a WebService.dat
file in the out directory.

IBM Software
__30. In the Application Development view in the upper left of the toolkit, select the MockNodeJs
application, right-click, select Deploy, select the default integration server on the Deploy
panel, and click Finish. You should see the MockNodeJs application deployed to the default
integration server.
__31. Use the mqsireportproperties TESTNODE -e default –o HTTPConnector –n port command from
an IBM Integration Console to determine the HTTP listener port (port 7800 in the example
shown).
Make a note of this port number. During pattern generation, you will need to update the pattern’s
three URLs with this port number.
END OF LAB 3

IBM Software
Lab 4 Modeling fixed-length data using a COBOL copybook
4.1 Introduction
In this lab, you will create a message model from a COBOL Copybook. Then you will use the
DFDL Test Tooling to test parse valid and malformed data files. In the last part of the lab you will
investigate the trace facility.
4.2 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.
You will create the message model using the message model wizard and providing a *.cpy file as input.
__1. To start the IBM Integration Toolkit, click the icon shown below:
The following screen is displayed when starting the IBM Integration Toolkit.

IBM Software
You are prompted to select an Eclipse Workspace
__2. Enter the workspace named C:\student10\workspaces\DFDL_Cobol. Click OK.
You may have already used another workspace for other labs. If so, choose File > Switch
Workspace > Other.
Lab 4 - Modeling fixed-length data using a COBOL copybook Page 143

IBM Software
__3. Overwrite the Workspace with C:\student10\workspaces\DFDL_Cobol and click OK.
__4. Create a new library named “MessageModellingLibrary”.
Click New library.

IBM Software
__5. You will see radio buttons to choose “Shared Library” or “Static Library”. For this lab you will use
a shared library.
Click Finish.

IBM Software
__6. In this library, click New and select Message Model.
__7. In the message model wizard, select COBOL and click Next.

IBM Software
__8. Leave the default option and click Next.

IBM Software
__9. Use the Browse button to set the Application or Library to “MessageModellingLibrary”.
Select Select source file from outside workspace. Click Browse.

IBM Software
__10. Browse in C:\student10\MessageModeling\resources\ and select the file PURCHASES.cpy.
Click Next.

IBM Software
__11. Click the >> button to select all found objects (just one in this case) and click Next.
Do NOT click Finish.

IBM Software
__12. Leave most of the default values, but select Recognize null values for all fields and Create
value constraints from level 88 VALUE clauses.
Click Next.

IBM Software
__13. Leave all the default values, and click Finish.

IBM Software
__14. The DFDL editor opens with the newly created DFDL message model called PURCHASES.xsd.
__15. Note that 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.
__16. Expand the Other Resources folder under the MessageModelingLibrary library.
Expand the importFiles folder and you will see the PURCHASES.cpy file that the wizard has
automatically imported.

IBM Software
__17. Double-click PURCHASES.cpy to open it in the editor.
This is a simple copybook with:

● 14 string fields
● PurchaseCount: binary field with the number of the Purchase structure
occurrences

IBM Software
● Purchase: Repeating structure

 PurchaseId, Amount: numeric fields
 Price: numeric field with 2 decimal places
__18. Switch to the DFDL editor. For the PURCHASES.xsd this shows the string fields, defined as
"PICX_string" by the import wizard:

IBM Software
__19. In the DFDL Editor click the CustomerLastName field to see its properties:
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)".

IBM Software
__20. In the DFDL Editor, click 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 four 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

IBM Software
__21. Now click the Price field, in the Purchase structure.

IBM Software
__22. In the properties view, look at the Content section.
Note that it is defined as a decimal field, with text representation and a length of 10 bytes (8
integers and 2 decimal places).

IBM Software
__23. Look at the Text Content section of the properties view.
Note that the "Number Representation" is defined as "zoned", with a pattern of 8 integer
numbers and 2 decimal places.
The letter “V” in the Number Pattern is an implied decimal point (common in COBOL copybooks).

IBM Software
__24. Click the Purchase element to open its properties.
__25. Look for the Occurrences section inside the properties view, and expand the Occurs Count
Kind property.

IBM Software
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
 implicit: uses “minOccurs” and “maxOccurs” properties with 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:
Also notice that the MinOccurs property is set to "0" and the MaxOccurs property is set to "99",
as the cpy file stated.
__26. Save your message model (PURCHASES.xsd) by pressing Ctrl+S, or File > Save.

IBM Software
4.3 Testing the message model

__27. Now you will use the DFDL test tooling to validate that the message model correctly models the
COBOL data. Click the Test Parse Model icon.

IBM Software
__28. In the Parser Input section, select Content from a data file and click Browse.

IBM Software
__29. In the File Selection window, select Select an input file from the file system.
Click Browse.

IBM Software
__30. Navigate to C:\student10\MessageModeling\data\ and select the purchases.dat file.
Click Open.

IBM Software
__31. Click OK on both windows.
__32. Select Remember my decision, and click Yes.

IBM Software
__33. 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.

IBM Software
__34. 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.

IBM Software
__35. In the DFDL Editor, click any element on the message model and you will see the relevant data
underlined in the input text below:
__36. Now click the PurchaseCount element.
Because it is a binary field, the highlighted value is not readable with this editor.

IBM Software
__37. Now click the Show hex button (top right of the lower pane, as highlighted below).
Note 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 button again to revert to normal display.
4.4 Using the Trace facility

__38. Now you will test the message model using a malformed message.
In the DFDL Test perspective, "DFDL Test - parse" view, click Browse.

IBM Software
__39. In the File Selection window, select Select an input file from the file system.
Click Browse.

IBM Software
__40. Navigate to the C:\student10\MessageModeling\data directory and select the

purchases_MALFORMED.dat file.
Click OK.
__41. 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 (the "Price" element position) there is a string "MALFORMED!" instead
of the expected decimal number.
Now click the Run parser button to test the message model (green arrow shown below).

IBM Software
__42. An error message will appear with the cause of the failed parsing.
__43. 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. The following field "Price" is empty.
__44. Now you will use the DFDL Test - Trace view, to better understand the problem.
Click the DFDL Test - Trace view.

IBM Software
__45. In the DFDL Test - Trace view, you will find an execution log of the parsing activities.
At the end of the trace, there are colored lines with the found error.
__46. Look at the lines before the error:
The first line states that it is starting to process the Price element.
In the third, 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.
__47. Back in the DFDL Editor, scroll to the Price element.
Note that it has an error icon next to its name.

IBM Software
__48. Place the cursor on the error icon and a message will appear, showing the same error displayed
in the trace view.
END OF LAB 4

IBM Software
Lab 5 Web administration interface and file-based security

Featuring:
● Deployment of applications and libraries from Web UI
● Exploring Web UI without security
● Configuring Web UI with role-based security
● Exploring Web UI with security
● BAR deploy and BAR override
● Toolkit authorization
● Operational Policy administration
● Resource Statistics
5.1 Introduction
IBM Integration Bus V10 has enhanced the web browser user interface allowing administration of
Integration Nodes. This has replaced the majority of the admin function that was previously available in
the IB Explorer (IBX). A small amount of function was moved from the IBX to the Integration Toolkit –
Configurable Services, Policy sets.
The web user interface (known in this document as the Web UI) provides the following capabilities:
1.Ability to allow defined web users to perform administration at defined level
2.Ability to perform update actions (such as start and stop) against deployed resources
3.Ability to view trace and log files through the Web UI
4.Ability to view and update Node policy documents
5.Ability to deploy application BAR files
6.Resource statistics
This lab will demonstrate some of these points, while others are the subject of separate labs.
5.1.1 Reset IIB10NODE security (if necessary)
The first part of this lab assumes that security has not been activated for IB10NODE. If security has been
activated on your system, deactivate it now. To verify whether it security is activated, run the command
below in the Integration Console:
mqsireportbroker IB10NODE
Ensure that you see the line
Administration security = 'inactive'
To set security off, use the following commands in an Integration Command Console:
Lab 5 - Web administration interface and file-based security Page 177

IBM Software
mqsistop IB10NODE
mqsichangebroker IB10NODE –s inactive
mqsistart IB10NODE
5.1.2 Outline of lab
This lab will show you the following functions:

● Deployment of applications and libraries from the Web UI
● Explore Web UI without security
● Configure Web UI with role-based security:
 Activate file-based security
 Set administration roles
 Define web users
● Explore Web UI with role-based security:
 Web UI for “Read-only” user
 Web UI for “Read/ Write” user
 Web UI for “Read/ Write/ Execute” user

IBM Software
5.2 Prepare the IB10NODE applications
5.2.1 Application deployment in Web UI
__1. One of the first enhancements that you will explore in the new Web UI is the ability to deploy
BAR files. If it is not already open, open the Web User Interface in your Browser.
From the Integration Toolkit, right-click IB10NODE and select Start Web User Interface:
__2. You may see an “untrusted connection error” when the browser opens.
Click I understand the Risks, then Add Exception.
In the next window, click Confirm Security Exception.

IBM Software
__3. You will be using the integration server “server1”.
Expand Servers and click server1 to see its details:
__4. If you have done previous labs, you may already have resources deployed in this server. You
want to deploy fresh copies of the applications to the integration server, so delete any current
resources.
Under the “server1” Integration Server, expand Applications, click to open the context menu
available for the application and select Delete.
__5. Respond Yes when prompted to confirm the delete of the resource.
Do the same for all deployed resources under “server1”.

IBM Software
__6. Open the context menu next to “server1”. Click Deploy.
__7. This will open the window for BAR deployment.
Click Browse and navigate to C:\student10\Integration_service\solution.

IBM Software
__8. Select EmployeeServiceInterface.V10.bar and click Open:
__9. A message is shown that there are “No configurable properties found” in this shared library. This
means that the shared library that is being deployed does not include any configurable
properties.

IBM Software
Click Deploy in the “Deploy BAR File” window:
__10. Repeat steps 5 and 6. This time select EmployeeService.V10.bar and click Open.
In the Deploy BAR File preview window you will see that the Deploy Preview table has been
populated with properties existing in the BAR file. Note that you need to expand
EmployeeService.appzip to be able to see them.
In the Values column some of the properties show “<unset>”. This means that these properties
could be configured. This will be shown later in the lab.

IBM Software
Once finished reviewing, click Deploy.
__11. Repeat the above step and deploy EmployeeService_JSONClient.V10.bar. This time import
from C:\student10\Integration_service_JSONClient\solution folder.
Again, feel free to explore the properties and their values in the deployment table.
Please note that it may take a few seconds to see the updated view while the resources are
being deployed.

IBM Software
You should now have resources on server1 under the Services, Applications and Shared
Libraries categories:
__12. To see which applications or services reference the shared library, expand
EmployeeServiceInterface and then Referenced by. You will see the service and application
that you imported in the previous steps.

IBM Software
5.3 Overriding BAR file

The Web UI in Integration Bus V10 allows you to override BAR files during the process of deployment.
The override uses a file with an extension .properties. In the file, new values are specified for the
properties that need to be set.
__13. The override file for this lab has been created and is provided for you.
Using Windows Explorer, go to C:\student10\Integration_service_JSONClient\solution folder

and right-click Override_JSONClient.properties.
From the menu select Edit with Notepad++.
__14. In the override file, the properties that will be overridden are specified following the message flow
name that they refer to.
For the URL property in addition to the message flow name, the (HTTP) Node name is specified.
The property names can be seen from the Deploy BAR File window (step 5.2.1.10)
No changes will be made here so close the window once finished viewing the file.
__15. In the Web UI click again on the context menu next to “server1” and then click Deploy.
__16. Navigate to C:\student10\Integration_service_JSONClient\solution and select

EmployeeService_JSONClient.V10.bar.
Click Open.
__17. In the Deploy BAR File window you can see again the content of the BAR file. Expand
EmpServ_JSON_getEmployee.

IBM Software
In the Value column you are presented with the properties that can be configured.
“<unset>” refers to a property that has not been set. You can set the property using an override
file.
You will see two of the properties that were present in the override file.
__18. Scroll down and expand the HTTP Input node properties.
The URLSpecifier is the third property that you will override in the next step.
From the context menu next to “Overrides” click Select overrides file.

IBM Software
__19. Select Override_JSONClient.properties from the

C:\student10\Integration_service_JSONClient\solution directory and click Open.
__20. Now the URLSpecifier value has changed to /empServClient_getEmployee_Override
__21. To restore the original property values from the BAR file, click the down arrow beside
“Overrides”, click Clear overrides to cancel the deploy.
5.4 Explore Web Admin Interface (no security)
5.4.1 Administration
__22. You may have noticed in the top right corner of your web browser that you are logged in as a
“Default” user.

IBM Software
__23. Click IB10NODE. In Quick View, you will see that Admin Security is set to “Off”.
In this scenario, the default user has full update access to all deployed broker resources.
If you have enabled the web admin http listener, and security is not active for the node, then any
user will be able to access the Web UI.

IBM Software
__24. In the Servers section, expand server1. Expand the deployed applications and services. You
should see the applications you just deployed in the previous step.

IBM Software
__25. You will see that you can start and stop the services and applications, as well as any defined
server.
Click the server1 context menu – and select Stop.

IBM Software
__26. Wait for it to show stopped (red down arrow). Notice that you are not able to view any services or
applications. This is similar to the Integration Toolkit when an Integration Server is stopped.
Select the context menu again and select Start. The server will start and show a green up
arrow.
5.5 Integration Node and server properties

__27. Click IB10NODE and then click Edit:

IBM Software
__28. This will open a table with various Integration Node properties. You can change any of the
properties by clicking the button in the far right column of each property.
Click the button in the far right column to change the short description of the Integration Node.
__29. In the dialog box type “Workshop Node” and click OK.

IBM Software
__30. To save any changes that you have made to the Integration Node properties, click Save:
__31. Click server1 and then click the Edit button on the right, to view and edit properties for the
Integration Server:

IBM Software
__32. This will open a table with the Integration Server properties, which you can edit if required:
Scroll down to view the available Integration Server properties.
Previously, users of IBM Integration Bus were able to change these parameters in Integration
Explorer. IBM Integration Bus V10 has removed Integration Explorer, so all the administration is
available in the Web UI tool.
__33. You will not be making any changes here at this time, so when finished exploring click Cancel.

IBM Software
5.6 Configure role-based security for web users

Administration security controls the rights of users to complete administrative tasks for an integration
node and its resources.
IBM Integration Bus V10 provides the ability to control access to Integration Node resources through the
Web user interface and REST application programming interface (API). All the node administration
functions can be viewed and controlled, as well as all the functionality that in previous IIB releases was
available through IBM Integration Explorer. Different web users can have different access rights across
these functions, and access can be granted, denied or revoked quickly.
IBM Integration Bus V10 allows role-based security to be achieved by using one of two options:
● Security functions based on Integration Bus and WebSphere MQ
● File-based security in IBM Integration Bus
The user has the option to choose how to implement the role-based security, based on their
infrastructure. However, this guide will show the new functionality for IBM Integration Bus V10: enabling
file-based security.
The access authorities are defined against a set of user definitions that represent the available security
roles. A role is a set of security permissions that control access to an integration node and its resources,
and each web user account is associated with a particular role. The permissions are checked to
determine a web user's authorization to perform tasks in the web user interface or the REST API. Each
web user is then defined to use one or more of these security roles.
For the purposes of this lab, you will create several user roles. Then you will create web users and
assign them to one of the defined roles:
1. iibRole1 (for Node administration access, read-only)
2. iibRole2 (for Node administration access, read, write functions)
3. iibRole3 (for Node administration access, all functionality)
5.6.1 Activate security for IB10NODE
__34. Open an Integration Console by double-clicking the desktop shortcut or from the Windows start
menu.
Security can only be activated while the integration node is shut down, so issue the following
command:
mqsistop IB10NODE

IBM Software
When you issue the mqsistop, you will see that the Browser page is greyed with a message
indicating that “Real-time updates are disabled”.
__35. Use the following command to view in the Integration Console the authorization mode and
whether the administration security is active:
mqsireportauthmode IB10NODE
You will receive the response:
BIP8930I: Integration node name 'IB10NODE'
Administration security = 'inactive'
Authorization mode = 'mq'
As expected the administration security is returned as ‘inactive’.
Because the Integration Node has been created using a Queue Manager, its default
authorization mode is ‘mq’.
__36. Turn on the administration security and change the authorization mode with the command:
mqsichangeauthmode IB10NODE –s active –m file
You should see the response:
BIP8071I: Successful command completion.
Restart the Node with the following command:
mqsistart IB10NODE

IBM Software
__37. After a short while, reload the browser page by clicking the reload icon in the address page.
__38. You are now presented with a sign-on screen because security has been activated.
Before you can continue, you must configure security so you are able to sign in.
5.6.2 Define administration roles and set file-based permissions
You will now create administration roles and grant administration authorities to these roles. These will be
referenced by the Integration Bus web user definitions.
Three levels of authorization are supported for IBM Integration Bus administration security: read, write,
and execute. You can assign permissions to a role (user) by specifying the type of permission followed
by a plus (+) to grant permissions, or a minus (-) to revoke permissions.

IBM Software
The following table shows the file-based authorities that are required for different types of users in this
lab guide:
Role Authority
iibRole1 read
iibRole2 read, write
iibRole3 read, write, execute (all)
These authorities are related to actions as follows:

● read – view resources
● write – view resources, create Integration Servers and modify their settings
● execute – start, stop, deploy and modify resources
__39. Check if there are any roles defined on the Integration Node by running the command:
 mqsireportfileauth IB10NODE –l
You should see the response:

 BIP8071I: Successful command completion.
No defined roles have been returned.
__40. Create iibRole1 by running the command:
mqsichangefileauth IB10NODE –r iibRole1 –p read+
Response:
mqsichangefileauthIB10NODE –r iibRole2 –p read+,write+
Response:
mqsichangefileauth IB10NODE –r iibRole3 –p all+
Response:

IBM Software
__43. Re-run the command for displaying any defined roles:
mqsireportfileauth IB10NODE –l
The returned response should be as below:
BIP8931I: Role = 'iibRole1', Resource = '', Permissions =

'read+,write-,execute-

'read+,write+,execute-

'read+,write+,execute+
5.6.3 Define the web users for IB10NODE
__44. Define an Integration Bus web user for read-only access. This user will be able to see which
applications are deployed, but will not be able to control the status of these applications.
In an Integration Bus Command Console, run the command
mqsiwebuseradmin IB10NODE –c -u admin1 -a passw0rd -r iibRole1
This command will define a new web user, admin1. The user will have the security profile
defined by the associated role, which in this case will mean that the user can only view the
broker and any deployed applications.
Response: BIP8071I: Successful command completion.
__45. Define an Integration Bus web user for read/write access. This user will be able to see what
applications are deployed, and will have administration privileges to change properties on the
Integration Node and Integration Server.
In a Integration Console, run the command
defined by the associated role, which in this case will mean that the user will be able to view the
broker and execution groups, and edit their properties. Also, the user will be able to view the
deployed resources.

IBM Software
__46. Define an Integration Bus web user for all access. This user will be able to see what applications
are deployed, and will be able to control completely the resources (start, stop, deploy and
modify).
In a Integration Console, run the command
defined by the associated role, which in this case will mean that the user will be able to view the
broker and execution groups, and any deployed applications, as well as control their status.
__47. Display the newly-defined web users by running the command
mqsiwebuseradmin IB10NODE –l
The response received should be as below:
BIP2837I: Web user 'admin1' is defined as having a role of 'iibRole1'.
5.7 Using the Web Admin interface with security
5.7.1 The Web Admin interface for a read-only user
Now that security has been configured for Web Admin users, you will log in as the admin1 user, which is
read-only, and see what the browser interface offers for someone who can only view the Integration
Node.
__48. You should have your Firefox web browser window still open with the IBM Integration login page.
Log in with the userid admin1 (password is “passw0rd”).

IBM Software
__49. This user has read-only access to the node.
Note that the Quick View will now show you that Admin Security is active.
Expand the Servers category.

IBM Software
__50. You will see that you are presented with the available servers but you are not able to view any of
the resources.
Although you gave the role iibRole1 “read” authorities, you specified this at a Node level. This
allows more granular approach by authorization for individual servers completed with a separate
command (shown in the next step).
__51. The IIB file-based authorization allows you to change the roles’ permissions without a restart of
the Integration Node—the changes are picked up dynamically.
In the Integration Console, run the command:
mqsichangefileauth IB10NODE –e server1 –r iibRole1 –p read+
The Integration Server has been specified with the parameter –e server1, which means that
now you are applying the permissions at the integration server’s level.
__52. Back in the browser, refresh the page and log in again as user admin1.
Note that to the left of “server1” there is now a twistie. If you click on the twistie you will be able
to view the resources in server1.
Expand server1.

IBM Software
__53. You can now view the resources on the Integration Server. Note that although you are able to
expand the server1 resources folders you do not have permission to start, stop or perform other
actions on the deployed artefacts.
__54. Click the arrow to the right of Servers and then click Create:
__55. In the opened dialog box type “admin1server” and click OK:

IBM Software
__56. You will see a message is shown above the Overview tab that the Integration Server cannot be
created. Hover with your mouse over the notification and you will notice that this is a hyperlink,
so click it.
__57. You will see a detailed message, explaining why the attempt has failed:
5.7.2 The Web Admin interface for user with write access
Now that security has been configured for Web Admin users, you will log in as the admin2 user, which is
the “read/write” user. This user has functionality for viewing resources, editing properties for Integration
Node and Integration Server, and for creating Integration servers.
__58. After exploring the facilities for admin1, log out admin1.
Click the pull-down menu next to the “Welcome, admin1” banner and select Log Out.

IBM Software
__59. Log in as admin2 (password is “passw0rd”).
__60. Expand Servers and you will see that although you can view the available servers, the role to
which admin2 is associated is not authorized for server1.
This is because admin2 has read/write access for IB10NODE, but not for any servers.
__61. In the Integration Console, run the command:
mqsichangefileauth IB10NODE –e server1 –r iibRole2 –p read+,write+
This will allow this role to view the resources on server1, create and modify Integration Servers.
__62. In the Web UI, refresh the login for admin2 (press F5 or the refresh button).
You are now able to view the server resources as admin1 but again you are not able to perform
any administration on the resources.

IBM Software
Highlight server1. You will see there is an “Edit” button (which was not available for admin1).
Click the Edit button.

IBM Software
__63. The table with server1’s properties is opened and the user admin2 has authority to change its
settings.
You will not make any changes here, so when finished reviewing, click Cancel.
The user admin2 has the same permissions for changing settings on the IB10NODE.
__64. Click the arrow on the right of “Servers” and then click Create:

IBM Software
__65. In the dialog box enter “admin2server” and click OK:
__66. Soon, you will see that a new Integration Server has been created. The user admin2 has “write”
authorities, which allows creating a new server on the Integration Node.
However, even though this user has created the Integration Server, the administrator has to
authorize the role to which admin2 is associated to perform any actions on the new server such
as start or stop.
__67. In the Integration Console run the command;
mqsichangefileauth IB10NODE –e admin2server –r iibRole2
–p read+,write+
This sets the permissions for this role on the admin2server server as read and write.

IBM Software
__68. Refresh the browser window and log in as admin2 again (you may be automatically logged in
after the refresh).
Now, the web user is able to view the newly created server and its resources. Note that no
resources have been deployed at this point.
__69. Log out the user admin2.
5.7.3 The Web Admin interface for a user with ‘all’ access
You will now log in as the admin3 web user, which has full authorities. This user has full functionality for
the resources including stop/start deployment of applications and start/stop statistics.
__70. Although admin3 has full authorities for the resources on the node, the administrator still has to
give permissions to the role, to which the web user is aligned for a particular Integration Server.
Run the command:
mqsichangefileauth IB10NODE –e server1 –r iibRole3 –p all+
__71. Log in as admin3 (password is “passw0rd”).
__72. Expand the Servers group, then server1.

IBM Software
You may have noticed that now, on the right side of “server1” there is an arrow, which was not
there for admin1 and admin2 web users. Click the arrow.
__73. You will see that a new drop-down menu has opened showing all the administration tasks that
web user admin3 can perform. Click Stop to stop the Integration Server.

IBM Software
__74. After a few seconds you will see that the integration server has stopped, as indicated by a small
red arrow pointing down.
__75. Expand the menu again and click Start to start the Integration Server again. As expected, most
of the available actions have been greyed out because the server is stopped.

IBM Software
__76. When the Integration Server starts, expand the Applications group and then click the twistie
next to the EmployeeService_JSONClient application. From the pull-down menu, click Stop:
__77. The application and all its flows have been stopped, as indicated by red arrows pointing down:
__78. Expand the pull-down menu and click Start to start the application again.

IBM Software
__79. Once the application has started, click EmployeeService_JSONClient. On the right, expand
Advanced Properties and Deployed Properties.
The Quick View panel displays important information about the application such as its name,
UUID, and Run Mode.
Advanced Properties and Deployed Properties show more detailed information.
__80. Log out user admin3.

IBM Software
5.7.4 Administration of operational policy
In this part of the lab you will explore the administration of MQEndpoint Policy from users with different
permissions based on the roles they have been assigned to.
__81. In the Integration Console, navigate to c:\student10\webadmin\Install and type the following
command:
mqsicreatepolicy IB10NODE -t MQEndpoint –l WebAdminPolicy
-f MQEndpointSample.xml
The command references an MQEndpoint configuration policy file MQEndpointSample.xml,

which has been provided for you.
The result you see should be as below:
__82. Log in to the Web UI as admin1 (password is “passw0rd”).
Under IB10NODE, expand Operational Policy > MQEndpoint and click the newly created
policy.
This user has “read-only” permission and is only able to view the defined values.
The values specified have been taken from the policy configuration file.

IBM Software
__83. Log in to the Web UI as admin3 (password is “passw0rd”).
Navigate to the newly created policy and click it.
This user has all permissions and is able to re-configure the policy details and delete the policy.
__84. In the Integration console run the command from step 5.7.4.81, but this time use the flag –i to
specify a user, their password and hostname.
mqsicreatepolicy IB10NODE -t MQEndpoint
-i tcp:\\admin3:passw0rd@betaworks-esb10 –l admin3_policy
-f MQEndpointSample.xml
__85. In the command console a message will be returned (BIP1921S) notifying you that the node
cannot be reached (if you are using the workshop VMware image supplied).
The reason this message is returned is because on the IB10NODE the SSL has been enabled. If
you would like multiple users to connect to a remote integration node that has SSL enabled on
its web administration port to execute a command, you will need to use .broker file.
This is not subject of this lab. Please refer to IBM Knowledge Center for more information.

IBM Software
5.7.5 Handle configurable services
__86. In the Web UI log in as admin1 (password is “passw0rd”)
Expand Operational Policy > Configurable Services > ActivityLog.
Click ActivityLogTemplate:
Remember that web user admin1 was assigned to a role that has only “read” permissions.
Therefore admin1 can only view the Configurable Services but not their details.
__87. Log in as user admin2 and again expand Activity Log:

IBM Software
Since admin2 web user has “read” and “write” permissions (assigned to the iibRole2), the user is
able to view the Configurable Service template and edit using the Edit button.
In addition, you can see that next to Configurable Services and ActivityLogTemplate there are
arrows.
Click the arrow next to Configurable Services.
__88. In the drop-down menu, select Create:
__89. Name the new configurable service “NewConfigService”.
As a type, leave “ActivityLog”.
Note that from the drop-down menu you are able to select and create any configurable service.
The selected type will update its corresponding Properties template.
Save the new configurable service without making any other changes.

IBM Software
__90. You are now able to see the new configurable service that you created. Click the arrow next to it.
You will see that admin2 user has permissions to delete and export the configurable service.
Click Export *.configurableservice.
__91. Click Save File and then OK.
__92. Navigate to c:/student10/webadmin and click Save.
Now you have the configurable service saved on your file system.
__93. Log out admin2.
5.8 Integration Toolkit authorization

The defined Web users’ authorities also apply for a remote connection of an Integration Toolkit to an
existing Integration Node.
__94. Create a remote connection to IB10NODE from the Integration Toolkit.

IBM Software
__95. Connect as admin3 (password is “passw0rd”), providing the connection details as below:
Host: betaworks-esb10
Port: 4421
Integration Node: IB10NODE
Use SSL: selected
__96. Click Finish.
You may see a progress information window to which you may have to respond before
continuing.

IBM Software
__97. You will be presented with a dialog, where you will need to confirm the Trust certificate.
Click Trust Certificate to continue.
__98. Expand server1 under the remote connection and you will see all the deployed resources.
User admin3 will also have the permissions to deploy resources from the Integration Tookit,
which will not be explored at this time.

IBM Software
__99. Click the newly created connection and then Remove Connection.
__100. After the previous step has been completed, create a new connection by repeating steps 5.8.94
and 5.8.95, only this time user will be admin1. Click Finish.

IBM Software
__101. You will receive an error message saying that the role to which the user is assigned does not
have the required permissions.
Click OK.
__102. In the Integration Nodes view you will see that the remote connection has been created.
However, even though you have connected as a user with “read” permissions, you are not able
to see the resources deployed to server1.
The reason for this restriction is that the Integration Toolkit is designed to “develop and deploy”.
Therefore, the user is not allowed to view resources on a node to which they do not have
permission to deploy.
Note that you may be able to open the Policy Sets editor and make edits, but you will not be able
to save them as admin1 does not have the permission for that.
5.9 Resource statistics

In this part of the lab, you will explore the IBM Integration Bus resource statistics available in the Web UI.
__103. Log in to the Web UI log in as admin3 (password is “passw0rd”).

IBM Software
Once logged in, click the arrow next to server1 and from the menu select Resource statistics
on.

IBM Software
__104. A message will appear once the resource statistics have been turned on.
Click the Resource Statistics tab.
__105. The data has started being collected and shortly you will see values for the three default
parameters: Initial memory, Used Memory and Committed Memory.

IBM Software
__106. To the right of the graphs there are tables with data about the resource. This is where you can
change the resource shown on the graph.
Click the arrow to view the available resources. The currently displayed resource is highlighted.
Do not change the selection at this time.
__107. Scroll down to see the server1 resource statistic table.
Click to the left of each resource and you will see that a different color is assigned to each
resource. Along with that, the selected resources are added color-coded to the graphs above so
you can easily identify the resource and compare it with others.

IBM Software
__108. Hover over any of the graphs with the mouse. You will see that the graphs are highlighted and
the values used to draw them are shown as dots. Placing the mouse over any of the dots will
show its value.
__109. From the Start menu, open SoapUI.
Expand EmployeeService completely and double-click the saved test Employee 000010.
Run the test a few times by clicking the green button.

IBM Software
__110. Back in the resource statistics view in the browser you will see that this is reflected in the
captured resource statistics.
__111. As a final step stop the Integration Node and turn off the administration security:
mqsistop IB10NODE
mqsichangebroker IB10NODE –s inactive
5.10 Summary
This concludes the Web Admin lab. Web users with the required authorization can administer services,
applications and other resources on the Integration Node.
END OF LAB 5

IBM Software
Lab 6 Implementing a service interface

You can integrate applications by using a service-oriented architecture (SOA). In an SOA, a service is
often defined as a logical representation of a repeatable activity that has a specified outcome. Typically,
a service is self-contained and its implementation is hidden from its consumers. To facilitate their re-use,
services define a prescribed interface, which specifies how data is exchanged with the service.
In IBM Integration Bus (IIB) an Integration Service is a specialized application with a defined interface
and structure that acts as a container for a web services solution. The interface is defined through a
WSDL file. The Integration Service Project contains message flows and sub-flows to implement the
specified web service operations and fault handlers. During this lab you will experience the powerful
development features and best-practices provided by the Integration Service Application.
You can create an integration service by using any of the following methods:
● You can create an integration service from scratch
● You can create an integration service by selecting an existing WSDL
● You can create an integration service from a Business Process Manager integration
service
For this lab you will create an integration service by implementing the service interface in the
EmployeeServiceV1 WSDL. Be aware that you can create an integration service by using the “Start from
WSDL” wizard but you must manually create and maintain the structure of the projects and the
organization of the artifacts, and the powerful Integration Service Application development features are
not available. By the end of this lab you will understand the benefits of using an Integration Service
Application.
Like an application, an integration service can reference resources in shared libraries. The shared library
is deployed before or with the integration service. If you update the resources in the shared library and
redeploy it, those changes are immediately available to the deployed integration service. For this lab the
EmployeeServiceV1 WSDL, XSDs and Maps are contained in shared libraries.
When you implement an integration service, you can deploy it to an integration server just like an
application. You can start and stop the deployed service as you would an application.
A “service interface” consists of one or more operations and a binding style.
An operation is a description of an action that is implemented by the service. Each operation can have
either of the following types:
● Request-response type operations mean that a request is sent and a response returned to
the interface.
● One-way type operations mean that only a request is sent, and no response is needed.
Each operation in the interface defines the data that can be passed in the form of inputs to and outputs
from the component when the operation is called. A one-way operation has only an input. A request-
response operation has both an input and output. For this lab, the EmployeeServiceV1 service interface
defines five request-response operations.
Lab 6 - Implementing a service interface Page 229

IBM Software
You will use the Start by Creating an Integration Service wizard to import the EmployeeServiceV1 WSDL
and create the Integration Service Application project. You will then implement the service interface
operations defined in the EmployeeServiceV1 WSDL, deploy the Integration Service and test the
implementation.
If you plan to perform Lab 7 – Creating a REST API – you will wrap the EmployeeServiceV1 web service
operations with a REST API.
6.1 IIB configuration

For lab execution consistency the default Integration Sever has been configured to explicitly use port
7800 for its embedded listener. All SOAP and HTTP Input nodes deployed to the default Integration
Server on the TESTNODE Integration Node will use port 7800. This has been preconfigured with the
following command, which explicitly sets the embedded listener’s port number:
mqsichangeproperties RESTNODE -e default -o HTTPConnector -n

explicitlySetPortNumber -v 7800
The prebuilt maps used to implement service operations access the DB2 SAMPLE database. These
maps use information from a JDBCProviders Configurable Service to connect with the SAMPLE
database. The Configurable Service can be created at the command-line or using the Web UI. The Web
UI provides Configurable Service import/export functionality using a simple XML file:
6.2 Implementing a service interface lab workspace

In this section of the lab you will import the necessary projects to complete the “Implementing a service
interface” lab.
The Proof of Technology (PoT) workspace for this lab is located at

C:\student10\workspaces\ServiceInterface. It is recommended that you use this workspace for the lab.
If you currently have the Toolkit open using a different workspace, you can switch to the
C:\student10\workspaces\ServiceInterface workspace by following the instructions.
__1. Open the IIB Toolkit, if it is not already open.

IBM Software
To start with the new workspace, enter C:\student10\workspaces\ServiceInterface and click

OK:
If you are currently working in another workspace, select File > Switch Workspace > Other.

IBM Software
Specify a path of:
C:\student10\workspaces\ServiceInterface.
Close the Welcome view:
__2. Right-click the Application Development View and select Import.
__3. Expand IBM Integration, select Project Interchange and click Next.

IBM Software
__4. Click Browse.

IBM Software
__5. Select the following Project Interchange file and click Open:
C:\student10\ServiceInterface\resource\ServiceInterface_PI.zip
__6. Select all of the projects and click Finish:

● BAR files
● EmployeeServiceSOAPMaps_Lib
● EmployeeServiceSOAP_Lib
● SAMPLE_DDPrj

IBM Software
__7. Your Workspace should contain the following artifacts:

a.EmployeeServiceSOAP_Lib – WSDL and XSDs for EmployeeService web service
b.EmployeeServiceSOAPMaps_Lib – Maps that implement the EmployeeService web
service operations
c. EmployeeServiceSOAP.bar – BAR file to deploy EmployeeServiceSOAP_Lib and
EmployeeServiceSOAPMaps_Lib.
6.3 Implementing a service interface lab deployment

The “Implementing a service interface” Lab requires that the EmployeeServiceSOAP_Lib and
EmployeeServiceSOAPMaps_Lib shared libraries be deployed to the default Integration Server on the
TESTNODE Integration Node.
__8. If you have performed other labs as part of the PoT and have deployed resources to the default
Integration Server on the TESTNODE Integration Node you will delete them now so they do not
interfere with this lab.
In the Integration Nodes view, expand TESTNODE > default.
Right-click the default Integration Server and select Delete > All Flows and Resources:

IBM Software
__9. In the Application Development View expand Independent Resources > BAR files > BARs and
select EmployeeServiceSOAP.bar. Drag and drop the EmployeeServiceSOAP.bar BAR file
to the default Integration Server on the TESTNODE Integration Node.
__10. You should see the following libraries and service interfaces deployed to the default Integration
Server:
6.4 Implementing the service interface

In this section you will create an Integration Service by implementing the service interface defined in the
EmployeeServiceV1 WSDL.
The IIB Start by Creating an Integration Service wizard will be used to create the Integration Service
Application Project. You will then use the development features of the Integration Service Application to
implement the service interface.

IBM Software
Although implementing a service interface could be done in previous IIB versions, the project’s many
development artifacts had to be built manually. Using the Integration Service wizard and project
eliminates a large number of development tasks and allows the developer to focus on implementing the
service interface.
In this lab you will implement five of the operations defined in the EmployeeServiceV1.wsdl document.
These operations will implemented by using existing maps that access the DB2 SAMPLE database; this
allows the lab to focus on the service interface development process.
You will implement the following operations defined in the EmployeeServiceV1 WSDL document:
● getDepartment – get details for a specific department
● getDepartmentEmployees – get all employees for a specific department
● getEmployee – get details for a specific employee
● getEmployeeDepartment – get department details for a specific employee
● predictSalary -- get predicted salary for a specific education level
__11. In the Application Development view, select New > Start By Creating an Integration Service

IBM Software
__12. Enter “EmployeeService_SOAP” for the name, select Implement an interface already
specified in an existing WSDL file and Use an existing WSDL in shared library, then click
Next.
__13. Expand EmployeeServiceSOAP_Lib > WSDL Definitions >

http://www.example.org/EmployeeServiceV1/, select EmployeeServiceV1.wsdl and click
Next:

IBM Software
__14. Select the EmployeeServiceV1SOAP binding and click Finish:

IBM Software
__15. Observe the Integration Service project structure and the Integration Service description. Note
the five operations that will be implemented:
__16. Right-click the EmployeeService_SOAP Integration Service Application and select Manage
Library References:
__17. Make sure both EmployeeServiceSOAP_Lib and EmployeeServiceSOAPMaps_Lib are

checked, and click OK:

IBM Software
__18. In the EmployeeService_SOAP Integration Service Definition, click the Interface tab to display
the service interface that you will implement:
__19. Observe the “getDepartmentEmployees” operation. To view its input, click

getDepartmentRequest_Type and when the type selection drop-down list appears right-click
and select Open in XSD Editor:

IBM Software
__20. The input request message contains a single element named “deptNumber”. Click the X to close
the schema:

IBM Software
__21. To view its input, click employees_Type, and when the type selection drop-down list appears
right-click and select Open in XSD Editor:
__22. Observe that the “employees_type” can contain multiple employee_type elements. Click the X to
close the schema:

IBM Software
__23. Be aware that the Interface tab is for design and you can modify the service interface by adding
new operations or modifying existing operations. You will not be modifying the service interface
during this lab; rather, you will be implementing the service interface which is done on the
Service tab. Select the Service tab to start implementing the service interface:
__24. You will now implement the getDepartment operation. In the Integration Service view click the
getDepartment operation to open the getDepartment_request_response sub-flow:

IBM Software
__25. Observe the getDepartment_request_response.sub-flow sub-flow in the

EmployeeService_SOAP Integration Service project and in the message flow editor. The
operation’s implementation is the sub-flow:
__26. You will now add a mapping node that will perform the database query for the operation
implementation. In the Message Flow Editor, expand the Transformation node category, select
the Mapping node and drop it between the Input and Output nodes. Rename the node
“getDepartment”:

IBM Software
__27. Highlight the getDepartment node. In the Properties View, select the Basic tab and click
Browse for the Mapping routine* property:
__28. Select the {default}:getDepartmentMap map and click OK:

IBM Software
__29. Double-click the getDepartment node to open the map. Click the icon in the upper-right corner
of the Select from SAMPLE source to open the database select dialog:
Here the query is being performed on the DEPARTMENT table. The WHERE clause was
generated by selecting columns from the table, elements from the Input and Operators:
Close the Select dialog.

IBM Software
__30. Expand SOAP_Domain_Msg > Body in the output. Observe that the output body can contain
either a fault or a getDepartmentResponse message; this allows the map to create a
getDepartmentResponse if a valid result set is returned from the select, or a fault if an empty
result set is returned or a database error occurs. Click the arrow icon in the upper-right corner
of the Local map transformation to view the mapping of the result set to the SOAP Body:
__31. Observe the “Failure” transform maps to a “Fault” message and the “Select” transform maps to a
“Fault” and a “getDepartmentResponse” message. The “Select” transform will generate a “Fault”
message if an empty result set is returned. The “Failure” transform will automatically handle any
database errors that occur. Click the arrow icon in the upper-right corner of the Select
transform to view the map:

IBM Software
__32. You can view the “If” transform’s condition by hovering the mouse pointer over the yellow
diamond icon to the left. If the result set contains data then a “getDepartmentResponse”
message is mapped; otherwise a “Fault” message is mapped. Click the yellow arrow in the
upper-right of the map to return to the parent map:
__33. Click the arrow icon in the upper-right of the Failure transform to view the map:
__34. Observe the database error information that is returned and the mapping to the Fault message.
Click the yellow arrow icon in the upper-right of the map to return to the parent map:

IBM Software
All of the other maps function in the same manner except the map for the predictSalary
operation, which is a sequence of IF, ELSE IF statements that returns a salary for ranges of
education levels. You can observe the other maps as you implement other operations if you like.
__35. Close the getDepartmentMap map by clicking the X in the getDepartmentMap tab:
__36. Connect the Out terminal of the Input node to the In terminal of the getDepartment node.
Connect the Out terminal of the getDepartment node to the In terminal of the Output node.
Enter CTRL+S to save the getDepartment sub-flow:
__37. You will now implement the “getDepartmentEmployees” operation. Click the arrow to the right of
EmployeeService_SOAP to list the service interface operations. Select
getDepartmentEmployees:

IBM Software
__38. Observe that the “getDepartmentEmployees_Request_Response.sub-flow” has been created

and opened in the message flow editor. This sub-flow implements the getDepartmentEmployees
operation:
“getDepartmentEmployees”:

IBM Software
__40. Highlight the getDepartmentEmployees node. In the Properties View select the Basic tab and
click Browse for the Mapping routine* property:
__41. Select the {default}:getDepartmentEmployeesMap map and click OK:

IBM Software
__42. Connect the Out terminal of the Input node to the In terminal of the getDepartmentEmployees
node. Connect the Out terminal of the getDepartmentEmployees node to the In terminal of the
Output node. Enter CTRL+S to save the getDepartmentEmployees sub-flow:
__43. You will now implement the getEmployee operation. Click the arrow to the right of
EmployeeService_SOAP to list the service interface operations. Select getEmployee:
__44. Observe that the “getEmployee_Request_Response.sub-flow” has been created and opened in
the message flow editor. This sub-flow implements the “getEmployee” operation:

IBM Software
“getEmployee”:
__46. Highlight the getEmployee node. In the Properties View select the Basic tab and click Browse
for the Mapping routine* property:

IBM Software
__47. Select the {default}:getEmployeeMap map and click OK:
__48. Connect the Out terminal of the Input node to the In terminal of the getEmployee node.
Connect the Out terminal of the getEmployee node to the In terminal of the Output node. Enter
CTRL+S to save the getEmployee sub-flow:
__49. You will now implement the “getEmployeeDepartment” operation. Click the arrow to the right of
EmployeeService_SOAP to list the service interface operations. Select
getEmployeeDepartment:

IBM Software
__50. Observe that the “getEmployeeDepartment_Request_Response.sub-flow” has been created and

opened in the message flow editor. This sub-flow implements the getEmployeeDepartment
operation:
“getEmployeeDepartment”:

IBM Software
__52. Highlight the getEmployeeDepartment node. In the Properties View, select the Basic tab and
click Browse for the Mapping routine* property:
__53. Select the {default}:getEmployeeDepartmentMap map and click OK:

IBM Software
__54. Connect the Out terminal of the Input node to the In terminal of the getEmployeeDepartment
node. Connect the Out terminal of the getEmployeeDepartment node to the In terminal of the
Output node. Enter CTRL+S to save the getEmployeeDepartment sub-flow:
__55. You will now implement the “predictSalary” operation. Click the arrow to the right of
EmployeeService_SOAP to list the service interface operations. Select predictSalary:
__56. Observe that the “predictSalary_Request_Response.sub-flow” has been created and opened in
the message flow editor. This sub-flow implements the predictSalary operation:
“predictSalary”:

IBM Software
__58. Highlight the predictSalary node. In the Properties View, select the Basic tab and click Browse
__59. Select the {default}:predictSalaryMap map and click OK:

IBM Software
__60. Connect the Out terminal of the Input node to the In terminal of the predictSalary node.
Connect the Out terminal of the predictSalary node to the In terminal of the Output node. Enter
CTRL+S to save the predictSalary sub-flow:
__61. You will now implement a “Catch Handler” for the integration service. Click
EmployeeService_SOAP to display the service interface operations and handlers:
Under Error Handlers, click Catch:

IBM Software
__62. Observe that the “EmployeeService_SOAP_Catch.sub-flow” has been created and opened in
the message flow editor. This sub-flow implements a Catch Handler that will handle exceptions
that occur during message flow processing:
__63. You will now add a mapping node that will generate a SOAP Fault for exceptions that occur
during message flow processing. In the Message Flow Editor, expand the Transformation node
category, select the Mapping node and drop it between the Input and Output nodes. Rename
the node “catchHandler”:
__64. Highlight the catchHandler node. In the Properties View, select the Basic tab and click Browse

IBM Software
__65. Select the {default}:catchHandler map and click OK:
__66. Connect the Out terminal of the Input node to the In terminal of the catchHandler node.
Connect the Out terminal of the catchHandler node to the In terminal of the Output node. Enter
CTRL+S to save the Catch Handler sub-flow:

IBM Software
__67. You’ve completed implementing the “EmployeeService_SOAP” service interface, but you might
be wondering -- where is the message flow? Up to this point you’ve only worked with sub-flows
that implemented the service interface operations and catch handler, but you have not seen the
main message flow with a SOAPInput and SOAPReploy nodes.
Expand EmployeeService_SOAP > Resources > Flows > gen to find the main flow:
EmployeeService_SOAP.msgflow:
Double-click EmployeeService_SOAP.msgflow and notice that the Integration Service

Definition is opened and not the message flow in the message flow editor.
Right-click EmployeeService_SOAP.msgflow and select Open With > Message Flow Editor
to open the flow in the message flow editor:

IBM Software
__68. Observe the main flow in the message flow editor. Note the warning about modifying the
message flow. Also note that the Flow Exerciser is not accessible from the message flow; it is
only accessible from the Integration Service Definition. Click the X to close the
EmployeeService_SOAP message flow:
6.5 Deploy the EmployeeService_SOAP Integration Service

Note that the packaging and deployment of an Integration Service Application is the same as packaging
and deploying an application.
You will not manually deploy the EmployeeService_SOAP Integration Service for this lab, rather the Flow
Exerciser will automatically package and deploy the Integration Service when it is started in the next
section of the lab (Testing the EmployeeService_SOAP Integration Service).
In this section you will use the IIB V10 Flow Exerciser to deploy and test the EmployeeService_SOAP
Integration Service.

IBM Software
__69. In the EmployeeService_SOAP integration service editor, click the red Start Flow Exerciser
button in the upper-right corner:
Note: Starting the Flow Exerciser will deploy the EmployeeService_SOAP Integration Service
Application.
__70. Note that you will use the “Send Message” button to send SOAP requests to the web service.
Click Close:

IBM Software
__71. You will now test the “getDepartment” operation. Click the Send Message button in the upper-
right corner:
__72. Click the New Message button to create a request message:

IBM Software
__73. Select the getDepartment operation. Enter “getDepartment” for the name. Enter “C01” for
deptNumber. Click Apply.
__74. Click the Send button to send the getDepartment message:
__75. Observe that the request was sent and a response was received:

IBM Software
__76. Click the envelope between SOAP/HTTP Binding and getDepartment to view the request
message that was received. Note that the SOAP Envelope has been removed. Click the X in the
Recorded Message window to close it:
Note: All components of the Message Assembly are available for inspection.

IBM Software
__77. Click the green getDepartment operation to open the sub-flow:
__78. Click the envelope between the getDepartment and Output nodes to view the response
message that will be sent. Note that the message contains a SOAP envelope. Click the X in the
upper-right corner of the Recorded Message window:
__79. Click the Send Message button to send another request message:

IBM Software
__80. Select the getDepartment message. Change the value of deptNumber to “C09” and click Send:
__81. Observe that an error has occurred—the getDepartment operation has returned a SOAP Fault
because no “C09” department was found. Click Error sending message to SOAP Input to
view the fault message. Click Close:

IBM Software
__82. Click the Send Message button to send another request message:
__83. Select the getDepartment” message. Change the value of deptNumber to “C099” and click
Send:

IBM Software
__84. Observe that an error has occurred. A database failure has occurred because “C099” has
exceeded the length of the DEPTNO column in the DEPARTMENT table. Click Error sending
message to SOAP Input to view the fault message. Click Close:
__85. Click the Send Message button to send a request message to the getDepartmentEmployees
operation:

IBM Software
__86. Click the New Message button to create a getDepartmentEmployees request message:
__87. Enter “getDepartmentEmployees” for the name. Select getDepartmentEmployees from the
SOAP operation drop-down list. Enter “C01” for deptNumber. Click Apply:
__88. Click Send to test the getDepartmentEmployees operation:

IBM Software
__89. Observe that a request message was sent and a response message was successfully received.
Click Received HTTP Reply message for SOAP Input to view the response message. Click
Close:
You can try other deptNumber values such as “C09” and “C099” to validate that faults are
correctly generated.

IBM Software
__90. Click the Send Message button to send a request message to the getEmployee operation:
__91. Click the New Message button to create a getEmployee request message:

IBM Software
__92. Enter “getEmployee” for the name. Select getEmployee from the SOAP operation drop-down
list. Enter “000060” for employeeNumber. Click Apply:
__93. Click Send to test the getEmployee operation:

IBM Software
Close:
You can try other deptNumber values such as “000066” (empty result set) and “0000666”
(column length exceeded) to validate that faults are correctly generated.
__95. Click the Send Message button to send a request message to the getEmployeeDepartment
operation:

IBM Software
__96. Click the New Message button to create a getEmployeeDepartment request message:
__97. Enter “getEmployeeDepartment” for the name. Select getEmployeeDepartment from the
SOAP operation drop-down list. Enter “000060” for employeeNumber. Click Apply:

IBM Software
__98. Click Send to test the getEmployeeDepartment operation:
Close:
You can try other employeeNumber values such as “000066” (empty result set) and “0000666”
(column length exceeded) to validate that faults are correctly generated.

IBM Software
__100. Click the Send Message button to send a request message to the predictSalary operation:
__101. Click the New Message button to create a predictSalary request message:
__102. Enter “predictSalary” for the name. Select predictSalary from the SOAP operation drop-down
list. Enter “16” for educationLevel. Click Apply:

IBM Software
__103. Click Send to test the predictSalary operation:
Close:
__105. You can try other educationLevel values such as “8” (education level too low) and “22”
(education level too high) to validate that faults are correctly generated.

IBM Software
__106. Click the X in the EmployeeService_SOAP tab to close the service interface editor:
6.6 Explore Integration Service using Web Admin

In this lab section you will use the V10 Web Admin to observe the EmployeeService_SOAP integration
service.
__107. In the Integration Nodes view, right-click TESTNODE and select Start Web User Interface:
__108. Expand Servers > default > Services > EmployeeService to observe the
EmployeeService_SOAP integration service:

IBM Software
__109. Click the EmployeeService_SOAP drop-down arrow to observe the actions that can be taken.
Note that Save Interface File will provide the EmployeeServiceV1 WSDL and XSD files
packaged in a zip file:

IBM Software
__110. Click the gen.EmployeeService_SOAP.msgflow drop-down list to observe the actions that can
be taken. Note that Attach Policy is where a Workload Management Policy would be applied to
the EmployeeService_SOAP Integration Service:

IBM Software
6.7 Summary
During the “Implementing a service interface” lab the Start by Creating an Integration Service wizard was
used to import the EmployeeServiceV1 WSDL document and create an Integration Service Application
project. You observed the structure, organization and contents of the Integration Service Application and
how it offers IIB design and implementation best practices.
You used the interface view to observe the defined service interface and investigated the schemas for an
input and output.
You used the Integration Service Application tooling to quickly implement five operations and a catch
handler.
The new V10 Flow Exerciser was used to deploy the EmployeeService_SOAP integration service and
test its operations.
The Web User Interface was used to observe the deployed EmployeeService_SOAP integration service
and the administration and operations functions that are available.
END OF LAB 6

IBM Software
Lab 7 Creating a REST API service

In earlier versions of IBM Integration Bus (IIB), implementing a REST API required the developer to
manually handle inbound HTTP requests, and routing of those requests. Programming was required to
process variable paths in the request and extract path parameters. Although IIB provided the capabilities
to implement REST APIs it did not provide tooling to automate the development process and decrease
development time, or provide design and implementation best-practices.
IIB V10 has introduced a new type of project, or container, called a REST API. A REST API in IBM
Integration Bus is a specialized application that allows you to expose a set of resources as a RESTful
web service.
To create a REST API in IBM Integration Bus, you must first define the resources and operations that are
available in the new REST API. Those definitions must be specified in a Swagger document, an open
specification for defining REST APIs.
To create a REST API in IBM Integration Bus, you use the Create a REST API wizard in the IBM
Integration Toolkit to import a Swagger document. You must then create the REST API sub-flowsub-
flowssub-flows and other project artifacts that are required to implement and deploy the new REST API.
Operations defined in the REST API are implemented as normal sub-flowsub-flows.
The REST API container automatically takes care of the routing of inbound HTTP requests to the correct
sub-flow for the operation being called and processing of input parameters.
You simply need to connect the dots between the Input and Output nodes in each operation’s sub-flow!
Catch, Failure and Timeout handlers are implemented as sub-flowsub-flows as well; IIB handles the
HTTP response code automatically.
REST APIs support all of the Integration Bus features that you can use with applications (such as shared
libraries, monitoring, activity log), and all message flow nodes can be used within a REST API.
A REST API application is deployed like existing applications. There are new artifacts, such as the
Swagger JSON document, but IIB handles these automatically and you simply drag and drop the REST
API application to deploy it from the Toolkit.
All administrative and operational controls that are available for applications in IIB are also available for
REST API applications, this includes command-line programs. The IIB Web UI has been extended to
provide information about resources, operations and parameters that are available in a deployed REST
API application.
During this lab you will explore a Swagger JSON document that defines the EmployeeServiceV1 REST
API, use the Create a REST API wizard to import the document and then implement five of the
operations defined in the EmployeeServiceV1 REST API. You will then deploy and test the
EmployeeServiceV1 REST API.
The REST API lab requires the EmployeeService SOAP web service that was implemented and
deployed in Lab 6, “Implementing a service interface”. If you performed the “Implementing a service
interface” lab prior to performing this lab you will have the necessary projects in your workspace and the
EmployeeService_SOAP Integration Service will be deployed on the default Integration Service on the
TESTNODE Integration Node. If you did not perform the “Implementing a service interface” lab prior to

IBM Software
this lab then follow the instructions in the following sections to import the necessary projects to your
workspace and deploy the necessary artifacts to the default Integration Server.
7.1 IIB REST API configuration

IIB support for REST APIs requires some special configuration of the IIB integration node and server.
This section of the lab will cover the required IIB configurations that were performed on the TESTNODE
Integration Node and the default Integration Server.
Support for REST requires the use of the embedded HTTP listeners, rather than the node-wide listener.
Additionally, the IIB node has to be configured for Cross-Origin Resource Sharing (CORS). For details on
this, please read: http://www.w3.org/TR/cors/.
To configure these items, the mqsichangeproperties command is used.
HTTP embedded listeners are enabled with the following command:
mqsichangeproperties RESTNODE -e default -o ExecutionGroup -n

httpNodesUseEmbeddedListener -v true
Cross-Origin Resource Scripting for REST is required when testing with the SwaggerUI test tool. See
http://en.wikipedia.org/wiki/Cross-origin_resource_sharing for further information. The following
command enables CORS for the default Integration Server on TESTNODE:

corsEnabled -v true
For lab execution consistency the default Integration Sever has been configured to explicitly use port
7800 for its embedded listener. The following command explicitly sets the embedded listener’s port
number:

explicitlySetPortNumber -v 7800
7.2 REST API lab workspace

If you completed the “Implementing a service interface” lab as part of the PoT then you can continue the
REST API Lab using that workspace. It is assumed this workspace contains the
EmployeeServiceSOAP_Lib, EmployeeServiceSOAPMaps_Lib and EmployeeService_SOAP projects
and that they are deployed to the default Integration Server on TESTNODE Integration Node.
If you completed the “Implementing a service interface” lab, skip to Step 2.
__1. Open the IIB Toolkit, if not already open.
Lab 7 - Creating a REST API service Page 287

IBM Software
To start a new workspace browse to C:\student10\workspaces\RESTApi and click OK:
Close the Welcome view:
Since you have not completed the “Implementing a service interface” lab as part of the PoT then
you must import the “Implementing a service interface” projects into your workspace along with
the REST API projects. You must deploy the “Implementing a service interface” libraries to the
default Integration Server on the TESTNODE Integration Node.
__2. Right-click in the Application Development view and select Import.

IBM Software
__3. Expand IBM Integration, select Project Interchange and click Next.
__4. Click Browse:

IBM Software
__5. Select the following Project Interchange file and click Open:
C:\student10\REST_service\resource\RESTApi_Start_PI.zip
__6. If you completed the “Implementing a service interface” lab as part of the PoT then select the
following projects and click Finish:
 BAR files
 EmployeeServiceJSONMaps_Lib
 JSONSchemas_Lib

IBM Software
__7. If you did not complete the “Implementing a service interface” lab as part of the PoT select the
following projects and click Finish:
 BAR files
 EmployeeServiceSOAP_Lib
 EmployeeServiceSOAPMaps_Lib
 EmployeeService_SOAP
 JSONSchemas_Lib
 SAMPE_DDPrj

IBM Software
If prompted, click OK to confirm the overwrite of BAR files.
7.3 REST API lab deployment

The REST API lab requires that the EmployeeService SOAP web service is deployed as well as REST
API lab libraries. If you completed the “Implementing a service interface” lab as a part of the PoT then
you should have the following libraries and service interfaces deployed to the default Integration Server
on the TESTNODE Integration Node:
● EmployeeService_SOAP
__8. If you did not complete the “Implementing a service interface” lab as a part of the PoT then in the
Application Development view expand Independent Resources > BAR files > BARs and select
EmployeeServiceSOAP.bar. Drag and drop the EmployeeServiceSOAP.bar BAR file to the
default Integration Server on the TESTNODE Integration Node:

IBM Software
__9. You should see the following libraries and service interfaces deployed to the default Integration
Server:
__10. In the Application Development view, expand Independent Resources > BAR files > BARs
and select EmployeeServiceREST.bar. Drag and drop the EmployeeServiceREST.bar BAR
file to the default Integration Server on the TESTNODE Integration Node:

IBM Software
__11. You should see the following libraries and service interfaces deployed on the default Integration
Server:
 JSONSchemas_Lib

IBM Software
7.4 Explore the EmployeeServiceV1 JSON document

In this section the EmployeeServiceV1.json document will be explored. The EmployeeServiceV1.json
document defines the REST API that will be implemented in this lab. Although this lab will not cover the
creation of the EmployeeServiceV1.json file, it is beneficial to understand the contents and structure of
the document.
You will first use the Notepad++ editor to view the raw JSON file and then you will use the Swagger
editor to view the REST API defined in the EmployeeServiceV1.json file in a human-readable mark up
and explore some of its powerful editing capabilities. You will also explore the definition of an API
operation and the message models it utilizes.
7.4.1 Using Notepad++
__12. Use Windows Explorer to locate

C:\student10\Rest_service\resources\EmployeeServiceV1.json
__13. Right-click EmployeeServiceV1.json and select Edit with Notepad++:
__14. At the beginning of the document you will see the “title” (Employee Service) of the REST API and
the “basePath” (/EmployeeService/v1). All operations defined in this REST API will start with this
base path.
The API operations are defined under “paths”. Observe the “/departments” resource. The URL
for this operation is “/EmployeeService/v1/departments”, and the GET HTTP method is
supported. The “description” states that this operation returns a list of all departments.

IBM Software
Observe that this operation does not accept any parameters or input.
Under “responses”, observe that a Departments object is returned for HTTP 200 return codes.
__15. Scroll to line 594 in the file to find the Departments schema:
Observe that the schemas are contained under “definitions”, and that Departments is a JSON
array of Department items. Also observe that a Department contains four elements
(departmentNumber, admrdept, name and location) and all elements other than admrdept are
required.

IBM Software
Close Notepad++.
7.5 Using the Swagger editor

The goal of Swagger is to define a standard, language-agnostic interface to REST APIs which allows
both humans and computers to discover and understand the capabilities of the service without access to
source code or documentation. When properly defined via Swagger, a consumer can understand and
interact with the remote service with a minimal amount of implementation logic.
Swagger is more than just a way to describe REST APIs; it is also a powerful set of tools including an
editor (Swagger editor) and UI (swagger-ui). The Swagger editor will be explored in this section of the
lab. Swagger-ui will be explored during the test portion of this lab.
__16. Open an IIB command console using the shortcut located on the desktop:

IBM Software
__17. Change directories to C:\tools\swagger-editor
__18. Execute the following command from the C:\tools\swagger-editor directory:
npm start
Respond n to the usage statistics prompt:
The Swagger editor will take a few minutes to build. You can observe the progress in the
command window:

IBM Software
__19. When complete the Swagger editor will open in Firefox with an introductory window. Close the
window.

IBM Software
__20. The default document template is displayed.
__21. You will now open the EmployeeServiceV1.json document. Click the File menu item and select
Import File:

IBM Software
__22. Click Browse:
__23. Browse to C:\student10\REST_service\resources, select EmployeeServiceV1.json and click

Open:

IBM Software
__24. Click Import:
__25. Move the mouse pointer by the Paths field and “List all paths” will be displayed. Click List all
paths to collapse all operations and display the defined paths:
Observe that the operations are grouped by tags – “employees” and “departments” – paths
associated with a tag are displayed by clicking the tag. Clicking a path in the right pane will
expand the YAML markup in the editor. Clicking the arrow to the right of a path will jump to the
specific YAML markup in the editor.

IBM Software
__26. Explore the /department path. Click the /department path in the right pane:
Observe that the associated YAML code is expanded in the editor in the left pane.
Observe the getDepartment operation is a combination of the path

“/EmployeeService/v1/department” and the GET HTTP method.
The operation accepts one required input parameter – “departmentNumber” -- that is a “query”
parameter. This parameter is appended to the operation URL:
The operation returns JSON content in the form of a Department object.

IBM Software
__27. Click the /department path to collapse the content and then click the /employees/predictSalary
path to expand it:
Observe the associated YAML code is expanded in the editor.
Observe the operation is a combination of the path

“/EmployeeService/v1/employees/predictSalary” and the GET HTTP method.
The operation accepts one required parameter via an HTTP header – Educationlevel:
The operation returns JSON content in the form of a PreditedSalary object.

IBM Software
__28. Click the /employees/predictSalary path to collapse its content. Hover the mouse pointer by
the MODELS field and then click List all models:
__29. Observe all of the JSON objects that are defined for the REST API.

IBM Software
__30. Click the Departments model and observe the associated YAML code is expanded:
The following models are defined:

 Department/Departments
 Employee/Employees
 Manager
 PredictedSalary
Observe the definition of these objects and arrays in the document. Later in the lab you will
utilize XML Schemas and the Graphical Data Mapper to map these message models.

IBM Software
__31. Editing the YAML code with the editor is beyond the scope of this introductory IIB lab. There are
numerous templates and examples to illustrate how to create a Swagger document.
Note that the Swagger editor supports content assist, like the Integration Toolkit, which is a
powerful ease-of-use feature for creating Swagger documents.
Place the pointer at the end of “definitions:” in the document, then enter CTRL+SPACE.
Observe the selection of completions that apply to the current context:
The document can be modified and then saved as JSON.
__32. Close the Swagger Editor tab in Firefox.
__33. Terminate the Swagger editor.
Enter CTRL+C in the IIB command console from which the Swagger editor was started.
Enter Y when prompted “Terminate batch job (Y/N)?”

IBM Software
7.6 Create the REST API service

In this section you will create a new REST API service. This scenario will be based on the
EmployeeServiceV1.json Swagger document that was explored in the previous lab section.
The new IIB v10 REST API wizard will be used to implement the EmployeeService REST API. You will
also use the new REST API project which contains and organizes the API assets in a context that makes
implementation easy and structured while applying IIB design and development best practices.
Although a REST API service could be built in previous IIB versions, many artifacts had to be built
manually. Using the REST API wizard and project eliminates a large number of development tasks and
allows the developer to focus on implementing the service interface.
In this lab you will implement five of the operations defined in the EmployeeServiceV1.json Swagger
document. These operations will wrap operations that are implemented by the EmployeeService SOAP
web service. If you performed the “Implementing a service interface” lab you are familiar with this web
service.
Each operation requires two maps – SOAP Request, SOAP Response – that have been pre-built to allow
the lab to focus on the REST API development process. You will explore a few of these maps to observe
how REST input parameters, JSON objects and arrays are mapped.
The REST API wizard does not generate schemas for models defined in the Swagger document, but as
an alternative, XML schemas can be defined to model JSON objects and arrays. The models in the
EmployeeServiceV1.json Swagger document are defined by the schemas in the JSONSchemas_Lib
Library. This allows powerful GUI mapping for the REST API implementation.
You will implement the following operations defined in the EmployeeServiceV1.json Swagger document:
● getDepartment (query parameter, returns JSON object)
● getDepartmentEmployees (path parameter, returns JSON array)
● getEmployee (path parameter, returns JSON object)
● getEmployeeDepartment (path parameter, returns JSON object)
● predictSalary (header parameter, returns JSON object)

IBM Software
__34. In the Application Development view, select New > Start By Creating a REST API.
__35. Enter “EmployeeService_REST” for the name and click Next.
__36. Select Select from file system and click Browse.

IBM Software
__37. Select C:\student10\REST_service\resources\EmployeeServiceV1.json and click Open:
__38. Click Next to see a list of the operations that are defined in the Swagger document:

IBM Software
__39. Observe the operations that are defined. The highlighted operations will be implemented in this
lab. Click Finish:
__40. Observe the REST API Project is created and the REST API Description is open.
Note the base URL for the REST API: http://hostname:portnumber/EmployeeService/v1.
Note the list of operations that are defined for the REST API and the Error Handling handlers
that have been created. You will implement the Catch error handler during this lab.

IBM Software
__41. Right-click EmployeeService_REST and select Mange Library References:
__42. Select the following libraries and click OK:

 JSONSchemas_Lib

IBM Software
__43. You will now implement the getDepartment operation. Expand the /department path under
Operations. Click Implement the operation for the getDepartment operation:
__44. The getDepartment sub-flow is opened in the Message Flow Editor:
__45. The getDepartment REST operation will access the EmployeeService SOAP web service for the
implementation. To make a SOAP request to the EmployeeService web service, expand
EmployeeServiceSOAP_Lib > WSDL Definitions >
http://www.example.org/EmployeeServiceV1, select EmployeeServiceV1.wsdl and drag and
drop it in the getDepartment sub-flow between the Input and Output nodes:

IBM Software
__46. Select Invoke web service from message flow, check getDepartment(getDepartment) and
click Finish:
__47. Double-click the getDepartment_EmployeeServiceV1 sub-flow node to open the

getDepartment_EmployeeServiceV1_getDepartment sub-flow:

IBM Software
__48. The sub-flow contains a SOAPExtract node to remove the SOAP Envelope from the web service
response. The map for the REST API response accepts a SOAP Envelope so it can handle
valid responses and SOAP Faults, so the SOAPExtract node must be removed from the sub-
flow. Right-click the Extract node and select Delete.
__49. Connect the Out terminal of the Request node to the In terminal of the
getDepartmentResponse node:
__50. Enter CTRL+S to save the getDepartment_EmployeeServiceV1_getDepartment sub-flow.

Click the X on the getDepartment_EmployeeServiceV1_getDepartment tab to close the sub-flow:

IBM Software
__51. You will now add a mapping node to map the REST request to the SOAP request. Expand the
Transformation node category, select the Mapping node and left-click in the getDepartment
sub-flow between the Input and getDepartment_EmployeeServiceV1 nodes. Rename the node
to “getDepartmentRequest”:
__52. Highlight the getDepartmentRequest node and select the Basic properties page. Click the
Browse button for the Mapping routine* property:

IBM Software
__53. Select the {default}:getDepartmentRequestMap map and click OK:
__54. Double-click the getDepartmentRequest node to open the getDepartmentRequestMap map.
The getDepartment operation accepts a query input parameter named “departementNumber”. In

previous versions of IIB(WMB) “departmentNumber” was available under the QueryString
property, now in V10 the REST API application makes REST API parameters available in a more
well-defined location under “LocalEnvironment/REST/Input/Pararmeters/any”. The “any”
element can be Cast to any type or “user-defined” elements can be added. The other REST
input parameter types of “path” and “header” will also made available at
“LocalEnvironment/REST/Input/Pararmeters/any”.
Click the Move transform; this will expand the LocalEnvironment tree and show the REST API
parameter mapping. Here you see that the “departmentNumber” “User Defined Type” was
added to “LocalEnvironment/REST/Input/Pararmeters/any”. Note, the name added here must
match the parameter name in the Swagger document exactly:

IBM Software
__55. You will now add a mapping node to map the web service SOAP response to the REST
response. Expand the Transform node category, select the Mapping node and left-click in the
sub-flow between the getDepartment_EmployeeServiceV1 and Output nodes. Rename the node
“getDepartmentResponse”.

IBM Software
__56. Highlight the getDepartmentResponse node, select the Basic properties tab and click the
Browse button for the Mapping routine* properties:
__57. Select the {default}:getDepartmentRepsonseMap map and click OK:
__58. Wire the Out terminal of the Input node to the In terminal of the getDepartmenRequest node.
Wire the Out terminal of the getDepartmentRequest node to the In terminal of the
getDepartment_EmployeeServiceV1 node.
Wire the getDepartmentResponse terminal of the getDepartment_EmployeeServiceV1 node to

the In terminal of the getDepartmentResponse node.

IBM Software
Wire the fault terminal of the getDepartment_EmployeeServiceV1 node to the In terminal of

the getDepartmentResponse node.
Wire the Out terminal of the getDepartmentResponse node to the In terminal of the Output
node.
__59. Enter CTRL+S to save the getDepartment sub-flow. Click the X on the getDepartment.sub-flow
tab to close the sub-flow:
__60. Select the EmployeeService_REST tab. Under Operations expand the

/departments/{departmentNumber}/employees path. Click Implement the operation for the
getDepartmentEmployees operation:

IBM Software
__61. The getDepartmentEmployees sub-flow is opened in the Message Flow Editor:
__62. The getDepartmentEmployees REST operation will access the EmployeeService SOAP web
service for the implementation. To make a SOAP request to the EmployeeService web service,
expand EmployeeServiceSOAP_Lib > WSDL Definitions >
drop it in the getDepartmentEmployees sub-flow between the Input and Output nodes:

IBM Software
__63. Select Invoke web service from message flow, select

getDepartmentEmployees(getDepartmentEmployees) and click Finish:
__64. Double-click the getDepartmentEmployees_EmployeeServiceV1 sub-flow node to open the

getDepartmentEmployees_EmployeeServiceV1_getDepartmentEmployees sub-flow:

IBM Software
getDepartmentEmployeesRepsonse node:
__67. Enter CTRL+S to save the

getDepartmentEmployees_EmployeeServiceV1_getDepartmentEmployees sub-flow. Click
the X on the getDepartmentEmployees_EmployeeServiceV1_getDepartmentEmployees tab to
close the sub-flow:

IBM Software
Transformation node category, select the Mapping node and left-click in the
getDepartmentEmployees sub-flow between the Input and
getDepartmentEmployees_EmployeeServiceV1 nodes. Rename the node to
“getDepartmentEmployeesRequest”:
__69. Highlight the getDepartmentEmployeesRequest node and select the Basic properties page.
Click the Browse button for the Mapping routine* property:

IBM Software
__70. Select the {default}:getDepartmentEmployeesRequestMap map and click OK:
sub-flow between the getDepartmentEmployees_EmployeeServiceV1 and Output nodes.
Rename the node “getDepartmentEmployeesResponse”.

IBM Software
__72. Highlight the getDepartmentEmployeesResponse node, select the Basic properties tab and
click the Browse button for the Mapping routine* property:
__73. Select the {default}:getDepartmentEmployeesRepsonseMap map and click OK:
__74. Double-click the getDepartmentEmployeesResponse node to open the

getDepartmentEmployeesResponseMap map.
Observe the map source is a SOAP Domain message where the Body of the SOAP Envelope
has been cast to a “getDepartmentEmployeesResponse” type and a “fault” type. This allows the
operation to easily handle valid and fault responses from the web service. If a
getDepartmentEmployeesResponse message is received an “Employees” JSON array is
returned. If a fault message is received an “error” object is returned.

IBM Software
Observe that the map output uses the JSON parser. The “EmployeeServiceV1” Swagger
document defines that the “getDepartmentEmployees” operation returns an “Employees” JSON
array. While the “Employees” model is defined in the Swagger document the current tooling
does not generate JSON schemas that can be used by the Graphical Data Mapper. An
alternative is to use XML schemas to implement the JSON schemas that are defined in the
Swagger document. The schemas in the JSONSchemas_Lib library implement all of the models
in the Swagger document and are used in all of the JSON mappings.
Note that the “any” element under JSON/Data has been cast to an “Employees” type and a User
Defined type of error has been added. This allows the operation to return either a JSON array of
“Employees” or an “error” object, and offers easy GUI mapping of JSON objects and arrays:
__75. Wire the Out terminal of the Input node to the In terminal of the
getDepartmenEmployeesRequest node.

IBM Software
Wire the Out terminal of the getDepartmentEmployeesRequest node to the In terminal of the
getDepartmentEmployees_EmployeeServiceV1 node.
Wire the getDepartmentEmployeesResponse terminal of the

getDepartmentEmployees_EmployeeServiceV1 node to the In terminal of the
getDepartmentEmployeesResponse node.
Wire the fault terminal of the getDepartmentEmployees_EmployeeServiceV1 node to the In

terminal of the getDepartmentEmployeesResponse node.
Wire the Out terminal of the getDepartmentEmployeesResponse node to the In terminal of the
Output node.
__76. Enter CTRL+S to save the getDepartmentEmployees sub-flow. Click the X on the
getDepartmentEmployees.sub-flow tab to close the sub-flow:

IBM Software

/employees/{employeeNumber} path. Click Implement the operation for the getEmployee
operation:
__78. The getEmployee sub-flow is opened in the Message Flow Editor:
__79. The getEmployee REST operation will access the EmployeeService SOAP web service for the
drop it in the getEmployee sub-flow between the Input and Output nodes:

IBM Software
__80. Select Invoke web service from message flow, check getEmployee(getEmployee) and click
Finish:
__81. Double-click the getEmployee_EmployeeServiceV1 sub-flow node to open the

getEmployee_EmployeeServiceV1_getEmployee sub-flow:

IBM Software
__83. Connect the Out terminal of the Request node to the In terminal of the getEmployeeRepsonse
node:
__84. Enter CTRL+S to save the getEmployee_EmployeeServiceV1_getEmployee sub-flow. Click

the X on the getEmployee_EmployeeServiceV1_getEmployee tab to close the sub-flow:

IBM Software
Transformation node category, select the Mapping node and left-click in the getEmployee
sub-flow between the Input and getEmployee_EmployeeServiceV1 nodes. Rename the node to
“getEmployeeRequest”:
__86. Highlight the getEmployeeRequest node and select the Basic properties page. Click the

IBM Software
__87. Select the {default}:getEmployeeRequest map and click OK:
sub-flow between the getEmployee_EmployeeServiceV1 and Output nodes. Rename the node
“getEmployeeResponse”.

IBM Software
__89. Highlight the getEmployeeResponse node, select the Basic properties tab and click the
Browse button for the Mapping routine* properties:
__90. Select the {default}:getEmployeeRepsonseMap map and click OK:
__91. Wire the Out terminal of the Input node to the In terminal of the getEmployeeRequest node.
Wire the Out terminal of the getEmployeeRequest node to the In terminal of the
getEmployee_EmployeeServiceV1 node.
Wire the getEmployeeResponse terminal of the getEmployee_EmployeeServiceV1 node to the

In terminal of the getEmployeeResponse node.
Wire the fault terminal of the getEmployee_EmployeeServiceV1 node to the In terminal of the
getEmployeeResponse node.
Wire the Out terminal of the getEmployeeResponse node to the In terminal of the Output node.

IBM Software
__92. Enter CTRL+S to save the getEmployee sub-flow. Click the X on the getEmployee.sub-flow tab
to close the sub-flow:

/employees/{employeeNumber}/department path. Click Implement the operation for the
getEmployeeDepartment operation:

IBM Software
__94. The getEmployeeDepartment sub-flow is opened in the Message Flow Editor:
__95. The getEmployeeDepartment REST operation will access the EmployeeService SOAP web
service for the implementation. To make a SOAP request to the EmployeeService web service,
expand EmployeeServiceSOAP_Lib > WSDL Definitions >
drop it in the getEmployeeDepartment sub-flow between the Input and Output nodes:

IBM Software
__96. Select Invoke web service from message flow, check

getEmployeeDepartment(getEmployeeDepartment) and click Finish:
__97. Double-click the getEmployeeDepartment_EmployeeServiceV1 sub-flow node to open the

getEmployeeDepartment_EmployeeServiceV1_getEmployeeDepartment sub-flow:

IBM Software
getEmployeeDepartmentRepsonse node:
__100. Enter CTRL+S to save the

getEmployeeDepartment_EmployeeServiceV1_getEmployeeDepartment sub-flow. Click the
X on the getEmployeeDepartment_EmployeeServiceV1_getEmployeeDepartment tab to close
the sub-flow:
Transformation node category, select the Mapping node and left-click in the
getEmployeeDepartment sub-flow between the Input and
getEmployeeDepartment_EmployeeServiceV1 nodes. Rename the node to
“getEmployeeDepartmentRequest”:

IBM Software
__102. Highlight the getEmployeeDepartmentRequest node and select the Basic properties page.
Click the Browse button for the Mapping routine* property:
__103. Select the {default}:getEmployeeDepartmentRequest map and click OK:

IBM Software
sub-flow between the getEmployeeDepartment_EmployeeServiceV1 and Output nodes.
Rename the node “getEmployeeDepartmentResponse”.
__105. Highlight the getEmployeeDepartmentResponse node, select the Basic properties tab and
click the Browse button for the Mapping routine* property:

IBM Software
__106. Select the {default}:getEmployeeDepartmentRepsonseMap map and click OK:
__107. Wire the Out terminal of the Input node to the In terminal of the
getEmployeeDepartmenRequest node.
Wire the Out terminal of the getEmployeeDepartmentRequest node to the In terminal of the
getEmployeeDepartment_EmployeeServiceV1 node.
Wire the getEmployeeDepartmentResponse terminal of the

getEmployeeDepartment_EmployeeServiceV1 node to the In terminal of the
getEmployeeDepartmentResponse node.
Wire the fault terminal of the getEmployeeDepartment_EmployeeServiceV1 node to the In

terminal of the getEmployeeDepartmentResponse node.
Wire the Out terminal of the getEmployeeDepartmentResponse node to the In terminal of the
Output node.

IBM Software
__108. Enter CTRL+S to save the getEmployeeDepartment sub-flow. Click the X on the
getEmployeeDepartment.sub-flow tab to close the sub-flow:

/employees/predictSalary path. Click Implement the operation for the predictSalary
operation:
__110. The predictSalary sub-flow is opened in the Message Flow Editor:
__111. The predictSalary REST operation will access the EmployeeService SOAP web service for the
drop it in the predictSalary sub-flow between the Input and Output nodes:

IBM Software
__112. Select Invoke web service from message flow, check predictSalary(predictSalary) and click
Finish:

IBM Software
__113. Double-click the predictSalary_EmployeeServiceV1 sub-flow node to open the

predictSalary_EmployeeServiceV1_getDepartment sub-flow:
__115. Connect the Out terminal of the Request node to the In terminal of the predictSalaryResponse
node:

IBM Software
__116. Enter CTRL+S to save the predict_EmployeeServiceV1_getDepartment sub-flow. Click the X

on the predictSalary_EmployeeServiceV1_predictSalary tab to close the sub-flow:
Transformation node category, select the Mapping node and left-click in the predictSalary
sub-flow between the Input and predictSalary_EmployeeServiceV1 nodes. Rename the node to
“predictSalaryRequest”:
__118. Highlight the predictSalaryRequest node and select the Basic properties page. Click the

IBM Software
__119. Select the {default}:predictSalaryRequestMap map and click OK:
__120. Double-click the predictSalaryRequest node to open the predictSalaryRequestMap map.
The predictSalary operation accepts a header input parameter named “Educationlevel”. This
parameter is passed via a HTTP header in the HTTP request. In previous versions of IIB(WMB)
HTTP headers were made available under the HTTP Input Header. Now in IIB V10 all REST
input parameter types are made available in a consistent location of
LocalEnvironment/REST/Input/Parameters/any.
Click the xs:int transform to expand the LocalEnvironment tree and expose the REST
properties:
Here you see that the User Defined type of Educationlevel has been added:

IBM Software
Close the predictSalaryRequestMap map.
sub-flow between the predictSalary_EmployeeServiceV1 and Output nodes. Rename the node
“predictSalaryResponse”.
__122. Highlight the predictSalaryResponse node, select the Basic properties tab and click the

IBM Software
__123. Select the {default}:predictSalaryRepsonseMap map and click OK:
__124. Wire the Out terminal of the Input node to the In terminal of the predictSalaryRequest node.
Wire the Out terminal of the predictSalaryRequest node to the In terminal of the
predictSalary_EmployeeServiceV1 node.
Wire the predictSalaryResponse terminal of the predictSalary_EmployeeServiceV1 node to

the In terminal of the predictSalaryResponse node.
Wire the fault terminal of the predictSalary_EmployeeServiceV1 node to the In terminal of the
predictSalaryResponse node.

IBM Software
Wire the Out terminal of the predictSalaryResponse node to the In terminal of the Output
node.
__125. Enter CTRL+S to save the predictSalary sub-flow. Click the X on the predictSalary.sub-flow tab
to close the sub-flow:
__126. Select the EmployeeService_REST tab. Under Error Handling click Implement the Catch
handler:

IBM Software
__127. The EmployeeService_RESTInputCatchHandler sub-flow opens in the Message Flow Editor:
__128. You will now add a mapping node to create a simple JSON error message for exceptions that
occur during message flow processing. Expand the Transform node category and select the
Mapping node, then left click in the sub-flow between the Input and Output nodes. Rename the
Mapping node to “catchHandler”:

IBM Software
__129. Highlight the catchHandler node and on the Basic properties page click the Browse button for
the Mapping routine* property:

IBM Software
__130. Select the {default}:catchHandlerMap map and click OK:
__131. Wire the Out terminal of the Input node to the In terminal of the catchHandler node.
Wire the Out terminal of the catchHandler node to the In terminal of the Output node.
__132. Enter CTRL+S to save the EmployeeService_RESTInputCatchHandler sub-flow. Click the X

on the EmployeeService_RESTInputCatchHandler.sub-flow tab to close the sub-flow:

IBM Software
__133. Click the X in the EmployeeService_REST tab to close the REST API:
__134. You can view the EmployeeService_REST API implementation message flow by expanding
EmployeeService_REST > Resources > Flows > gen and right-clicking
EmployeeService_REST.msgflow then selecting Open > With Message Flow Editor:

IBM Software
__135. Observe there is a Label Node for each operation and Catch Handler that was implemented that
is wired to the associated sub-flow:
Note the warning that the flow is auto generated and should not be edited.
7.7 Deploy the EmployeeService_REST REST API

You will now deploy the EmployeeService_REST REST API to the default Integration Server on the
TESTNODE Integration Node.

IBM Software
__136. In the Application Development view, select the EmployeeService_REST REST API project and
drag and drop it onto the default Integration Server in the Integration Nodes view:
__137. Observe that the EmployeeService_REST REST API has been successfully deployed:

IBM Software
7.8 Testing the EmployeeService_REST REST API

This section will show you how to use the SwaggerUI tool to send a REST request into the REST API
service that you have just created.
__138. Open the IIB Web UI by right-clicking TESTNODE in the Integration Nodes view and selecting
Start Web User Interface:
__139. When the Web User Interface opens expand TESTNODE > Servers > default > REST APIs >
EmployeeService_REST > API then right-click Remote URL For The REST API Definitions
and select Copy Link Location:

IBM Software
__140. In Firefox, open a new tab, and open the SwaggerUI tool (using the bookmark in the REST
folder). By default, this will open the Petstore Swagger document.
__141. In the entry field, paste the contents of the clipboard and click Explore to view the
EmployeeServiceV1 REST API hosted on IIB:

IBM Software
__142. On the departments tag click List Operations to list all of the operations that are defined for the
tag:
__143. Click GET /departments to expand the getDepartment operation. Enter “C01” for the
departmentNumber and click Try It Out:
Observe the Request URL and the response body for the HTTP 200 return code:

IBM Software
__144. Enter “C09” for the departmentNumber and click Try It Out. Observe the Request URL and the
error response for an HTTP return code of 500:
Note: An empty result set was returned for the database query performed by the
EmployeeService web service.

IBM Software
error response for an HTTP return code of 500:
Note: The database query performed by the EmployeeService web service failed because the
departmentNumber exceeds the length of the DeptNumber column in the Department table.
__146. Click GET /departments/{departmentNumber}/employees to expand the

getDepartmentEmployees operation. Enter “C01” for the departmentNumber and click Try It
Out:

IBM Software
__147. Observe the Request URL and the Response Message for a HTTP return code of 200:
Note: A JSON array of Employee objects has been returned.
error response message that was returned for an HTTP return code of 500:
EmployeeService web service.

IBM Software
__149. Enter “C099” for the “departmentNumber” and click “Try It Out”. Observe the Request URL and
the error response message that was returned for an HTTP return code of 500:
departmentNumber exceeds the length of the DepartmentNumber column in the Department
table.
__150. Click Show/Hide for the department tag and click List Operations for the employees tag:

IBM Software
__151. Click GET /employees/{employeeNumber} to expand the getEmployee operation. Enter

“000060” for the employeeNumber and click Try It Out:

IBM Software
__153. Enter “000066” for the employeeNumber and click Try It Out. Observe the Request URL and
EmployeeService web service. IIB has automatically handled the HTTP 500 response code.
employeeNumber exceeds the length of the EmployeeNumber column in the Employee table.
IIB has automatically handled the HTTP 500 response code.

IBM Software
__155. Click GET /emplyees/{employeeNumber}/department to expand the

getEmployeeDepartment operation. Enter “000060” for the employeeNumber and click Try It
Out:

IBM Software
EmployeeService web service. IIB has automatically handled the HTTP 500 response code.
employeeNumber exceeds the length of the EmployeeNumber column in the Employee table.
IIB has automatically handled the HTTP 500 response code.

IBM Software
__159. You will use the NetTool utility to test the predictSalary operation. This operation accepts an
input header parameter named Educationlevel and NetTool allows you to easily create HTTP
headers.
Using Windows Explorer, navigate to C:\tools\Nettool 4.7.2” and execute “start-nettool.bat:
__160. When NetTool starts select the HTTP Client tab.
Enter http://localhost:7800/EmployeeService/v1/employees/predictSalary for the URL.
Select the GET HTTP method.
Click Add Header to add the Educationlevel header. Assign of value of “16” to the
Educationlevel header.
Click Send to send the request.

IBM Software
__161. Observe the response:
__162. Click Clone to create a new request. Change the value of the Educationlevel header to “8” and
click Send:

IBM Software
__163. Observe the response:
Note: The EmployeeService_REST message flow has automatically handled the HTTP 500
response code.
__164. You have completed the REST API lab.
7.9 Summary
During the “Creating a REST API” lab you explored the contents of a Swagger document that defined the
EmployeeServiceV1 REST API using Notepad++ and the Swagger editor.
The new Create REST API wizard was used to import the EmployeeServiceV1 Swagger document and
create a REST API application. You observed the structure, organization and contents of the new REST
API application and how they offer IIB design and implementation best practices.
You used the REST API application tooling to quickly implement five operations and a Catch handler,
and then deployed the REST API application to a runtime Integration Server. The five operations
exchanged JSON Objects/Arrays and demonstrated all three input parameter types – path, query and
header.
● The Web UI was used to observe the REST API extensions that have been added to V10.
● The EmployeeServiceV1 REST API was tested using Swagger-UI and NetTool.
END OF LAB 7

IBM Software
Lab 8 Exception handling and the interactive Flow Debugger
8.1 Overview
Murphy’s law states that “Anything that can go wrong, will go wrong”.
All programs should be designed with that adage in mind, and include exception handling of some sort.
Integration solutions developed for IBM Integration Bus are no different—a well-designed message flow
will have some form of exception handling.
In this lab you will see an example of how exceptions can be thrown, caught, and handled directly in your
message flow. You will also be introduced to the interactive Flow Debugger and see how that can be
used in addition to the Flow Exerciser in diagnosing problems.
8.2 Lab setup

You will use the Lab 2 solution as the starting point for this lab.
If you completed Labs 1 and 2, and still have the IntroLab application and IntroLab_Lib library in your
workspace, you can proceed to section 8.3.
If you did not complete both Labs 1 and 2, or are now using a different workspace, you can import the
completed Lab 2 solution into your workspace using the following steps.
__1. In the whitespace of the Application Development view, right-click and select Import.

IBM Software
__2. In the Import wizard, expand the IBM Integration folder if necessary, and select Project
Interchange.
Click Next.
__3. Click the Browse button next to the From zip file: entry field.
Lab 8 - Exception handling and the interactive Flow Debugger Page 371
IBM Software
__4. In the Open dialog, navigate to C:\student10\LabSolutions.
Select Lab2_PI.zip and click Open.
__5. Ensure that all four project folders shown are checked.
Click Finish.

IBM Software
__6. In the Application Development view, you should now see the imported project folders (and
perhaps others as well).
8.3 Understanding exceptions in IBM Integration Bus

The IntroLab message flow had no exception handling of any kind included. In this lab you will extend
the IntroLab message flow to both throw user exceptions in certain situations, as well as be able to catch
and handle both User and Recoverable system exceptions, regardless of where in the flow these occur.
IBM Software
8.3.1 Key Idea: Catch Terminals and TryCatch nodes
Key Idea: Catch Terminals and TryCatch nodes.

Read the section below for additional information about
using Failure and Catch Terminals, TryCatch nodes, or
both to catch and handle exceptions in IBM Integration Bus.
With IBM Integration Bus there are two general approaches to handling errors in a message flow:
Failure checking
Most nodes have a Failure terminal. Wire this terminal to explicitly check for any errors that occur within
that node. Sometimes node failures are tolerable, or recoverable. If you do not want a node failure to
result in the flow as a whole aborting, you can wire the Failure terminal to nodes that can deal with (or
ignore) the failure.
Catching exceptions
If you do not wire a Failure terminal, a node failure is converted into an exception which is thrown from
the node. Any changes that were made to the inflight message before the exception was thrown are
reversed. Message flow nodes that represent the start of a transaction typically have a Catch terminal.
Use the Catch terminal to handle any exceptions that are thrown "downstream".
Note this important difference!
A message is propagated to a node’s Failure terminal

if an exception occurs inside that node. A message is
propagated to a node’s Catch terminal only if it has
first been propagated beyond the node (for example,
to the nodes connected to the Out terminal) and an
unhandled exception occurs downstream from the
node.
In both cases, an Exception List tree is created, which contains diagnostic information about the error
that has occurred. If you wire the node’s Failure terminal, or wire an upstream node’s Catch terminal, the
message assembly, including the Exception List, will be propagated down that path. Along that path in
the message flow you can include nodes to handle such exceptions as you see fit. Examples of what you
might do include logging exception data, saving the message or event being processed in a file or
undeliverable message queue, or generating an alert.
For complex message flows, a TryCatch node can be used to break the large message flow into multiple
"TryCatch blocks". This can enable more granular exception handling to be performed. The TryCatch
node itself does not process a message in any way; it merely represents a decision point in a message
flow. When the TryCatch node receives a message, it propagates it to the Try terminal (a "try subflow"). If
an exception occurs on that path, control will return to the TryCatch node, which will then propagate it to
the Catch terminal (a "catch subflow") that can then attempt to handle the exception.

IBM Software
See the IBM Integration Bus documentation for more detailed information on failure and exception
handling in message flows.
In this section you will see a simple example of how exception handling can be incorporated into a
message flow.
Note:
The following should not be viewed as an example of
robust exception handling! The example is very simple, and
intended merely to illustrate some of the options available
to catch and handle exceptions in IBM Integration Bus.
__7. In the Application Development view, expand the IntroLab application and Flows folder, and
double-click IntroMessageFlow.messageflow.
__8. Locate the Trace node that you left unwired at the end of Lab 2.
You will be repurposing this node to gather additional information when exceptions occur.
Click the Trace node and review its properties.
IBM Software
__9. Leave the Destination and File path the same.
In the Pattern box, add the following additional lines:
Enter the string ${LocalEnvironment} exactly as indicated – this tells the trace node to dump
out the entire contents of the LocalEnvironment tree.
Enter the string ${ExceptionList} exactly as indicated – this tells the trace node to dump out any
Exception data if present.
Note:
The pattern uses curly braces, not parentheses!
The pattern is case sensitive!
__10. The trace node properties should look like this when complete:

IBM Software
__11. On the Palette, open the HTTP drawer.
Select an HTTPReply node from the drawer.
Place it to the right of the trace node.
__12. Rename the node “Reply if Error”.
Press the Enter key to accept the changed name.
__13. Wire the Catch terminal (at the bottom) of the IntroLab_Listener input node to the in terminal of
the Trace node.
IBM Software
__14. Wire the Out terminal of the Trace node to the In terminal of the Reply if Error node.
__15. Click the node, then click one more time on the node name. It should then look like the following:
__16. Change the name of the node to “Trace Exceptions”.
The changes are nearly complete. But there is one more thing to take into account.

IBM Software
Remember that, in Lab 2, you ran one test with MX for customerCountry. When that test was
run, no failure was generated – the flow simply ended. As discussed in that lab, the reason was
that, in a Route node, a no-match condition is not considered a failure.
For purposes of this lab, you are going to consider a no-match condition to be a failure. So you
will now extend the flow further, to throw a User Exception when there is not a valid value for
customerCountry.
__17. On the Palette, find the Construction drawer and open it
Select a Throw node from the drawer.
Place it to the right and slightly above the CheckCountry node.
__18. Change the name of the node to “NoMatch”.
__19. Click the NoMatch (previously, “Throw”) node and look at its Properties.
On the Basic tab, change Message number to “9999”, and Message text to “Missing or invalid
value found in customerCountry element”.
IBM Software
__20. On the CheckCountry route node, click the group of output terminals.
__21. Select default from the list. Click OK.
__22. Connect the Default terminal of the CheckCountry node to the In terminal of the NoMatch throw
node.
Verify that the correct terminals are wired.

IBM Software
__23. The changes should be complete.
Your flow should look like this:
__24. Save the message flow.
You will now repeat some of the tests you ran in Lab 2.
You will first retest the US and Canada paths in the flow, to ensure they still work as expected.
You will then retest sending an unexpected customerCountry code, to see if the logic you added
handles that correctly.
Finally, you will send in a malformed XML document, to see how system exceptions are caught
and handled.
IBM Software
__26. If prompted to save the message flow, click OK.

IBM Software
__28. Click the Send message icon to configure a test message.
IBM Software
__29. Click Test message.
Change the name to “Test message (US)”.
__30. Recall that in Lab 2, you had changed customerCountry to “MX”. You may see that value there
now.
You want to retest the US path through the flow, so change customerCountry back to “US”.

IBM Software
IBM Software
__31. Click Apply to the change.
Click Send to send the message to the flow.

IBM Software
__33. The Flow Exerciser shows the path the US message took through the flow.
__34. Repeat these steps to test the Canada path in the message flow.
IBM Software
Click the Send message icon to configure a test message.
__35. Right-click Test message (US), and select Duplicate from the menu.

IBM Software
__36. Change the name of the new test message to “Test message (CA)”.
Change customerCountry to “CA”.
Click Apply to the change.
IBM Software

IBM Software
__38. The Flow Exerciser shows the path the CA message took through the flow.
IBM Software
__39. Repeat these steps again, this time creating an MX test message.
Click Send to configure another message.
__40. Right-click Test message (CA), and select Duplicate from the menu.

IBM Software
__41. Change the name of the new test message to “Test message (MX)”.
Change customerCountry to “MX”.
IBM Software

IBM Software
__43. The Flow Exerciser shows the path the MX message took through the flow.
This path is rather interesting.
Examine what happened here.
__44. Looking at these steps in order:
IBM Software
1.The input message was processed by the IntroLab_Listener node and passed to the
CheckCountry node.
2.The CheckCountry node determined that MX did not have a matching entry in its routing
table, and so passed the message via the default terminal to the NoMatch throw node.
3.The NoMatch throw node threw an exception.
4.The thrown exception was caught by the IntroLab_Listener node
5.The IntroLab_Listener node passed the input message, along with exception data, to the
Trace Exceptions node via the Catch terminal.
6.After logging the message along with exception data to a file, the Trace Exceptions node
passed control to the Reply if Error node, and the flow ended.
__45. Look at the message tree that was passed via the Catch terminal from the IntroLab_Listener
node to the Trace Exceptions node.

IBM Software
Do this by clicking the recorded message to view it.
__46. Focus on the Exception List structure in the tree (1).
The Exception List structure provides a great deal of detail about what led up to, and what
caused, an exception.
The items labeled (2) indicate that the CheckCountry node caught and rethrew an exception
generated from a downstream node.
IBM Software
The items labeled (3) indicate that the downstream node that threw the exception was the
NoMatch node, that the exception thrown was a User exception with an error number of 9999,
and that the cause was a Missing or invalid value found in customerCountry element.

IBM Software
__48. Call this recorded message “Test Unknown Country Code (MX)” and click OK.
The approach of having an exception handler for the entire flow means that exceptions thrown
for any reason, from any point in the flow, can be handled using a common exception handler.
The following steps will demonstrate this, by sending a malformed XML message into the flow,
and observing what happens.
IBM Software
__50. Click Send to configure another message.
__51. Right-click Test message (MX), and select Duplicate from the menu.

IBM Software
__52. Change the name of the new test message to “Test message (Malformed XML)”.
Change customerCountry to “&” (which is illegal in XML).
IBM Software
__53. The Flow Exerciser will run.
This time you get an error back from the flow.

IBM Software
Click the error message to see its contents.
__54. Review the highlighted text. Briefly, it explains that an exception occurred, and that the cause
was an XML parsing error at element “customerCountry”.
Click Close.
__55. The Flow Exerciser shows the path the malformed XML message took through the flow.
Notice here that the message never made it to the CheckCountry node.
IBM Software
The reason was that IIB tried to parse the XML message before passing it to the CheckCountry
node, but because it could not be successfully parsed, the message went straight to the Catch
terminal on the IntroLab_Listener node.
Why was the Failure terminal not used?

Because On-Demand parsing is in effect, no attempt was
made to parse the message inside the IntroLab_Listener
node. The first attempt to parse the message was after the
IntroLab_Listener node but before the CheckCountry node.
Had the error been detected inside the IntroLab_Listener
node, the Failure terminal would have been used.
__56. Look at the message tree that was passed via the Catch terminal from the IntroLab_Listener
node to the Trace Exceptions node.

IBM Software
Do this by clicking the recorded message to view it.
__57. First, focus on the message body.
The Flow Exerciser will display as much of the message tree as possible. You see here that the
message up to customerCountry is displayed, but customerCountry itself, and any elements
below it, are not displayed. The reason is that the XMLNSC parser was only able to successfully
parse the message up to that point, but no further, due to the malformed data (“&”) in the
message.
IBM Software
__58. Now collapse the Message section, and expand the Exception List section.

IBM Software
There are multiple RecoverableException sections, showing the XMLNSC parser attempting to
find a way to successfully parse the data.
__59. Scroll to the bottom of the Exception List structure – the original exception will be found there.
The exception type (“ParserException”) as well as the cause of the parser error and the element
involved (“customerCountry”), can be found here.
IBM Software

IBM Software
__61. Call this recorded message “Test Malformed XML” and click OK.
__63. Remember that the Trace Exceptions node was also logging the message tree to a file.
__64. Use the Windows Explorer to locate the file you configured the Trace Exceptions node to use.
IBM Software
__65. Recall that in Lab 2 you configured the Trace node to capture the “IIB-internal” view of the
message tree.
By this time there will be quite a bit of data in the trace file – you will need to scroll to near the
bottom of the file to find the most recently logged data.
Scroll down to locate the most recent Message data.
Note the correspondence with what you saw in the Recorded Message from the Flow Exerciser
– the XMLNSC parser was able to parse to the customerCountry element, but failed at that point.
Note that the “IIB-internal” view of the message tree contains more detail about the message
tree than does the XML-rendered view – for example, showing the different data types (such as
INTEGER and CHARACTER).

IBM Software
__66. Now scroll down further to find the Exception List structure.
Scroll all the way to the bottom of that section, so you can see the original exception.
IBM Software
Again, note the correspondence with what you saw in the Recorded Message from the Flow
Exerciser—the exception type is “ParserException” and the element involved is
“customerCountry”.
The detailed exception information provided by IBM Integration Bus makes it possible for flow-
level exception handlers to be written that can log detailed information about failures, as well as
to take action in some if not many cases to recover from those exceptions programmatically.
Think also about what you’ve configured in terms of testing assets by using the Flow Exerciser
as you have in this lab, as well as the first two labs.

IBM Software
__68. Return to the Flow Exerciser, and click Send to view the configured test messages.
__69. You configured test messages for four scenarios: two “happy paths” (for US and CA) and two
error paths.
IBM Software
In addition, you saved four Recorded Messages that captured the results of those tests.
Click Close to close the window.
__70. In the Application Development pane, the IntroMessageFlow_inputMessage.xml file and the
IntroMessageFlow_recordedMessage.xml file can be exported and used by other testers, or by
external test tools, to perform regressing testing on this flow in the future.

IBM Software
__72. Click Yes to dismiss the pop-up.
IBM Software
8.4 Diagnosing failures

The Flow Exerciser is a very useful tool for testing a new or modified message flow. But there are times
when the Flow Exerciser may not provide sufficient information for diagnosing a problem. In this section
you will see an example of such a situation.
__73. You may recall from Lab1 that a change you made resulted in a warning appearing on the
IntroLab_Listener node.
__74. Hover the mouse pointer over the node to see the warning.
__75. In Lab1 you were told to ignore this warning. You are now going to address it.
Click the IntroLab_Listener node.

IBM Software
__76. In the Properties sheet for the node, under Parser Options, change Parse timing from On
Demand to Immediate.
__78. With Parse Timing set to Immediate, the warning no longer appears.
IBM Software
__79. You will now repeat the test using the malformed XML document.
Start the Flow Exerciser.

IBM Software
IBM Software
__82. Click the Send message icon to configure a test message.

IBM Software
__83. Select Test message (Malformed XML)
Verify that the “&” is in the customerCountry field.
Click Send.
__84. Because the message was malformed, you expected this error.
Click the error and examine the returned error explanation.
You will notice some differences between this exception data and the data that was returned in
your earlier test.
Click Close.
IBM Software
__85. What is this? You did not get this on your previous test.
Click OK to dismiss.
__86. Here’s another surprise – Because no data was retrieved from the Flow Exerciser, you cannot
see what path the message took through the flow.

IBM Software
__88. Click Yes to dismiss the pop-up.
IBM Software
Previously, when you tested the malformed XML message, you were able to see the exception path
being taken when testing with the Flow Exerciser. Something about the change you made to the Parse
Timing resulted in the Flow Exerciser behaving differently.
Because you want to be able to handle parsing errors in your flow, you need to determine why the
change you made to the Parse Timing is preventing your flow from detecting the error and handling it.
In the next section you will use the Flow Debugger to better understand what is happening in this case
and how it is different from your previous test.
8.5 Using the integrated Flow Debugger

The Flow Exerciser is a very useful tool for testing a new or modified message flow. But there are times
when the Flow Exerciser may not provide sufficient information for diagnosing a problem. In situations
like that, the integrated Flow Debugger can be a useful alternative.
8.5.1 Key Idea: The Flow Debugger
Key Idea: Flow Debugging.

Read the section below for an overview of the integrated
Flow Debugger.
The Debug perspective in the IBM Integration Toolkit provides a Flow Debugger which enables more
detailed message flow debugging than is possible using the Flow Exerciser.

IBM Software
Using the Flow Debugger, you can set breakpoints in a message flow, and then step through some or all
of the nodes in a flow. While you are stepping through, you can examine and change elements in the
message assembly, as well as variables used by ESQL code and Java code. This is in contrast to the
Flow Exerciser, which shows you the path a given message takes through the flow, but provides no
ability to set breakpoints or to change variables other than at the outset. Using the Flow Debugger, the
ability to set breakpoints at strategic points in the flow, to see and modify the message assembly
between nodes, and to “step into” nodes such as Java Compute nodes for line-by-line debugging,
provide for much more detailed analysis of flow processing than is possible with the Flow Exerciser.
You can debug a wide variety of error conditions in flows, including the following:
 Errors occurring at flow initiation
 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
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.
The Flow Debugger does have some restrictions that must be kept in mind. For example, flows in 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. This is true even if you are debugging different message flows.
Another important restriction on the Flow Debugger is that it cannot be used in conjunction with the Flow
Exerciser. So message flows that are to be debugged must be driven either by external tools (such as
SoapUI) or using the Test Client that is integrated with the IIB Toolkit. You will be using the latter
throughout the remainder of this lab.
__89. In the Integration Node view in the bottom left, right-click the Integration Server called default.
__90. If Launch Debugger (Port is 0) appears, perform the following steps to enable the debugger.
IBM Software
__a. On the Windows Desktop, locate the IBM Integration Console 10 shortcut, and double-
click the icon to start the Console.
__b. The IBM Integration Console for the current installation should appear.
__c. In the Console window, enter the following command to enable the debug port:
mqsichangeproperties TESTNODE -e default -o ComIbmJVMManager -n
jvmDebugPort -v 4449

IBM Software
__d. Once executed, you should see “Successful command completion”.
__e. For the change to take effect, the Integration Node must be stopped and restarted. Enter
the following commands:
mqsistop TESTNODE
IBM Software
The command will take several seconds to execute, but after that you should see
“Successful command completion”.
__f. Restart the Integration Node by entering the following command:
mqsistart TESTNODE
You should see “Successful command initiation”.
__g. You may also see the Integration Toolkit refreshing the node status:

IBM Software
__h. In the Integration Nodes view of the Toolkit, right-click again on the default Integration
Server.
You should see Launch Debugger (Port is 4449) appear, indicating that the debugger is
ready for use.
__91. One very nice feature of the Flow Debugger is that you can set breakpoints at specific points in
your message flow.
To do this, right-click the connector between the IntroLab_Listener node and the CheckCountry
node.
Select Add Breakpoint.
IBM Software
__92. A small blue circle will appear on the connector, indicating at a breakpoint has been set.
__93. Do the same thing on the connector between the IntroLab_Listener node and the
TraceExceptions node – right-click the connector and select Add Breakpoint.
__94. A small blue circle will appear on the connector, indicating at a breakpoint has been set.

IBM Software
Because the Flow Analyzer has been disabled, message flows that are to be debugged must be driven
either by external tools (such as SoapUI) or using the Integrated Test Client that is part of the IIB Toolkit.
8.5.2 Key Concept: The integrated Test Client
Key Concept: The integrated Test Client

Read the section below for information on the integrated
Test Client and how to use it in conjunction with the Flow
Debugger.
With IBM Integration Bus there are two integrated tools for testing integration solutions directly, from
inside the Toolkit, without the need to use external tools. These are the Flow Analyzer (which you have
seen) and the Test Client.
Take a moment to familiarize yourself with the Test Client.
IBM Software
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.
Like the Flow Analyzer, the Test Client has support for features such as monitoring all supported output
paths through a flow, and storing sample messages for replay purposes. It also encapsulates the build
and deploy process, and can be used to launch the debugger.
__95. To launch the Integrated Test Client, click the IntroLab_Listener node to give it focus.
__96. In the Toolkit menu bar, select Flow > Test.

IBM Software
__97. Click OK on the confirmation popup.
__98. The Test Client will be started.
IBM Software
__99. Under Detailed Properties, click the drop-down for Body, and select Edit as text.
__100. With “Edit as text” set, click Import Source.

IBM Software
__101. In the Open window, navigate to C:\student10\IntroLabMessage, select the IN_Request.xml

file, and click Open.
__102. First you will run a good message through.
In the test message, locate customerCountry, and change it from “USA” to “US”.
Click Send Message.
IBM Software
__103. Select the default Integration Server for TESTNODE as the Deployment location.
Also make sure that both the Trace and debug as well as the Stop at the beginning of the
flow during debugging checkboxes are selected.
Click Finish.

IBM Software
__104. Click Yes on the confirmation to launch the Debug perspective.
__105. Review the Debug perspective, and the various featured that are presented.
IBM Software
__106. Note the toolbar and the controls it contains.
__107. Hover the mouse pointer for a brief description of each. Significant controls include:
Resume execution
Terminate
Step over a node
Run to completion
__108. Click to step over the next node in the flow.

IBM Software
Because customerCountry was set to “US”, you should see the following:
__109. Click to run to completion.
__110. You may see the following:
If so, click to resume execution.
__111. In the upper right corner of the Toolkit, click the Integration Development tab to return to the
Integration Development perspective.
IBM Software
__112. Click the IntroLab.mbtest tab to bring the Test Client into focus.
__113. In the Test Client, you see on the left a node-by-node execution trace of the message flow.
On the right you see the response message that was returned by the flow. Because this flow
does no transformation there is no difference from the input message.
And you see the modification you made to the customerCountry, which you changed from “USA”
to “US”.
__114. Next you will run the same test, but this time make a change while the debugger is running.
You will use this modified message (with customerCountry set to “US”) as the starting point.

IBM Software
In the Test Client, right-click the Invoke Message Flow event at the top, and select Duplicate.
__115. A duplicate of the flow test will be created. You can see customerCountry is set to ”US”.
Click Send Message.
__116. Click Yes on the confirmation to launch the Debug perspective.
IBM Software
__117. As before, the debug perspective will launch and the flow will pause at the first breakpoint.
__118. Look at the upper right of the Debug perspective. Locate the Variables view.
Here you can see all four trees that make up the message assembly. At present two of the trees
are populated: The Message and LocalEnvironment trees.

IBM Software
__119. Expand the message tree, and locate the customerCountry element.
It should be set to US, as shown below.
__120. You have already tested the US path in the debugger. So you will change the customerCountry
variable to “CA” and test the Canada path.
Click US in customerCountry, and change the value to CA.
Press Enter to commit the change.
IBM Software
__121. In the debug toolbar, click to step over the next node in the flow.
Because customerCountry was set to “CA”, you should see the following:

IBM Software
The ability to change variables in the message assembly, while the flow is executing, makes the
Flow Debugger a very useful tool for exercising different behaviors the flow might take.
As an optional exercise, you might rerun these steps again, testing the flow with a
customerCountry of “MX”, and observe the behavior in that case.
__122. Click to run to completion.
You may see the following:
If so, Click to resume execution.
__123. In the upper right corner of the Toolkit, click the Integration Development tab to return to the
Integration Development perspective.
__124. Click the IntroLab.mbtest tab to bring the Test Client into focus.
__125. Next you will run the test that was inconclusive when using the Flow Exerciser: the test with
malformed XML.
In the Test Client, right-click the second Invoke Message Flow event, and select Duplicate.
IBM Software
__126. A duplicate of the flow test will be created.
Modify customerCountry by replacing “US with ”&”.
Click Send Message.

IBM Software
__127. What happened? The Debugger did not start. Remember that this is also how the Flow Exerciser
behaved.
But in this case, you have an additional clue. Note the exception message below:
Error sending request to http "http://localhost:7800/IntroLabService"
IBM Software
Why is this clue useful?
Remember how both the flow exception handling and how the Flow Debugger work:
__a. Catching exceptions in a message flow require that the exception be thrown downstream from
the node with the Catch terminal (either an Input node or a TryCatch node).
__b. When the Flow Debugger pauses, it is either at a breakpoint or after doing a StepOver – either
way, it pauses after node execution completes.
What does that tell you?
That the exception must have occurred before control left the Input node in the message flow.
Question: Do you recall how exceptions occurring inside a node need to be handled?
Answer: By wiring the Failure terminal of the flow where the exception is occurring.
8.6 Modify flow and rerun using the Flow Exerciser

Because the exception is occurring before control left the Input node, rather than in a downstream node,
it cannot be handled by wiring the Catch terminal of the Input node. Instead, you need to wire the Failure
terminal of the node in order for your flow to handle the exception

IBM Software
In this section, you will return to the Flow Exerciser to see if wiring the Failure terminal of the
IntroLab_Listener node will catch this exception.
__128. Return to the Debug perspective by clicking on the tab in the upper right corner.
__129. In the Debugger toolbar, click the terminate control to end the debugger
__130. In the upper right corner, right-click the tab.
Select Close to close the Debug perspective.
__131. Close the Test Client by clicking the in the upper right corner of the IntroLab.mbtest window.
__132. Click Yes to save the Test Client script.
IBM Software
__133. Clicking Yes to the above allows you to save, and then reuse later, the execution script you
created using the Test Client.
In the Save Execution Trace dialog, select IntroLab as the project folder to save the script, and
click Finish.
__134. Note that the IntroLab.mbtest script has been saved in a folder called “Flow Tests” in the
IntroLab application folder. This preserves the script for use again at a later time.

IBM Software
__135. In the Integration Nodes view at lower left, right-click the default Integration Server, and if
Terminate Debugger is not greyed out, click it to stop the debugger.
You will now return to the message flow and make the needed changes so that your flow can handle this
exception.
__136. Change the message flow by wiring a connector from the Failure terminal of the
IntroLab_Listener node to the In terminal of the Trace Exception node.
IBM Software
__137. On the message flow toolbar, start the Flow Exerciser.
__139. Click Close to dismiss the Ready to Record message popup.

IBM Software
__140. On the message flow toolbar, Click Send.
__141. Select Test Message (Malformed XML). Verify an “&” is specified for customerCountry.
Click Send.
IBM Software
__142. Click the error.
This is the same error you encountered when testing this message previously using the Flow
Exerciser.
Click Close to dismiss.

IBM Software
__143. You will see that, unlike your earlier test with the Flow Exerciser, this time the message flow was
able to get control after the exception occurred.
Control was passed to the Failure terminal of the IntroLab_Listener node, which you wired to the
exception path of the flow.
Click the icon to see the message tree that was passed out the Failure terminal.
IBM Software
__128. The Flow Exerciser will retrieve the recorded message tree.
__144. When complete, the message tree will be displayed, with the Message portion of the tree
expanded.

IBM Software
Collapse the Properties and HTTPInputHeader folders so that you can just see the payload.
You can see the payload could be parsed as far as the customerCountry element, but parsing
halted at that point.
IBM Software
Why did changing Parse timing from “On-Demand” to “Immediate” alter the behavior of your message
flow in this way?
Despite the fact that Parse timing is an Input node option, in many cases the input node does not
actually need to know the structure of the message. So when Parse timing is set to On Demand, the
message will not be parsed until it reaches a downstream node that does require parsing of the
message. In the case of your flow, that would be the Route node.
Changing Parse timing to Immediate does two things:
1) Forces the message to be fully parsed, as well as validated if that option is also selected.
2) This is done immediately, before the message leaves the input node.
Previously, the malformed element in the message was not detected until the message reached the
Route node. An exception was thrown, caught by the Input node, and routed down your exception path.
With Parse timing set to Immediate, a full parse of the message was attempted before the message was
passed to the next node in the flow. The parse failed, and control was passed to the Failure terminal.
Close all the open editor tabs but leave the Toolkit running.

IBM Software
8.7 Lab clean-up

Optionally, you can clean up the resources deployed in this and previous labs.
The following steps will delete the run-time artifacts from the TESTNODE server.
__129. In the Application Development pane, collapse any folders that are currently expanded.
__130. In the Integration Nodes pane, right-click the default Integration Server, and select
Delete > All Flows And Resources.
__131. Click OK to proceed.
IBM Software
__132. Wait while the default Integration Server is cleared.
__133. All deployed objects should be cleared from the default Integration Server.
END OF LAB 8

IBM Software
Appendix A. Notices
This information was developed for products and services offered in the U.S.A.
IBM may not offer the products, services, or features discussed in this document in other countries.
Consult your local IBM representative for information on the products and services currently available in
your area. Any reference to an IBM product, program, or service is not intended to state or imply that
only that IBM product, program, or service may be used. Any functionally equivalent product, program, or
service that does not infringe any IBM intellectual property right may be used instead. However, it is the
user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter described in this
document. The furnishing of this document does not grant you any license to these patents. You can
send license inquiries, in writing, to:
IBM Director of Licensing

IBM Corporation
North Castle Drive
Armonk, NY 10504-1785
U.S.A.
For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property
Department in your country or send inquiries, in writing, to:
IBM World Trade Asia Corporation

Licensing
2-31 Roppongi 3-chome, Minato-ku
Tokyo 106-0032, Japan
The following paragraph does not apply to the United Kingdom or any other country where such
provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES
CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND,
EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some
states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this
statement may not apply to you.
This information could include technical inaccuracies or typographical errors. Changes are periodically
made to the information herein; these changes will be incorporated in new editions of the publication.
IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this
publication at any time without notice.
Any references in this information to non-IBM Web sites are provided for convenience only and do not in
any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part
of the materials for this IBM product and use of those Web sites is at your own risk.
IBM may use or distribute any of the information you supply in any way it believes appropriate without
incurring any obligation to you.
Any performance data contained herein was determined in a controlled environment. Therefore, the
results obtained in other operating environments may vary significantly. Some measurements may have
Appendix Page 461

IBM Software
been made on development-level systems and there is no guarantee that these measurements will be
the same on generally available systems. Furthermore, some measurements may have been estimated
through extrapolation. Actual results may vary. Users of this document should verify the applicable data
for their specific environment.
Information concerning non-IBM products was obtained from the suppliers of those products, their
published announcements or other publicly available sources. IBM has not tested those products and
cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM
products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of
those products.
All statements regarding IBM's future direction and intent are subject to change or withdrawal without
notice, and represent goals and objectives only.
This information contains examples of data and reports used in daily business operations. To illustrate
them as completely as possible, the examples include the names of individuals, companies, brands, and
products. All of these names are fictitious and any similarity to the names and addresses used by an
actual business enterprise is entirely coincidental. All references to fictitious companies or individuals are
used for illustration purposes only.
COPYRIGHT LICENSE:
This information contains sample application programs in source language, which illustrate programming
techniques on various operating platforms. You may copy, modify, and distribute these sample programs
in any form without payment to IBM, for the purposes of developing, using, marketing or distributing
application programs conforming to the application programming interface for the operating platform for
which the sample programs are written. These examples have not been thoroughly tested under all
conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these
programs.

IBM Software
Appendix B. Trademarks and copyrights

IBM AIX CICS ClearCase ClearQuest Cloudscape
Cube Views DB2 developerWorks DRDA IMS IMS/ESA
Informix Lotus Lotus Workflow MQSeries OmniFind
Rational Redbooks Red Brick RequisitePro System i
System z Tivoli WebSphere Workplace System p
Adobe, the Adobe logo, PostScript, and the PostScript logo are either registered trademarks or
trademarks of Adobe Systems Incorporated in the United States, and/or other countries.
IT Infrastructure Library is a registered trademark of the Central Computer and Telecommunications

Agency which is now part of the Office of Government Commerce.
Intel, Intel logo, Intel Inside, Intel Inside logo, Intel Centrino, Intel Centrino logo, Celeron, Intel Xeon, Intel
SpeedStep, Itanium, and Pentium are trademarks or registered trademarks of Intel Corporation or its
subsidiaries in the United States and other countries.
Linux is a registered trademark of Linus Torvalds in the United States, other countries, or both.
Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the
United States, other countries, or both.
ITIL is a registered trademark, and a registered community trademark of The Minister for the Cabinet
Office, and is registered in the U.S. Patent and Trademark Office.
UNIX is a registered trademark of The Open Group in the United States and other countries.
Java and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle and/or
its affiliates.
Cell Broadband Engine is a trademark of Sony Computer Entertainment, Inc. in the United States, other
countries, or both and is used under license therefrom.
Linear Tape-Open, LTO, the LTO Logo, Ultrium, and the Ultrium logo are trademarks of HP, IBM Corp.
and Quantum in the U.S. and other countries.
Appendix Page 463

NOTES
NOTES
NOTES
© Copyright IBM Corporation 2015.
The information contained in these materials is provided for

informational purposes only, and is provided AS IS without warranty
of any kind, express or implied. IBM shall not be responsible for any
damages arising out of the use of, or otherwise related to, these
materials. Nothing contained in these materials is intended to, nor
shall have the effect of, creating any warranties or representations
from IBM or its suppliers or licensors, or altering the terms and
conditions of the applicable license agreement governing the use of
IBM software. References in these materials to IBM products,
programs, or services do not imply that they will be available in all
countries in which IBM operates. This information is based on
current IBM product plans and strategy, which are subject to change
by IBM without notice. Product release dates and/or capabilities
referenced in these materials may change at any time at IBM’s sole
discretion based on market opportunities or other factors, and are not
intended to be a commitment to future product or feature availability
in any way.
IBM, the IBM logo, ibm.com and WebSphere are trademarks of

International Business Machines Corp., registered in many
jurisdictions worldwide. Other product and service names might be
trademarks of IBM or other companies. A current list of IBM
trademarks is available on the Web at “Copyright and trademark
information” at www.ibm.com/legal/copytrade.shtml.

JCJR 9YVSER Workbook

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

JCJR 9YVSER Workbook

Uploaded by

Copyright:

Available Formats

IBM Software An IBM Proof of Technology

Discovering the value of IBM

© Copyright IBM Corporation, 2015

7.8 TESTING THE EMPLOYEESERVICE_REST REST API ............................................................................. 356

Page 4 Discovering the value of IBM Integration Bus v10

The following symbols appear in this document at places where additional

Icon Purpose Explanation

This symbol calls attention to a particular step or command.

This symbol indicates information that might not be

Lab 1 Getting started

1.1 Building and executing a simple Integration Application

To explain these terms, in order:

 A message flow is like a program but is developed using a visual paradigm.

 An Integration Server is an operating system process where user flows execute.

 An Integration Node is a collection of operating system processes, including one or more

Tools that you will use as part of these labs include:

1.2 Getting to know the IBM Integration Toolkit

Page 6 Discovering the value of IBM Integration Bus v10

__2. Verify that the C:\student10\workspaces\GettingStarted directory is selected.

If not, enter C:\student10\workspaces\GettingStarted.

Lab 1 - Getting started Page 7

If you are not prompted to select a workspace:

__b. Enter C:\student10\workspaces\GettingStarted, or use the Browse button to navigate

Page 8 Discovering the value of IBM Integration Bus v10

Click Go to the Integration Toolkit to dismiss this screen.

Lab 1 - Getting started Page 9

__4. Now familiarize yourself with aspects of the Toolkit.

1.2.1 Key Idea: The Toolkit

The Integration Toolkit.

Page 10 Discovering the value of IBM Integration Bus v10

1.3 Building a simple application

Lab 1 - Getting started Page 11

You are prompted to enter a name for your Application.

__6. Enter IntroLab for the Application name. Click Finish.

Now you will create a new message flow.

__7. Under IntroLab, click (New).

__8. Select Message Flow.

Page 12 Discovering the value of IBM Integration Bus v10

__9. Here you are asked to name the message flow.

Note: An Application may contain multiple message flows.

__10. Enter IntroMessageFlow in the Message Flow name box.

__12. Select the Properties tab.

__13. Select the Description tab.

Lab 1 - Getting started Page 13

__14. Enter the following:

Enter 1.0 for the Version field.

Enter your choice of information in the Long description field.

The HTTPInput node is in the HTTP drawer.

__15. Click on the drawer to open it.

Page 14 Discovering the value of IBM Integration Bus v10

Lab 1 - Getting started Page 15

__18. Change the name of the node to “IntroLab_Listener.”

Press Enter to complete the rename.

Select the Basic tab in the Properties pane.

Page 16 Discovering the value of IBM Integration Bus v10

__19. Note the hotspot on the right.

__20. Click in the Path suffix for URL field.

__22. Enter /IntroLabService as the Path suffix for URL.

Lab 1 - Getting started Page 17

__24. Enter URL Suffix: IntroLabService in the Short description field.

Page 18 Discovering the value of IBM Integration Bus v10

__27. The Trace node is in the Construction drawer.

Click the drawer to open it.