2 Configuration File eai_ini.xml

This chapter describes the configuration file.

2.1 Setting up the Configuration File eai_ini.xml

The configuration file eai_ini.xml consists of certain sections for the different modules of the Enterprise Integration Platform (Controller, Connector and Mapping). Each one of them needs to be set up accordingly in order to have the Enterprise Integration Platform start up and run properly.

2.2 Common Section

The Common Section is the part marked below the common configuration comment. These configuration values may be used in the following sections:

Controller Section
Admin Section
Cryptographer Section
Version Section

<!--Application -->
<application version="2.2.0">
     <!-- application configuration -->
     ...
     <!-- common configuration -->
     <archive-dir>${eai.home}/archive</archive-dir>
     <data-dir>${eai.home}/data</data-dir>
     <temp-dir>${eai.home}/tmp</temp-dir>
     <log-dir>${eai.home}/log</log-dir>
     <log active="true">
           …
     </log>
     <locale>system</locale>
     <encoding>UTF-8</encoding>
     <appearance>java</appearance>
</application>

Note:

The directory tags, e.g. <data-dir>, use placeholder variables like ${eai.home}. ${eai.home} have to be predefined by either specifying the environment variable EAI_HOME or by editing the file eai.properties in the conf directory where the installation directory of the Enterprise Integration Platform must be taken (see the Enterprise Integration Platform Installation Guide for Agile e6.1.3.0).

Details of the XML tags:

