flows

Developing an Integration Flow

Version: 17.07

First create an empty project as described in Creating a project section. When creating an empty project, select the HTTP NIO module from the connector list. Further, from the processors list select Flow Control, Message Transformation and Message Validation modules. After creating the project, add it as a Maven project

Project Structure

This empty project is a basic maven project with a few new items. Let’s see what are these new items in the project

Project.xpml File

This file contains the information about your project such as name, version and description.

<x:project id="mySampleProject" name="mySampleProject"
version="1.0-SNAPSHOT"xmlns="http://www.springframework.org/schema/beans"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:x="http://www.adroitlogic.org/x/x-project"  xsi:schemaLocation="http://www.adroitlogic.org/x/x-project http://schemas.adroitlogic.org/x/x-project-1.0.0.xsdhttp://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-4.1.xsd">
    <x:description>
        A sample project that demonstrates the projects concept
    </x:description>

    <x:flows>
           <x:flow id="sampleFlow" file="helloWorldFlow.xcml"/>
    </x:flows>

    <x:resources>
    </x:resources>
</x:project>

Further, within the flows tag, all the integration flows in your project where file path is specified relative to the conf directory will be added. When you run the project, only the integration flows specified in this section will be deployed. Apart from that within the resources tag, you can specify re-usable complex spring beans which in return used by components in your integration flow.

Conf Directory

This is where all your integration flows must reside. It is not recommended to create integration flows anywhere else in the project. Although, you can create sub-directories within conf directory to organize your flows.

Apart from these main two items, there are few files in the test/resources directory and for now you do not need to worry about those.

Now let’s create our first integration flow. Keep in mind that all the integration flows which are created must reside within the conf directory. First right click on the conf directory and from the context menu, select Integration Flow. After that specify helloWorldFlow as the flow name and click on OK button.

Now you can see that there is a new file added to the conf directory and double click on it to open it in the editor view.

Main Components of the Editor View

studio ide overview
Figure 1: Design View

1 . Main Toolbar

The main toolbar (Figure 1:1) contains all the important functionalities which affect the design view. Below list contains brief description of each button and the respective functionality of that button (Figure 1).

  1. Toggle the component pallet’s visibility

  2. Toggle the property pane’s visibility Toggle the visibility of grids on the design canvas

  3. Refresh the editor view Highlight the message execution path in the integration flow Clear the highlighted message execution path

  4. Zoom in the design pane

  5. Zoom out the design pane

  6. Reset the Zoom view of design pane

2 . Component Pallet

This pallet (Figure 1:2) contains all the components required to create an integration flow. There are ingress/egress connectors, processors, and so on. If you want to refresh your

3 . Properties Pane

This pane (Figure 1:3) contains all the properties which can be specified by the user for a particular component. i.e. for a given component to function properly, user has to manually specify some properties and these properties varies from one component to another. Apart from that, this pane contains a Documentation tabs which provides the basic documentation of the specific component.

4 . Design Canvas

This is where you can create your integration flow. You can drag and drop component from the component pallet in to the design pane and keep on creating your flow (Figure 1:4).

5 . Component

sample component
Figure 2: Sample Component

Each component is unique and designed to execute a specific logic. As shown in figure 2 the circles surrounding the component icon are called ports. Mainly there are four port types.

  • In-Port (grey color circle) - This is where messages are given as input to the component. A component can have only one in-port and specific type of components such as ingress connectors have zero in-ports

  • Out-Port (green color circle) - This is where the output message is emitted from the component. There can be zero or more outports for a particular component.

  • Side-ports (blue color circle) - These ports are used to connect other components as parameters for a particular component. There can be zero or more side ports for a particular component.

  • Exception-Port (red color circle) - This is a sub set of out ports and an output is emitted from the component through this port if an exception or an error occurs while executing the component’s logic, so that the user can gracefully handle it.

Creating the Hello World Flow

Now let us start adding component to the design pane and create our flow. In this sample flow, first we will create a flow where the UltraESB will accept a message through HTTP protocol and send it to a backend service, and return the response received from the back end service to the original client.

There are two ways you could add components to the design pane. First way is to just simply drag and drop the component into the design canvas. When you drag and drop a component to the pane, that particular component instance will be given a random UUID. The other way is to click on the component on the component pallet and then you will be presented with a pop-up where you can specify a name for that component.

For our basic flow we need two components. First one is HTTP NIO Listener (under connectors/ingress category) and the other one is the HTTP NIO Sender ( under connectors/egress).

Next we need to connect these two component as shown in figure 3. We have connected the out port of the HTTP NIO Listener with the in-port of the HTTP NIO sender and the out-port of the HTTP NIO sender with the in-port of the HTTP NIO Listener.

basic flow
Figure 3: Connected Integration Flow

Now let’s run the flow validator and see if our flow is correct. In the bottom tab bar, there is a tab named flow Validation and within that tab select the module you want to validate and click on the start button.

flowvalidator
Figure 4: Flow Validation Result

As you can see from the result in figure 4, we have few errors in our flow. Double clicking on the error will show you the erroneous component.

These errors indicates missing configuration. Hence we need to specify few properties for these components in-order for those to work properly.

If you hover over a component, you can see the blue cog icon and, by clicking on that, you can open the property pane of that component. You can open the property pane by double clicking on the component as well.

For the HTTP NIO Listener, mainly there are two properties we need to specify

http listener prop
Figure 5: Property configuration for HTTP NIO Listener
  • Http Port - The port we want our http listener to start listening for incoming request. For this example let’s specify 8280.

  • Service Path - The resource path where we want to filter out the incoming requests. Specify service/echo-proxy for that.

After specifying those properties, click on the save button. Now we have configured our HTTP listener to listen at service/echo-proxy on port 8280 for incoming requests.

Similarly, we need to configure our HTTP NIO sender as well. For the sender, all you have to specify is the address of the backend system. for this example let’s specify http://localhost:9000/service/EchoService as shown in figure 6.

http sender prop
Figure 6: Property configuration for HTTP NIO Sender

We have completed the configuring our flow. Now you might be wondering how to start a backend service on port 9000.

Fear not, we provide a very basic jetty server for testing within the Ultra Studio. As shown in figure 7 click on the start button to start a Jetty server on port 9000.