Business Integration Engine

This is unofficial documentation of Brunswick's Business Integration Engine - BIE, and covers version 6.04. Development from the original team seems to have stopped, and a fork was started. The fork is called BIE-gpl, and a beta version of 6.05 is available for download. BIE is now sold by Redberri.

Introduction

Licensed under the Free Software Foundations' The GNU General Public License, Brunswick WDI's Business Integration Engine is free (as in freedom) software and available at no cost. BIE can help you transform messages and transport messages between applications which does not have these capabilities.

BIE uses a number of free (as in freedom) software components as its foundation. The original contributions to the free software community are the web application Dashboard and the Java client Map Builder.

Dashboard lets you create workflows using drag-and-drop and connectivity in and out of BIE. The Map Builder helps you set up translation from one XML schema to another.

Installation

GNU/Linux

• Download BIE 6.04 for your platform from Sourceforge.net at http://sourceforge.net/project/showfiles.php?group_id=79291. Choose the zipped archive file bie-linux-6.0.4.tar.gz.
• Unzip the archive file any way you like. Here is one way using a console window:

tar xfvz bie-linux-6.0.4.tar.gz

The result is a new subdirectory called bie-linux-6.0.4.

• Change to superuser mode or root with su, enter root's password.
• Change directory to the new subdirectory and type

./install.sh

to install BIE. A GUI opens up, just follow the instructions given.

• The install defaults to /usr/local/BIE.
• Check the box Start BIE
• The default user is

admin

and the default password is

123qwe

• You are done.

Files and sub directories

See File Tree Structure.

Setup

• Open the BIE Dashboard web application by pointing your web browser to

http://localhost:5803/

• Log in with your user name and password.
• On the BIE Dashboard Welcome page, click Mail Settings under the System Settings menu, and give your SMTP server and email address, then hit the Save button. You may now test if BIE is able to send you an email by entering your email address in the text field, then hit the Test button, and check your email application for any new email from BIE.

Dashboard - web application overview

System

Global Settings

Global System Configuration

General Settings

• Remote Client Management may be set to either

Disabled

or

Enabled

from the drop down menu. Disabled is the default setting.

Shut Down

• Stops All Services by hitting the red button marked

Shut Down   
  

System Log Settings

• Overall Logging Level may be set to one of the following from the drop down menu
  • ALL
  • DEBUG
  • INFO
  • WARN
  • ERROR
  • FATAL
  • OFF

• Declared Appenders. Full control of the logging behavior can be configured in the /usr/local/BIE/services/jboss/server/default/conf/log4j.xml file. Properties for appender BIE_DETAILS

 BufferSize:8192
 Class:class org.jboss.logging.appender.DailyRollingFileAppender
 Filter:null
 Append:true
 ErrorHandler:org.apache.log4j.helpers.OnlyOnceErrorHandler@7e80a
 BufferedIO:false
 DatePattern:'.'yyyy-MM-dd
 Name:BIE_DETAILS
 File:/usr/local/BIE/logs/bie-details.log
 ImmediateFlush:true
 Threshold:INFO
 FirstFilter:null
 Layout:org.apache.log4j.PatternLayout@113108b
 Encoding:null

Listeners

Listeners are BIE's supported methods of getting messages into BIE for processing or out to a recipient when done. Version 6.0.4 supports HTTP/HTTPS, watched directory, FTP, scheduler, POP and FTP directory watcher. You may edit most listeners by hitting the Edit button. To start a listener, hit the Enable button. To stop a listener, hit the Disable button.

Registered Listeners

Status	Name	Description
Running	JMS Listener	Each workflow is represented is represented by a queue. To receive a response from the workflow, the reply to header must be defined. -Initial Context Factory: org.jnp.interfaces.NamingContextFactory -Queue Connection Factory: UIL2ConnectionFactory		Enabled
Running	HTTP/HTTPS	The HTTP/HTTPS listener runs the administration console, web services engine, and HTTP GET/POST listeners. GET and POST listeners reside at /listener/HTTPGet and /listener/HTTPPost, and require parameters routeID and message to be specified.	Edit
Stopped	Watched Directory	The Watched Directory listener monitors a directory for new files and passes the file content to BIE for processing. This Listener uses all characters in the filename up to a .(dot) or _ (underscore) as the route identifier.	Edit	Enable
Stopped	FTP	The FTP Listener runs routes based on FTP requests. PUT requests transfer messages to BIE. GET requests retrieve messages from BIE. This Listener uses all characters in the filename up to a .(dot) or _ (underscore) as the route identifier.	Edit	Enable
Running	Scheduler	The Scheduler triggers routes at fixed intervals. Each job signals a route to run when a scheduled interval is reached.	Edit	Disable
Stopped	POP Listener	Watches a POP3 account and downloads messages for use by BIE. The route key must be defined as the subject(inline text) or file name(attachment).	Edit	Enable
Stopped	FTP Directory Watcher	Watches a directory on a remote FTP server for new files. The route key will be inferred from the file names.	Edit	Enable

Mail Settings

