BIE Quick Tutorial

By
-
49

Author: Benjamin D. Thomas

WDI writes “BIE Quick Tutorial.

The Business Integration Engine (BIE) is a full java-based application to application integration server. It competes directly with applications like Microsoft BizTalk, but is truly cross-platform since it is written in Java.

As easy to use as BIE is,
it is still a very complex system. Getting started can be a
tremendous challenge to say the least. This is a short guide to
demonstrate BIE’s power, and also to get you started using BIE as
quickly as possible.

Before we get started,
there are a few things we should note. This is not meant to be a
comprehensive reference guide, for that get yourself a copy of the
BIE
Docs. This document is also not meant to be a complete
training guide, for that check out WDI’s
comprehensive list of training programs. And finally,
we’re assuming that you’ve already downloaded
and installed
the latest copy of BIE.

Familiarize Yourself

The first thing you should
do is familiarize yourself with BIE and it’s main components. Take a
few minutes to view all of the pages in the BIE dashboard. The main
areas of interest are under the “Configurations” and “Reports”
headings in the navigation. You don’t need to know what each of these
things are or how to use them just yet. Instead, know where they are
so that when we reference them later you can find them quickly.

The Process

In order to show you how
to use BIE, we need a business process. In this case we’ve created a
fictional purchase order transaction between Jones Publishing and
Smith Printing. Jones Publishing wants to send a purchase order to
Smith Printing to get some materials printed for an upcoming
publication. The following is minimally how the process will flow:

  1. Jones Publishing will
    generate a purchase order (PO) as a comma separated values (CSV)
    file.

  2. The PO will enter
    Smith Printing’s BIE server.

  3. The PO will be
    translated from Smith Printing’s PO format to Smith Printing’s order
    format, which is a custom XML format.

  4. The order will then
    be handed off to some internal system at Smith Printing for
    processing.

Documents and
Translation

Once you know what a
process looks like, you then need to define the documents as W3C
Schemas and create a map between those two formats.
For the sake of expediency we’ve created the schemas and map for you.

To see the map open the
BIE map builder. On Windows this can typically be found in
c:biebinmapper.exe and in
Linux and UNIX environments it can typically be found in/usr/local/bie/bin/map.sh.

Once you’ve opened the Map
Builder, click on the icon that looks like a folder in the toolbar.
When prompted select Jones2Smith.xml
and click on the “open” button to load the map. Depending upon
the speed of your system it may take a few moments to load the map.
When it’s loaded you should now have a screen that looks like this:

[Click to view what the Map Builder looks like.]

Notice that on the left we
have the CSV document format of Jones Publishing, which is very flat.
On the right we have the XML document format of Smith Printing, which
has some heirarchy as most XML documents do.

The lines inbetween the
two sides represent the mapping of individual fields. To map one
field to another you simply click on a field on the left, and drag
your mouse to a field on the right. If the document is too large to
drag directly, you can access the clipboard by right-clicking on any
field on the left and then paste by right clicking on any field on
the right.

Also note the box labeled
“multiply”. That is a macro that, as its name implies, multiplies
two fields and then the result can be fed into an element of the
other document, or it can be fed into another macro for additional
processing. To see the other macros available, right click in the
center of the screen.

Behind the scenes the map
builder is actually generating XSL. To see the resultant XSL click on
the compile icon in the toolbar. It is the second to last icon on the
right of the toolbar.

Now close the map builder,
and be sure not to save any changes you made or the rest of
the tutorial will fail.

Document Parsing

BIE
cannot translate or
otherwise manipulate anything other than XML, therefore every
document must be transformed to XML. Luckily BIE has a number of
document parsers built in to perform these transformations between
various formats and XML.

Open
your BIE dashboard, log in, and click on the “Message Formats”
page under the “Configurations” heading. You’ll notice a list of
message formats (or document parsers) that have already been
configured, including the Jones PO.

Click
on the Jones PO document format configuration in the list. It will
then appear at the bottom of the page. Notice that there are a number
of configuration parameters. Each type of message format has its own
set of parameters. A detailed list of all the message formats, and
their parameters can be found in the BIE
docs.

We’ve
already configured everything for you in this case, so let’s move on.

Maps

We’ve
already talked a little bit
about how maps are created in the map builder, but in order for BIE
to use a map, it must have a copy. If you develop your map on the
same machine as your BIE server, then the map will already be
installed. Otherwise you can upload it by clicking on the “Maps”
link under the “Configurations” heading in the BIE dashboard.

Note
that we’ve already done this for you as well.

Routes

Routes,
or business processes, are defined using BIE’s route builder. Click
on the “Routes” link under the “Configurations” heading in
the BIE dashboard. Now you’ll see a list of the routes installed in
your system, and whether they are enabled or disabled.

You
should see the JonesPubPO route. Click on it.

[Click to see what the process builder looks like.]