Tag	Description	Values
archive-dir	Directory for archiving data via the Administrator	${eai.home}/archive
data-dir	Directory for data files (e.g. internal database files)	${eai.home}/data
log-dir	Directory for logging	${eai.home}/log
log	Configuration for logging	For more information see Log Section
trace-dir	Directory for log files	${eai.home}/log
locale	Language of GUI applications	en_US, de_DE, default \| system Notes on locales: The locale consists of two parts separated by an underscore. The first argument is the language code, a pair of lowercase letters that are conform to ISO-639. The second argument of the locale constructor is the country code. It consists of two uppercase letters and is conforms to ISO-3166. Note: Only the locales for en_US and de_DE are provided by default. When you specify default or system locale, the default locale for your system will be used (e.g. in a German Windows system the locale will be de_DE).
encoding	Encoding for XML files	UTF-8 Notes on encoding: Supported values are: US-ASCII, ISO-8859-1, UTF-8, and UTF-16 (or any other encoding stated on `http://docs.oracle.com/javase/8/docs/api/java/nio/charset/Charset.html`
appearance	Look and feel for GUI applications	java (default), system, windows, motif java: The Java Swing appearance system: appearance depending on the operating system (resolves to windows on Windows, and motif on Unix) windows: Windows appearance. May not be available on any other platforms but Windows. motif: Unix appearance. May not be available on any other platforms but Unix.

2.3 Controller Section

The controller is the kernel of the Enterprise Integration Platform. It starts up all necessary modules like connectors, Queues and Logger. Here you can define location and type of event logging. In addition, the temporary directory can be changed here:

<controller version="2.2.0">
    <!-- controller configuration -->
    <queue active="true"></queue>
    <polling-interval>10</polling-interval>
    <eci-trace>NONE</eci-trace>
    <admin-port>9876</admin-port>
    <feature persist-synchronous="false" queue-polling="false"/>
    <webserver active="true" port="8080" webapps="${eai.data}/webapps">
        <!-- host name for which the certificate was created -->
        <host-name></host-name>
        <!-- Security properties for a HTTPS connection -->
        <key-alias></key-alias>
        <keystore-password></keystore-password>
        <!-- Keystore file location (path with file name).
            e.g. ${eai.home}/wallet/private/eip/keystore.jks        -->
        <keystore-file></keystore-file> 
    </webserver>
 
<!-- common configuration -->
...
</controller>

Note:

The configuration values under the comment  (marked in gray) may be used in every application section, see "Common Section" on page 2-1.

Details of the XML tags:

Tag	Description	Values
queue	Configuration for queue	For more information see Queue Section
polling-interval	Time interval for polling the source connectors for new data to be transferred	10 (seconds)
eci-trace	Level for logging of ECI calls from Agile EDM Connector	ALL, DEBUG, TRACE, NONE Only the log level in log/level has to be set to SYS. The ECI trace is now configured separately. For Agile e6.0.2 and higher, the trace level INFO is also available (sequence: ALL, DEBUG, TRACE, INFO, NONE). For axalant2000sp3, the log level in log/level still has to be set to SYS.
admin-port	Port for the Administrator tool	9876
feature	Features for controller	Feature definitions (see below)
webserver	Web Server Configuration	Configuration (see below)

Details of the XML tag feature:

Tag	Description	Values
persist-synchronous	Defines to persist synchronous transfer steps	true, false
queue-polling	Defines if the polling on the queue is enabled. If disabled, the data will still be persisted, but will directly routed through the EIP; the queue will not be polled anymore.	true, false

Details of the XML tag webserver:

Tag	Description	Values
active	Defines if to start the internal web server.	true, false
port	Port on which the web server listens	8080
webapps	Directory for web applications and web services	${eai.data}/webapps

As the embedded Tomcat webserver in EIP runs only in HTTPS mode a certificate in a Java keystore must be installed for it. Therefore the following child XML tags of the webserver XML tag must be configured:

Tag Name	Description
host-name	This is the host name where the embedded Tomcat of EIP is running
key-alias	That is the alias of the private key created during the certificate request.
keystore-password	That is the password of the keystore created during the certificate request and which is used to secure the embedded Tomcat in EIP. Here the password must be inserted encrypted which can be done with the EIP encryption tool.
keystore-file	Path and file name of the Java keystore used to secure the embedded Tomcat. This keystore contains the certificate.

2.4 Log Section

The Integration Platform uses the Logging Tool LOG4J for recording the activities of its components (controller, mapping, queue and connectors). The <log> section(s) are sub-sections of the <controller> section, the <admin> section, the <cryptographer> section, and the <version> section, since all of them allow turning on logging.

Several <log> sub-sections can be configured, but only one of them can be activated ("active" attribute is "true"):

<log active="true">
     <class>com.eigner.commons.logging.Log4jLogger</class>
     <file>${eai.log}/eai.log</file>
     <level>INFO</level>     
<host>localhost</host>
     <port>4445</port>
     <types>console, file, socket</types>
</log>

Details of the XML tags:

Tag	Description	Values
class	Class which does the logging	com.eigner.commons.logging.Log4jLogger (or any other class which inherits from the interface com.eigner.commons.logging.Logger)
file	File used for logging if types includes file	${eai.log}/eai.log
level	Level for logging Notes on trace-level: The trace levels have the following order: ALL < SYS < DEBUG < TRACE < INFO < WARN < ERROR < FATAL < FORCE < OFF. When setting a level, all higher levels are reported, too. Examples: trace-level INFO: the levels INFO, WARN, ERROR, FATAL and FORCE are reported trace-level FATAL: the levels FATAL and FORCE are reported	ALL, SYS, DEBUG, TRACE, INFO, WARN, ERROR, FATAL, FORCE, OFF
host	Target-host for the trace-output via socket	localhost
port	Target-port for the Trace-output via socket	4445
types	Logging targets	console, file, socket Notes on trace-types: The trace types have to following meaning: console: logging messages are written to the terminal window where the application has been started from - file: logging messages are written to the file specified in the <file> element. - socket: logging messages are written to the host and port specified in <host> and <port>, e.g. to show the trace information in the Admin GUI.

2.5 Queue Section

The Message Queue is used to store the XML messages, which are routed through the Integration Platform, in a persistent way, i.e. in a database. The Oracle database is configured as queue database. The <queue> section(s) are sub-sections of the <controller> section and the <admin> section. Both need to access the database for storing and retrieving queue entries. It is recommended to keep the <queue> sections in <controller> and <admin> in sync.

The Oracle database needs to be configured first:

Prepare/create your database which you want to use for storing the queue entries.

We recommend using a separate Oracle schema for that purpose. Ideally, this database should be as "close" to the Integration Platform as possible in order to reduce delays caused by network traffic.
Adapt the configuration file eai_ini.xml in order to point to the new database.

Please make this change in the <controller> section as well as in the <admin> section!

Several <queue> sub-sections can be configured, but only one of them can be activated ("active" attribute is "true"):

<queue active="true">
     <type>oracle</type>
     <host>hostname</host>
     <port>1521</port>
     <user>scott</user>
     <password></password>
     <name>sid</name>
     <timeout>30</timeout>
     <interval>3</interval>
     <id>1</id>
</queue>

Details of the XML tags:

Tag	Description	Values
type	Type of message queue	oracle
port	Port number of queue database	e.g. 1521 for Oracle
host	Host where the database is running
user	Name of the database user
password	Password of the database user	DB user password encrypted by encryption tool
name	Name of the database	e.g. SID for Oracle
timeout	Timeout for starting controller queue	time in seconds
interval	Interval to poll message queue	time in seconds
id	Queue ID (optional for Administrator; will display only entries with queue ID if specified)	1 Note: If no value is specified, the default of 1 is used.

Oracle Real Application Cluster (RAC) Example:

<name>(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=[racnode1])(PORT=1521))(ADDRESS=(PROTOCOL=TCP)(HOST=[racnode2])(PORT=1521))(LOAD_BALANCE = yes)(CONNECT_DATA=(SERVER=DEDICATED)(SERVICE_NAME=[sid])))</name>

