Configuring OBE

Before OBE can be deployed, there are various aspects which must be configured. This is done after the source or binary distribution has been installed on disk and prepared. We shall refer to the staging area as OBE_HOME - this is the location where the binary distribution is installed, or the $OBE_DEV_HOME/build/staging location as created by the build system.

Configuring JAXP

OBE uses JAXP for most XML manipulation and provides the Apache Xerces and Xalan libraries for this purpose. However, most application servers also provide these two libraries but quite possibly different versions thereof. Unfortunately, although the Xerces DOM implementation is serializable the classes do not appear to have a stable serialVersionUID, which makes serialized DOM instances non-portable between versions. Now, process relevant data can contain DOM-type values, which OBE stores as serialized objects if the DOM object is serializable. It is important that OBE client and server processes use the same Xerces version as each other to ensure that serialized DOM objects returned by remote API calls can be deserialized by the client and vice-versa.

OBE-1.0 provides Xerces-2.7.1, to match the version supplied by JBoss-4.0.4.GA. If you are using a different version of JBoss or a different application server altogether, you must ensure that $OBE_HOME/lib contains the same version of Xerces as supplied by the application server.

Configure Application Server

Configure the application server to ensure that the resources required by OBE will be available. The J2EE resources required include:

Configuring JBoss

OBE provides some preconfigured resources for use with JBoss, under $OBE_HOME/j2ee/jboss. The conf and deploy directories can be copied to the ${as.dir}/server/default directory - you will need to rename/edit the *-ds.xml data source definition file in the conf directory to suit your database type and connection properties.  The 'default' JBoss server configuration should be adequate for most purposes.  Do not try to use the 'minimal' server configuration - it is not J2EE compliant and does not provide all the J2EE container functionality required by OBE.

Install the JDBC driver for your database by copying the appropriate JAR files into the ${as.dir}/server/default/lib directory.

Note that OBE provides a modified version of the Castor XML library that fixes certain critical bugs, so it is necessary either to delete the one that comes with JBoss-3.2.x in ${jboss.home}/server/default/deploy/snmp-adaptor.sar, or to replace it with the OBE version (castor-0.9.9-xml-patched.jar ) if you wish to use the JBoss SNMP adaptor. This incompatibility is a consequence of the JBoss UnifiedClassLoader3 merging the classpaths of the various J2EE applications.

Configuring WebLogic Server

OBE provides some sample configuration files for  WebLogic Server under the $OBE_HOME/j2ee/wls* directories.

Configuring the database

To configure the database, perform the following steps using settings to match your custom build properties:

Configuring the OBE Clients and Server

OBE Configuration Files

OBE needs a number of configuration files in order to start up in anything other than 'vanilla default' mode. These configuration files can either be bundled in the obeconfig.jar on the classpath ($OBE_HOME/lib/config.jar by default or inside $OBE_HOME/j2ee/lib/obeserver.ear) or they can reside in a directory on the hard disk, or both. Loose files and settings from the configuration directory override their counterparts in the jar. In a configuration jar the files are located in the META-INF/services directory as recommended by the Sun JAR Specification. On disk the default location for configuration files is the current directory but this is typically overridden by setting the system property obe.config.dir.

obe.properties

This Java properties file is packaged by default at  jar:obeconfig.jar!META-INF/services/obe.properties. It contains a number of important settings, which can be overridden by any of the following techniques:
For full details on these properties please refer to the Javadocs for CommonConfig, ClientConfig and ServerConfig. The default values shown below suit JBoss-4.x and do not have to be specified in obe.properties: just supply values for the ones you need to override.