This lets you specify where BIE sends system notifications by email.

Mail Configuration

Mail Server

• Mail server host name - type your SMTP server in this field
• Maximum Notification Message Size (bytes) - the default value is 51200
• System E-Mail Address - type your email address in this field
• Use E-Mail Authentication - check this box if your SMTP server requires authentication credentials
• Authentication User Name - your SMTP user name
• Authentication Password - your SMTP password

Hit the Save button before testing.

Test Mail Configuration

Run this test to see if your mail server is accessible by BIE

• Enter E-Mail Address - type your email address here

Hit the Run Test button.

JDBC Drivers

You can add database connections to BIE using JDBC drivers. BIE ships with a MySQL (won't work with new versions of MySql, e.g.:5.0,) , and an ODBC driver. You are using something else, you must add the appropriate driver.

Oracle

Oracle driver can be added as follows. 
 1.	Click on the System --> JDBC Drivers menu option
 2.	In the Manage JDBC Connections screen, click on “Register a Driver” link
 3.	In the “Register JDBC Driver” screen enter the parameters as follows
       a)	Driver Name : Oracle
       b)	Driver Class Name : oracle.jdbc.driver.OracleDriver
       c)	Driver Archive : ojdbc.jar 
       Click on the Register button.
 4.	Add a connection to the DUMMY schema as follows, Click on the Add Connection button against the newly registered      
       driver.
 5.	In the “Choose JDBC Driver” screen enter the values 
       a)	Select Driver :  Oracle (The driver that we added in the previous step)
       b)	Connection URL : jdbc:oracle:thin:@<HOSTNAME>:<PORT>:DUMMY
       Click on the continue button.
 6.    Set the connection properties as 
       a)  Connection Name: DUMMY
       b)  URL: jdbc:oracle:thin:@<HOSTNAME>:<PORT>:DUMMY
       c)  Username: username
       d)  Password: password
       Click on the “Save” button.
 7.	In the “Manage JDBC Connections” , we can find the newly added connection listed.
 8.    Click on the Test button next to the newly added connection .

MySQL

The MySQL JDBC driver that ships with BIE 6.04 is version 2.014, which does not appear to work with MySQL version 4.1.7 or newer. The latest stable MySQL JDBC driver is version 3.1.13, which may be downloaded from http://www.mysql.com/products/connector/j/ The latest driver solves the issue of connecting BIE to a MySQL on the same server, but you may need to add localhost.localdomain in the Host column to your User table in the MySQL database.

PostgreSQL

The PostgreSQL driver may be downloaded from http://jdbc.postgresql.org/download.html.

HSQLDB

BIE uses an internal Hypersonic database, now called HSQLDB, that contains configuration, state, and audit information. See

Other JDBC drivers

Chui's counterpoint lists a number of JDBC driver and JDBC URLs.

Some drivers like DB2 require more than one jar file. If so, just create a dummy driver for each extra jar file as a way to upload it. You may need to restart the BIE service before it notices the new jar files.

LDAP Connections

Lightweight Directory Access Protocol or LDAP is a protocol for querying directories. Here you can add your companies LDAP directory service.

Workflow

Workflow

A common mistake/issue when trying to run a workflow, is not provide a start message. The default config for a newly added workflow is to receive InputMessage, with the message format as StandardXML. So, to start a worflow, you've got to provide at least a minimum xml tag, e.g.: <ok/> Changing the format to StandardRaw will solve this issue.

Message Formats

BIE only understands XML, so you must express any input or output as XML schemas before you can use BIE. If you receive a file containing Comma Separated Values - CSV for short - BIE can help you generate the necessary schema.

Map Builder - moving data between applications with XML Schemas

XML Schemas express shared vocabularies and allow machines to carry out rules made by people. They provide a means for defining the structure, content and semantics of XML documents.

Map Builder is a Java application, which lets you load an input schema and output schema, and then use drag and drop to establish links between matching fields from the input schema to the output schema. Once a link is established, you may add processing instructions to the link, e.g. mathematical, logic, string operations and so on.

The map is then saved as an XSLT transformation file, meaning it shows how input documents are converted to output documents.

Testing maps

IMPORTANT: Don't use a file with Comma Separated Values (CSV) when testing your map! A error box with the following message will appear:

Error
An unexpected error occurred.
Source:
Content is not allowed in prolog.

Hit the OK button to close the box.

CORRECT WAY: Use an XML version of the CSV file. The Dashboard can be used to generate the correct parsed XML output for a given message format. Copy and paste this parsed output to a file, and use this file for testing your map in Map Builder. See tutorial below for details.

Tutorials

Some assumptions are made in the following tutorials:

• You have read the entire tutorial before proceeding, and understand that you follow the instructions at your own risk.
• You have administrator or root rights to the server where BIE is installed.
• BIE has been started. A standard installation on GNU/Linux can be started this way

/usr/local/BIE/bin/start.sh

• You have logged into Dashboard. A standard installation regardless of platform makes the Dashboard available from the server to your browser at

http://localhost:5803/

given the user name

admin

and the password

123qwe

