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.

GNU/Linux
tar xfvz bie-linux-6.0.4.tar.gz The result is a new subdirectory called bie-linux-6.0.4. ./install.sh to install BIE. A GUI opens up, just follow the instructions given. admin and the default password is 123qwe
 * 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:
 * Change to superuser mode or root with su, enter root's password.
 * Change directory to the new subdirectory and type
 * The install defaults to /usr/local/BIE.
 * Check the box Start BIE
 * The default user is
 * You are done.

Files and sub directories
See /File Tree Structure/.

Setup
http://localhost:5803/
 * Open the BIE Dashboard web application by pointing your web browser to
 * 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.

General Settings
Disabled or Enabled from the drop down menu. Disabled is the default setting.
 * Remote Client Management may be set to either

Shut Down
Shut Down
 * Stops All Services by hitting the red button marked

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

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
 * 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

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.

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

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:@::DUMMY       Click on the continue button.  6.    Set the connection properties as         a)  Connection Name: DUMMY b) URL: jdbc:oracle:thin:@::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
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.:  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
MyName,MyAddress,MyPhone,MyCountry Joe Schmoe,Anywhere Street Number 1,123-456-789,Anyplace on Earth /usr/local/BIE/translation/data Lesson1 Lesson1 /usr/local/BIE/translation/data/Lesson1.CSV
 * 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)
 * Save the file as Lesson1.CSV to
 * 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
 * Set the Process Header radio button to On
 * Change the Root tag to
 * 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
 * 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.

Lesson1.xsd as your source schema, then hit the Next button. 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. Lesson12Lesson1.xml by hitting the Finish button. Lesson1.xml Lesson1_transformed.xml and hit the Save button. Lesson1_transformed.xml You should see that the data from the source fields have been accurately mapped to destination fields. Lesson1.xml as the source file and save the result as Lesson1_transformed_again.xml 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.
 * 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
 * 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
 * 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
 * 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
 * The Save result dialog opens, change the file name to
 * Open your text editor, and load the file
 * 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
 * Open

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 to BIE-gpl

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