The connection string for RAC configuration could be taken from an already existing tnsnames.ora that is properly set up for RAC (e.g. from an existing Oracle client installation).

RAC configuration example in tnsnames.ora:

KHERACW.ORACLE.COM =
    (ADDRESS = (PROTOCOL = TCP)(HOST = example.oracle.com)(PORT = 1521))
    (LOAD_BALANCE = on)
    (FAILOVER = on)
    (CONNECT_DATA =
      (SERVER = DEDICATED)
      (SERVICE_NAME = rac.oracle.com)
      (FAILOVER_MODE =
        (TYPE = select)
        (METHOD = basic)
        (RETRIES = 10)
      )
    )
  )

Note:

In order to prove that your configuration was successful, please run the test tool (test.cmd or test.sh), which will also check if it could connect to the database, and if the tables were created correctly. If the test tool terminates with no error message, then the configuration is completed.

2.6 Notification Section

The Notification Service can be used for sending out notifications in case of technical exceptions in the system. The Controller can be configured to point to the notification service.

<notification name="emergency" subject="Emergency notification!" sender="eip@foo.com">
     
     <!--Notification via notifier-->
     <notifier type="mail" name="admin@foo.com">
       <mail-host>mail-server@domain</mail-host>
       <mail-port>25</mail-port>
       <mail-security>STARTTLS</mail-security>
       <smtp-user>mail-account@domain</smtp-user>
       <smtp-pwd>XXX</smtp-pwd>
     </notifier>

     <!--Notification via mail connector-->
     <!-- <notifier type="connector" name="mail"/> -->

</notification>

Details of the XML tags:

Tag	Description	Values	Sub_structure	Values of Sub_structure
notification	Defines how a system notification should be sent out: subject sender	Defines how a system notification should be sent out: Unique name of the notification element. The subject Sender of the notification	Notifier
notifier	Defines the type of notifier type name (receiver) If you select "type=mail", then an email is sent out directly to the receiver as defined in "name". If you select "type=connector", than the SMTP Mail Connector is used as defined in the "name" attribute.	"mail" or "connector" mail: mail address -connector: name of mail connector	Mandatory Parametrs: <mail-host> <mail-port> <smtp-user> <smtp-pwd> <mail-security>	Mail host name (e.g. mailserver@domain) Mail port (any number) The smtp user name for the outgoing mail server account The smtp password for the outgoing mail server Needs to be encrypted The smtp password for the outgoing mail server

Tag

Description

Values

Sub_structure

Values of Sub_structure

notification

Defines how a system notification should be sent out:

subject
sender

Defines how a system notification should be sent out:

Unique name of the notification element.
The subject
Sender of the notification

Notifier

notifier

Defines the type of notifier

type
name (receiver)

If you select "type=mail", then an email is sent out directly to the receiver as defined in "name".

If you select "type=connector", than the SMTP Mail Connector is used as defined in the "name" attribute.

"mail" or "connector"

mail: mail address

-connector: name of mail connector

Mandatory Parametrs:

<mail-host>
<mail-port>
<smtp-user>
<smtp-pwd>
<mail-security>

Mail host name (e.g. mailserver@domain)
Mail port (any number)
The smtp user name for the outgoing mail server account
The smtp password for the outgoing mail server

Needs to be encrypted
The smtp password for the outgoing mail server

2.7 Connector Section

The connector is the interface to the application, to which the Enterprise Integration Platform should connect. Theoretically, you can use multiple connector processes, connecting to the same system. Each connector process needs a unique connector name, which is the attribute <name> of the connector tag. The only mandatory attributes defined by the Enterprise Integration Platform are class and active. All other additional tags depend on the requirements/functionality of the specific connector. Therefore, please refer to the connector-specific documentation.

The <reconnect> element allows you to configure the reconnect option of that specific connector in case the connector loses its connection to the respective system.

<connector name="example" version="2.2.0" active="false" class="com.eigner.eai.connector.ExampleConnector">
     <reconnect active="false" count="3" delay="5" notification="emergency"/>     <feature dynamic-connect="false"/>
     <connection name="default" active="true">
           …
     </connection>
     <bor location="${eai.conf}/bor_example.xml"/>
</connector>

Note:

The details for <bor> also apply to the Synchronous connector sections. All other details do not necessarily need to be used by a synchronous connector. Please refer to the paragraphs that are dedicated to the special connector.

Details of the XML tag connector:

Attribute	Description	Values
name	Unique connector name	connector name
version	Version of the connector	connector version
class	Java class name of the connector	connector class name
active	Flag if to start the connector	true, false

