Wikibooks

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

edit

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

edit

GNU/Linux

edit 
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

edit

See File Tree Structure.

Setup

edit
  • 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

edit

System

edit

Global Settings

edit
Global System Configuration
edit
General Settings
edit
  • Remote Client Management may be set to either
Disabled

or 

Enabled

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

Shut Down
edit
  • Stops All Services by hitting the red button marked
Shut Down
System Log Settings
edit
  • 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

edit

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

edit

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

Mail Configuration
edit
Mail Server
edit
  • 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
edit

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

edit

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

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
edit

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

HSQLDB
edit

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

Other JDBC drivers
edit

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

edit

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

Web Services

edit

Workflow

edit

Workflow

edit

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

edit

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.

Maps

edit

Plugins

edit

Reports

edit

System Info

edit

System Logs

edit

Transactions

edit

Security

edit

Commands

edit

Groups

edit

Users

edit

Help

edit

Forums

edit

License Policy

edit

License

edit
edit

Map Builder - moving data between applications with XML Schemas

edit

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

edit

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

edit

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

edit
  • 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

edit

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 3 - validate input against DTD

edit

Lesson X - setting up EDI of encrypted documents

edit

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

edit

References to BIE-gpl

edit
Retrieved from "https://en.wikibooks.org/w/index.php?title=Business_Integration_Engine&oldid=4237909"