• You have started the Map Builder. A standard installation on GNU/Linux can be started this way

/usr/local/BIE/bin/map.sh

• You have a text editor available.

Lesson 1 - from CSV to XML

• Open your text editor
• Enter or copy and paste the following text, making sure there is a new line character between them (hit the Enter or Return key at the end of line one)

MyName,MyAddress,MyPhone,MyCountry
Joe Schmoe,Anywhere Street Number 1,123-456-789,Anyplace on Earth

• Save the file as Lesson1.CSV to

/usr/local/BIE/translation/data

• Open the Dashboard, select Workflow from the top menu, then select the menu item Message Formats
• Under the heading Configurations, select type Delimited from the drop-down menu, then hit the "add new" button.
• In the Name field write

Lesson1

• Set the Process Header radio button to On
• Change the Root tag to

Lesson1

• Hit the save button.
• In the Format column under Configurations, you will now see a link named Lesson1 - hit it.
• A new form is now available, called Format Testing / Schema Generation.
• In the "Select a local file" field, enter or select through the browse button the address to Lesson1.CSV

/usr/local/BIE/translation/data/Lesson1.CSV

• Hit the "Run Formatter/Generator" button.
• A new three part form is now available:

• Generated schema. Give the name

Lesson1.xsd

in the text field. DON'T HIT THE "Save to Server" button just yet.

• Parsed Ouput - a BIE typo, should be Parsed Output. Select the parsed XML output, copy, and paste into a new file in your text editor. Save the file as

Lesson1.xml

• NOW you can hit the "Save to Server" button. We did it this way to avoid back-button browser problems.

• Open Map Builder, and hit the "Create a new map" button in the top left corner. The steps is outlined to the left, and you can you select

Lesson1.xsd

as your source schema, then hit the Next button.

• Select Lesson1 as the source schema's root element, and hit the Next button
• Select the suggested File Name for the base path for source includes/imports by hitting the Next button
• Select

Lesson1.xsd

as your target schema. Yes, it's the same one, but for the purposes of this lesson it will do. Hit the Next button.

• Select Lesson1 as the target schema's root element, and hit the Next button.
• Select the suggested File Name for the base path for source includes/imports by hitting the Next button.
• Save the map file to the map folder with the file name

Lesson12Lesson1.xml

by hitting the Finish button.

• The map is loaded with the source schema's fields on the left, and the destination schema's fields on the right.
• Click the source schema's row icon and hold down the mouse button while moving it to the destination schema's row icon before you let the mouse button go. You should now a blue link between the two schemas.
• Repeat the linking process - MyName to MyName, MyAddress to MyAddress, MyPhone to MyPhone, MyCountry to MyCountry.
• Hit the Compile XSLT button from the tool bar.
• Hit the Test XSLT transformation button, and select

Lesson1.xml

• The Save result dialog opens, change the file name to

Lesson1_transformed.xml

and hit the Save button.

• Open your text editor, and load the file

Lesson1_transformed.xml

You should see that the data from the source fields have been accurately mapped to destination fields.

• Right-click the MyName field in the source schema and select Unlink. Do the same with MyAddress.
• Now link the source field MyName to the destination field MyAddress. Link the source field MyAddress to the destination field MyName.
• Save the new map.
• Compile the new map.
• Test XSLT transformation using

Lesson1.xml

as the source file and save the result as Lesson1_transformed_again.xml

• Open

Lesson1_transformed_again.xml

in your text editor. You should see that Joe Schmoe is now in the MyAddress field, and his address has become his name.

Lesson1 is now over. You should try BIE to find what works or not. Come back here and create new lessons. :-)

Lesson 2 - creating a workflow

In Lesson 1 you learned how to create a map between one XML Schema to another in Map Builder, and to test the transformation. The point of BIE is to automate these kinds of mappings, and that is what we are going to do in this lesson. This time we will be mostly working in the Dashboard, creating a workflow.

To be continued... In the interim, please look at the JonesPubPO workflow.

Lesson X - setting up EDI of encrypted documents

An idea for a future lesson:

Health professionals exchange sensitive patient information electronically using encrypted XML Schemas. Referrals and reports are transported by the thousands every single day of the year. This lesson will describe the use of GNU Privacy Guard, perhaps Idealx X.509 Certificate Authority and BIE for this purpose.

References

• http://bie.sf.net/
• http://bie.sourceforge.net/
• http://sf.net/projects/bie
• http://sourceforge.net/projects/bie
• http://www.brunswickwdi.com/bie
• http://www.whitemiceconsulting.com/taxonomy/term/13
• http://www.whitemiceconsulting.com/node/56
• http://www.whitemiceconsulting.com/node/78 - Resetting An Account's BIE Password
• http://www.redberri.com/redberri/index.do
• http://biewiki.schtuff.com/
• http://www.adaptivedynamics.net/index.pl/faq
• http://ixdb.de/business_integration.html - Some patches for the MAP Builder

References to BIE-gpl

• http://www.bie-gpl.org/
• http://sourceforge.net/projects/bie-gpl/