Details of the XML tag reconnect:

Attribute	Description	Values
active	Activate or deactivate the reconnect option	true, false
count	Number of attempts to reconnect (by calling the start operation of the connector), otherwise, the connector will be deactivated	number
delay	Delay between the attempts to reconnect	seconds
notification	Reference to notification configuration which should be used	"name" attribute of the "notification" tag

Details of the XML tag feature:

Attribute	Description	Values
dynamic-connect	Flag if connector should use the dynamic connect feature	true, false

Details of the XML tag connection:

Attribute	Description	Values
name	Name of connection
active	Flag if active	Several <connection> sub-sections can be configured, but only one of them can be activated ("active" attribute is "true").

Details of the XML tag bor:

Attribute	Description	Values
location	Location of the BOR (Business Object Repository) file	Must point to a valid file (placeholders are allowed) or the content of the BOR must be sub-elements.

Note:

For further information about the specific settings of the different connectors, please refer to the chapters of the specific connectors, e.g. Agile EDM Connector.

2.8 Pipe Section

The pipe provides the information, where the mapping file can be found. Right now, only XSL files can be used for mapping. The name of the pipe will be referred to in the Workflow Section.

<pipe name="plm-erp">
     <path>${eai.conf}/plm_erp.xsl</path>
</pipe>

Details of the XML tags:

Tag	Description	Values
path	Path to the transformation file; instead of referring to an absolute path (e.g. /tmp/) you could also use the placeholder {eai.conf}, which points to the configuration directory of the Integration Platform	XSL file

2.8.1 Modifying the Mapping File

As mentioned before, XSL files are used for mapping purposes. Since the connectors create and read XML data (i.e. the message XDO), converting the XDO to a specific format will be done by the XSL transformation engine XALAN.

Note:

Please use standard literature for more information on using standard XSL.

The names of the XSL mapping files, which are used by the Enterprise Integration Platform, are provided in the eai_ini.xml configuration file as described in the previous chapter.

2.9 Workflow Section

The workflow section finally puts all pieces above together and defines which connectors and pipes should be used. The workflow can be activated with the tag active. The tags source, target and pipe refer to the names of these tags as described in the Connector and Pipe Section.

<workflow name="erp" active="true" type="asynchronous">
     <source>plm</source>
     <target>erp</target>
     <request-pipe>plm-erp</request-pipe>
     <response-pipe>erp-plm</response-pipe>
</workflow>

Note:

The tags <pipe> and <request-pipe>/<response-pipe> should not be used together! Either use <pipe> for mapping the request only or use a <request-pipe>/<response-pipe> combination for mapping both, request and response.

Details of the XML tags:

Tag/Attributes	Description	Values
active	Flag if workflow is to be used	true, false
type	defines whether this is a synchronous process or asynchronous process; this will normally be a synchronous process if the source connector is a synchronous connector	synchronous, asynchronous
source	Source connector name	name of connector
target	Target connector name	name of connector
pipe	Pipe (transformation) for request	name of pipe
request-pipe	Pipe (transformation) for request, if <response-pipe> is also used	name of pipe
response-pipe	Pipe (transformation) for response	name of pipe

Note:

If there are two or more workflow definitions with the same source connector name active, only the first one (determined by the order in the eai_ini.xml file) will be used. If you need to have one source connector that should feed more than one target connector, Site Management needs to be used (see Configuration inside Agile EDM).

2.10 Admin Section

The Administration tool is intended to be used for the administration of the Enterprise Integration Platform. It allows displaying the content of the queue and to output the trace log.

<admin version="2.2.0">
     <!-- admin configuration -->
     <queueactive="true">
           …
     </queue>
     <remote-logger-port>4445</remote-logger-port>
     <eip-host>localhost</eip-host>
     <eip-port>9876</eip-port>
     <!-- common configuration -->
     …
</admin>

Note:

The configuration values under the comment  (marked in gray) may be used in every application section, see Common Section.

Details of the XML tags:

Tag	Description	Values
remote-logger-host	Host name from which to receive logging messages	localhost
remote-logger-port	Port number from which to receive logging messages	4445
eip-host	Name of the eip host (where the Integration Platform process is running)	localhost
eip-port	Port number of Integration Platform (for Admin)	9876

2.11 Cryptographer Section

The Cryptographer tool is intended to be used for the administration of the Enterprise Integration Platform. It allows encrypting passwords, which are used by the connectors for login.

<cryptographer version="2.2.0">
     <!-- cryptographer configuration -->
     <!-- common configuration -->
     …
</cryptographer>

Note:

The configuration values under the comment  (marked in gray) may be used in every application section, see Common Section.

There is also a command line tool (encrypt) available. For further reference, please see "Encrypt Tool" on page 10-2.