You
are now in the process builder. You can see a visual representation
of the process. The series of rounded gray boxes down the left
represent the process. The individual rounded boxes are called
actions. The square boxes directly to the right of the actions
represent what document(s) are being dealt with in a particular
action. And to the right of the documents are icons that represent
what is actually happening to the document inside the action.

Let’s
talk about what’s going on in this route. First we receive a document
called “Jones_CSV”, which is what initiates or triggers this
route. Next we log the incoming document so that we have a copy of it
in case we need to diagnose a problem later. Then we convert the
Jones PO to the Smith Order using the map we discussed earlier. Next
we log a copy of the translated document, so we can diagnose a
problem if needed. Then we write the Jones Order to the file system.
And finally, we tell BIE to send a copy of the original document back
to the sender.

In
the step where we write the Jones Order to the file system, we could
have instead inserted it into a database, sent it out over a web
service to some application server, or dumped it to an FTP server for
processing. We have used the file system in this case so that you can
test the BIE without setting up some external system to connect to.
You can select “add an action” link to view a list of available
actions.

Also,
in the final step, we specify that the route should send back the
original document to the sender. This step is skipped in most
protocols, but some protocols are capable of real-time round-trip.
This means that they send you one document and expect another back.
Web services are an example of a protocol that supports this
functionality. Instead of the original document, we could also have
sent back a receipt for the purchase order, or maybe even an advanced
ship notice (ASN).

Set Up The Demo

Now
that we’ve covered some of the basic components, let’s set up a
demonstration so you can see BIE in action.

First,
assuming you’re still on the route builder page, scroll to the top of
the page and click on the link that reads “enable this route.”
This will tell BIE that we wish to being servicing requests for this
route.

Now
click on the “System” link under the “Configuration” heading
in the menu. Scroll down to the file system listener section. Enable
the file system listener, and set the watch interval to “5”
seconds. Also make note of the watch directory path as we’ll need it
later. Now scroll to the bottom of the page and click “save”.

After
making changes to system settings, we need to restart the BIE server.
On Windows restart the service. On UNIX style systems just run stop
and start from the command line.

Run The Demo

To
run the demo we first need to get the sample Jones Purchase Order
document. It can be found in the translation/data folder of your BIE
install. On most UNIX style systems it can be found here:

/usr/local/bie/translation/data/JonesPubPO.csv

And
on Windows environments, it can be found here:

c:bietranslationdataJonesPubPO.csv

Rename the file from
JonesPO.csv to Jones2Smith.csv. What this does is tells BIE that this
file should be processed with the Jones2Smith route. If we wanted to
put our own identifier on the file we could also call the file
Jones2Smith_foobar.csv.

BIE has the ability to
accept input via multiple protocols including FTP, webservices, HTTP,
HTTPS, and by watching a directory. For this example, we will be
using the file system watched directory. More information on the
available listeners can be found in the BIE docs.

Since we will be placing
our file in the watched directory, we need to tell BIE which route
to run. This is done via an identifier in the filename. Notice that
the name of the file is the same as the route that we would like to
run. BIE will use all characters in the filename up to a.(dot) or _
(underscore) as the route identifier. Since the JonesPubPO.csv file
already contains the route identifier we can continue to the next
step.

Now we need to copy the
file into the watch directory that we noted in the last step. Unless
you changed it, the folder can be found in the data/filesystem/watch
folder of your BIE install. On UNIX style systems this can typically
be found here:

/usr/local/bie/data/filesystem/watch

And on Windows
environments, it can be found here:

c:biedatafilesystemwatch

Within 5 seconds (because
that’s the time we told BIE to wait between checking for documents)
BIE should pick up the document, and process it.

Results

Now that we’ve processed a
document with BIE, we can finally see the fruits of our labor. Let’s
first look in the folder where BIE was supposed to drop the document.
It can be found in the data/filesystem/out folder in your BIE
install. On UNIX style systems this can typically be found here:

/usr/local/bie/data/filesystem/out

about:

And on Windows
environments it can be found here:

c:biedatafilesystemout

Go ahead and open the
document to verify that it is indeed XML.

Now, open the dashboard,
log in, and click on the link called “Transactions” under the
“Reports” heading in the menu.

You should now see a list
of the transactions that have been logged by BIE. At this point there
is probably only one with a transaction ID of 1000. Click on the
transaction ID to view the details of the transaction.

Initially you should see
the incoming document. It should look like a mess of text with commas
separating each field. If you click on the link under “Mark 2”,
you should then see the translated document. This should look like a
very clean XML document.

Conclusion

You’ve
now completed this brief tutorial. You should revisit any parts that
were unclear to see if they now make sense, since you’ve seen a whole
process in action. Keep in mind that this is a very simple process,
compared to what BIE is capable of.

Now
that you’ve seen the power of BIE, you should easily recognize how
much time it can save integrating business processes, over the
traditional methods of custom coding. Users that are familiar with
BIE can typically build processes in BIE in a tenth of the time it
would take them to build the process from scratch.

Links

“

RELATED ARTICLESMORE FROM AUTHOR