Property Type Default / Allowable Value(s) Meaning
Properties accessed via CommonConfig
obe.client.credentials string password The credentials to supply when connecting to the server.
obe.client.principal string system The principal to supply when the connecting to the server.
obe.client.protocol string local | j2ee-local | rmi | xmlrpc The protocol to use when connecting to the server.
obe.xpdl.date.format string yyyy-MM-dd'T'HH:mm:ssZ The default date format.
obe.xpdl.duration.unit string D (day) The default duration unit.
Properties accessed through ClientConfig
obe.client.java.naming.factory.initial string Overrides the default JNDI initial context factory specified by ${java.naming.factory.initial}.
obe.client.jaas.callback.handler string org.obe.client.api.base.
OBECallbackHandler		 The name of the JAAS callback handler class to instantiate for login.
obe.client.jaas.config string other The name of the JAAS login configuration entry to use.
obe.client.stdio boolean false Whether to use standard I/O for tool agent interactions with the user.
obe.jaas.caller.principal.class string The name of the java.security.Principal class which indicates the primary authenticated identity.
obe.jms.queue.connection.factory string ConnectionFactory The JNDI name of the javax.jms.QueueConnectionFactory to use (JMS client only).
obe.jms.topic.connection.factory string ConnectionFactory The JNDI name of the javax.jms.TopicConnectionFactory to use (JMS client only).
obe.server.host URL jnp://localhost:1099 The URL of the server.
Properties accessed through ServerConfig
obe.audit.nontransactional boolean false Whether to log audit records non-transactionally.
obe.domain string OBE The value of the 'domain' property in audit records.
obe.node string dns-host-name The value of the 'node' property in audit records.
obe.mail.session string The JNDI name of the mail session to use.
obe.reuse.workitems boolean true Whether to re-use existing work items for cyclic workflows.
obe.script string text/x-xpath The default scripting language to use when evaluating expressions.
obe.events.use.api boolean false Whether to route inbound events through the local client API.
obe.events.key.based.subscriptions boolean true Whether to support key-based event subscriptions.
obe.events.max.tardiness int 300000 Maximum acceptable delay for timed events.
obe.init.use.servlet boolean false Whether to use the OBE initialization servlet (J2EE deployments only).
obe.debug.verbose boolean false Enables extremely verbose debug output.
obe.async.threadpool.size int 20 The size of the thread pool used to service async execution requests (BasicAsyncManager only).
obe.directory.poll.interval int 5000 The polling interval for the ${obe.config.dir}/processes directory.
Properties required by JavaMail
mail.debug boolean false The initial debug mode.
mail.from string obe@localhost The return email address for emails sent by OBE.
mail.mime.address.strict boolean true Whether to perform strict MIME header parsing.
mail.host string localhost The default host name of the mail server for both Stores and Transports.
mail.store.protocol string pop3 Specifies the default message access protocol.
mail.transport.protocol string smtp Specifies the default mail transport protocol.
mail.user string obe The default user name to use when connecting to the mail server.
mail.protocol.class string Specifies the fully qualified class name of the provider for the specified protocol.
mail.protocol.host string ${mail.host} The host name of the mail server for the specified protocol.
mail.protocol.port int The port number of the mail server for the specified protocol.
mail.protocol.user string ${mail.user} The user name to use when connecting to mail servers using the specified protocol.

ServiceManager.properties

This Java properties file specifies implementation class names for the various services which run under the control of the Service Manager. It is not necessary to modify this file unless you are providing a custom service implementation.

Basic Service Implementations

The keys and default basic service implementations defined in jar:$OBE_HOME/lib/obeconfig.jar!META-INF/services/obe.properties are as follows:

Property Default Implementation Service
obe.applicationEventBroker org.obe.event.BasicApplicationEventBroker Application Event Broker
obe.asyncManager org.obe.engine.async.BasicAsyncManager Async Execution Manager
obe.assignmentStrategyFactory org.obe.runtime.strategy.BasicAssignmentStrategyFactory Assignment Strategy Factory
obe.calendarFactory org.obe.engine.calendar.BasicCalendarFactory Calendar Factory
obe.completionStrategyFactory org.obe.runtime.strategy.BasicCompletionStrategyFactory Completion Strategy Factory
obe.dataConverter org.obe.engine.util.BasicDataConverter Data Converter
obe.evaluatorFactory org.obe.runtime.evaluator.BasicEvaluatorFactory Evaluator Factory
obe.functionFactory org.obe.runtime.evaluator.BasicFunctionFactory Function Factory
obe.instanceRepository org.obe.engine.persistence.memory.BasicInstanceRepository Instance Repository
obe.realm org.obe.runtime.participant.BasicRealm Security Realm
obe.parserFactory org.obe.spi.service.XPDLParserFactory XPDL Parser Factory
obe.toolAgentFactory org.obe.runtime.tool.BasicToolFactory Tool Agent Factory
obe.processRepository org.obe.engine.persistence.memory.BasicProcessRepository Process Repository
obe.workflowEventBroker org.obe.event.BasicWorkflowEventBroker Workflow Event Broker
obe.resourceRepository org.obe.engine.repository.BasicXMLRepository Resource Repository

J2EE Service Implementations

The keys and J2EE service implementations defined in the obeconfig.jar packaged inside $OBE_HOME/j2ee/lib/obeserver.ear are as follows:

Property J2EE implementation Service
obe.applicationEventBroker org.obe.server.j2ee.service.EJBApplicationEventBroker Application Event Broker
obe.asyncManager org.obe.server.j2ee.service.JMSAsyncManager Async Manager
obe.instanceRepository org.obe.server.j2ee.repository.EJBInstanceRepository Instance Repository
obe.processRepository org.obe.server.j2ee.repository.EJBProcessRepository Process Repository
obe.resourceRepository org.obe.server.j2ee.repository.WebDAVResourceRepository Resource Repository

log4j.properties

OBE uses Jakarta Commons Logging for managing logging and auditing output; Commons Logging in turn uses Log4J by default. OBE Server supplies a custom Log4J configuration file in order to ensure that audit records get logged correctly, and the J2EE server configures a transactional appender programmatically, to avoid the ClassCastExceptions which happen if this is done declaratively in the configuration file.

log4j-client.properties

The Log4J configuration for OBE clients.

castor-map.xml

The basic service implementations store their configurations in XML files and use Castor to read them into in-memory Java objects. The castor-map.xml file defines the mapping between the XML elements and attributes and the corresponding JavaBean properties. It should not normally be necessary to edit this file unless you are extending OBE by adding new tool agent types, for example.

Service Configuration Files

Many of the service implementations have their own XML configuration files, which are also stored in the OBE configuration directory or under jar:obeconfig.jar!META-INF/services/