Understanding BW engine properties

Note to the reader:

For many property declarations discussed in this article, we followed the property with parentheses that enclose a comment for explanation. If you choose to add a property with a comment within parentheses to your property file, you must remove the parentheses and advance each comment with a comment tag in order to prevent unnecessary syntax errors.

Inroduction
The BW engine uses two flavours of properties:
1. java.property.<propname> -- which is loaded by the wrapper(i.e bwengine.exe) 2. <propname> -- which is picked by the engine

The wrapper loads its properties from a file specified by --propFile while the engine loads its properties from a file specified by -p. When running the engine in debug mode (i.e. through Designer), the properties can be put in a file, such as "properties.cfg", and loaded when the engine is launched as -p properties.cfg. When you launch the tester engine, go to the Advanced Test Settings tab and specify the properties file as shown below.

By default, the tester engine in Designer loads the properties file(properties.cfg) to the <TIBCO_HOME>/designer/5.x directory. Some properties of the form 'java.property.*' needs to be specified in the designer.tra file as they are loaded by the wrapper, in which case Designer must be restarted for the properties to take effect. In contrast, any changes made to the engine properties specified with the -p flag should take effect simply by restarting the tester.

Generated by Clearspace on 2011-01-25-06:00 1

Understanding BW engine properties

When running the engine from the command line, all properties can be placed in one file (e.g. myengine.tra) using the template "bwengine.tra". In the .tra file, you must edit the property tibco.env.APP_ARGS to point to itself. For example, if "myengine.tra" is in C:/temp, then the property would be tibco.env.APP_ARGS=-p C:/temp/myengine.tra Start the engine as >bwengine --propFile myengine.tra <repo> to load the engine with the properties declared in "myengine.tra". If deploying the engine to a domain, the properties set in the Admin GUI under the process archive should be added to the deployed engine's .tra file. To manage custom properties in the Admin GUI, you must add them to the "bwnegine.xml" file under <TIBCO_HOME>/bw/5.x/lib/com/tibco/deployment before creating the application archive (EAR) file. For example, <property> <name>JDBC Idle timeout</name> <option>java.property.bw.engine.dbConnection.idleTimeout</option> <default>5</default> <description>controls JDBC idle timeout in minutes</description> </property> [Note: Properties set in the "bwengine.xml" file will be visible in the Admin GUI for modification.]

Tracing, Logging and Debugging

Log File and Directory Properties
Engine.Log.Dir=logs (directory to which log files are written)

Generated by Clearspace on 2011-01-25-06:00 2

Understanding BW engine properties

Engine.Dir=./testDir (alternate method to specify the log directory) Engine.Log.MaxSize=20480000 (setting the maximum size for the log file in bytes) Engine.Log.MaxNum=5 (specifying the maximum number of log files -- a rollover feature) Roles Info Debug Warn Error userrole (used in 'Write to log' activity) Sinks Term (terminal or console) Log #log file Publish #RV sink Tracing Trace.<role>.Term Trace.<role>.Log Trace.<role>.Publish where role = Info,Debug,Warn,Error,Role.<userRole> (note how a user defined role is specified as "Role.<userRole>") Trace.<role>.Publish.Subject Trace.<role>.Publish.Service

Generated by Clearspace on 2011-01-25-06:00 3

Understanding BW engine properties

Trace.<role>.Publish.Daemon Trace.<role>.Publish.Network Enabling/Disabling the Roles: Trace.<role>.* (enables/disables the specified system role) Trace.Role.<userRole> (enables/disables specified user-defined role) Trace.Role.* (enables/disables all user-defined roles) Tracing for Different Components of BW: Trace.Startup (tracing during engine startup) Trace.Engine (tracing when job enters process flow) Trace.JC.* (tracing for all process starters) Trace.JC.<ProcessFlowName> (tracing for a specific process starter) Trace.JC.ProcessFlows/MyPr1.process=true (example) Trace.Task.* (tracing for all tasks) Trace.Task.<ProcessFlowName>.* (variation) Trace.Task.ProcessFlows/MyPr1.process.*=true (example) Trace.Task.<ProcessFlowName>.<ActivityName> (variation) Trace.Task.ProcessFlows/MyPr1.process.RVPub=true Example Trace.Task.ProcessFlows/MyPr1.process.<GroupName>/<ActivityName>=true [Note: when the activity is inside a group, the above example will not work.] Specifying Rolling Log Files for UserRole: Trace.Role.<userRole>.Log.Dir (location for the set of rolling log files)

Generated by Clearspace on 2011-01-25-06:00 4

Understanding BW engine properties

Trace.Role.<userRole>.Log.File (file name for the log files) Trace.Role.<userRole>.Log.MaxSize (sets the maximum size of a log file) Trace.Role.<userRole>.Log.Maximum (specifies the maximum number of log files to create)

All Activities
bw.engine.showInput (available from BW 5.3 onwards) bw.engine.showOutput (available from BW 5.3 onwards)

SOAP Tracing
java.property.com.tibco.plugin.soap.trace.inbound=true java.property.com.tibco.plugin.soap.trace.outbound=true java.property.com.tibco.plugin.soap.trace.filename=C:/files/support/soapLogging/ soap.txt java.property.com.tibco.plugin.soap.trace.pretty=true java.property.com.tibco.plugin.soap.trace.stdout=true

WS-Security Tracing
log4j.logger.com.tibco.spin=DEBUG, tibco_bw_log log4j.logger.com.tibco.security.tibcryptx.wss=DEBUG, tibco_bw_log (enables the above in log4j.properties file in conjunction with t he soap tracing properties above)

RV Advisories
Trace.RV.Advisory.Error=true (error advisories are logged by default) Trace.RV.Advisory.Warn=false Trace.RV.Advisory.Info=false

Generated by Clearspace on 2011-01-25-06:00 5

Understanding BW engine properties

Engine Properties
Worker Threads
The default number of worker threads is 8. On a multi-CPU machine, the number of threads can be increased. The user should empirically determine the optimal thread value for their deployment as too many threads can cause resource contention. The recommended value is 8 threads per CPU: Engine.ThreadCount=8

StepCount Property
The StepCount property controls the maximum number of execution steps (unless inside a transaction) for a job before an engine thread switch occurs. The default value of this parameter is 20. Frequent thread switching can cause engine performance degradation. But when a process instance keeps the tread too long, this may cause less concurrency for executing process instances and hence inefficient use of CPU.Therefore, it is difficult to determine the correct value for this property. The default value is sufficient for most situations. But if your process definitions contain a large number of activities (and especially if they contain a large number of activities in iteration loops), you may benefit from setting this property to a higher value. Engine.StepCount=20

Flow Control
Those are flow control-related properties. Detailed explanation of those properties can be found in the TIBCO Admin Users Guide, Chapter 8 (Setting deployment options), under the section titled "Changing TIBCOBW process configuration properties". MaxJobs.ProcessFlows/PrRVSubscriber.process=5 (0 by default) FlowLimit.ProcessFlows/PrRVSubscriber.process=10 (0 by default) ActivationLimit.ProcessFlows/PrRVSubscriber.process=false ("true" by default) ActivationLimit.ProcessFlows/Pr\ RVSubscriber.process=false ("true by default)

Generated by Clearspace on 2011-01-25-06:00 6

Understanding BW engine properties

Memory Saving Mode - BW Garbage Collection (not Java)

Memory saving mode can reduce memory usage by actively running process instances as well as potentially improving the performance of checkpoints. Note that is a BW Process Variable garbage collection and not the Java garbage collection. EnableMemorySavingMode.*=true (for all process flow) EnableMemorySavingMode.<processName>=true (for specific process flow) Both properties above are "false" by default

JobId Block Size

When an engine starts up, it reads a job id block size from the DataManager. Each newly created job is assigned an id from this block. By default, the value of the JobIdBlockSize is 1000: Engine.JobIdBlockSize=1000

Engine Termination
If you wish to terminate the engine when the "Process initialization failed" error is encountered during engine startup, set the following property to "true": Engine.ShutdownOnStartupError=true The default of the property above is "false".

FT-Related Properties
Engine.FT.UseFT=true Engine.FT.Weight=100 Engine.FT.HeartbeatInterval=3000 Engine.FT.ActivationDelay=6000 Engine.FT.ActivationInterval=10000

Generated by Clearspace on 2011-01-25-06:00 7

Understanding BW engine properties

Engine.FT.GroupName=RUDRA.xyz Engine.FT.Subject=RUDRA.Test.Process (optional, if not used, subject=FT.<GroupName>) If you wish to perform FT-level debugging, you can listen on the following subject for FT heartbeats: tibrvlisten "_RVFT.ACTIVE_HB.<FT subject name>" FT transport configuration: To use non-default values for FT transport, set the following properties: Bus.Default.Service=6532 Bus.Default.Daemon=tcp:6532 Bus.Default.Network=; In some situations where a database is used as the data manager for process engines, a unique constraint violation is thrown. If such an error is encountered, set the property below to "false". Engine.StandAlone By default, the property above has a value of "true".

DupKey
The following three process engine properties control duplicate key detection:
bw.engine.dupKey.enabled

This property controls whether duplicate detection is performed. By default, this property is set to "true".
bw.engine.dupKey.timeout.minutes

This property specifies how long (in minutes) to keep stored duplicateKey values. The default value of this property is 30 minutes. The value "-1" indicates that the duplicateKey values are deleted when as soon as the job is completed. The value "0" forces the storage of duplicateKey values indefinitely. Positive integers greater than 0 determine the the number of minutes to keep stored duplicateKeys.

Generated by Clearspace on 2011-01-25-06:00 8

Understanding BW engine properties

bw.engine.dupKey.pollPeriod.minutes

This property specifies the number of minutes to wait before polling for expired duplicateKey values.

DataManager/Checkpoint Database Properties

Engine.UseDatabase=true (the default value is "false", implying file-based data manager) File-based DataManager - working directory: If using file-based data manager, you can specify the name/location using the following property: DataManager.Directory=<dir> (absolute or relative path) The default value for this property is 'working' An alternate (and recommended) way to specify the location of the data manager directory can be accomplished with the following property: Engine.Dir=C:/MyProject Note that when using the Engine.Dir property, it will always create a directory named 'working' under the specified location. The 'log' directory is also created under the same location. DB-based DataManager: There are two ways to specify the database connectivity details:
The simplest way is to use a 'JDBC Connection' resource from the BW project:

Engine.Database.Configuration=/SharedConfig/JDBCOra
An alternate way is to use the following set of properties:

Engine.Database.Location=jdbc:oracle:thin:@jones:1521:icjones Engine.Database.Driver=oracle.jdbc.driver.OracleDriver Engine.Database.User=oratest Engine.Database.Password=oratest

Generated by Clearspace on 2011-01-25-06:00 9

Understanding BW engine properties

Engine.Database.MaxConnections=10 DB DataManager table names: The property below sets the Tablename prefix. Database.Tablename.Prefix=tab Setting the Tablename prefix is more than sufficient. However, the following properties are optional: Database.DataManager.Internal.Table=tab_internal Database.DataManager.Job.Table=tab_job Database.DataManager.Job.DupTable=tab_duplicates Database.WaitNotify.Wait.Table=tab_wait Database.WaitNotify.Notify.Table=tab_notify

Hawk
Enabling/Disabling Hawk
Hawk.Enabled=true true - enables both TIBCO Hawk and Engine Command activity usage. false - disables both TIBCO Hawk and Engine Command activity usage. local - only enables Engine Command activity (TIBCO Hawk will be disabled).

Hawk Transport
Hawk.Service=7474 (default udp port is 7474) Hawk.Daemon=tcp:7474 (default tcp port is 7474) Hawk.Network=; (default network value is ;)

Generated by Clearspace on 2011-01-25-06:00 10

Understanding BW engine properties

Hawk Display Name

Hawk.AMI.DisplayName=Test.bwengine #default name is com.tibco.pe.<engineName>

Performance Statistics
Set the following property to collect statistics for various activities in a process flow at runtime: Instrumentation.*=true Instrumentation.<processName>=true (for a specific process flow) [Note: be advised that setting the instrumentation property can cause performance degradation and memory overhead.] When you enable instrumentation, it allows you to execute the following Hawk methods:
Collection of activity statistics using GetActivity micro-agent method Calls to OnProcessActivity and OnProcessStatusChanged micro-agent methods

The instrumentation property can be set at runtime by calling the TIBCO Hawk setInstrumentProperties method. The property value specified in a call to setInsrumentProperties will take effect immediately.

Other (Non-activity) Specific Properties

Memory
java.extended.properties -Xms768m -Xmx768m -verbose:gc

Enable Remote Debugging from IntelliJ and Other IDEs

java.extended.properties -Xdebug -Xnoagent -Djava.compiler=NONE Example: -Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=5005

Generated by Clearspace on 2011-01-25-06:00 11

Understanding BW engine properties

Global Variable Substitution

tibco.clientVar.<global var>=test tibco.clientVar.mySubject=test.xyz

Repository Connection - Remote/Local

tibco.repourl=C\:/tibco/tra/domain/amxdom/datafiles/RVCMQtester_root tibco.deployment=RVCMQtester tibco.domain=Test tibco.username=admin

designer.tra prop to point to prop file

java.property.testEngine.User.Args -p c:\\tibco\\properties.cfg

Active Enterprise Adapter Activities

Publish to Adapter Activity
Timeout for 'Publish to Adapter' activity when used in a request/reply mode: bw.plugin.ae.publishReqRepTimeout (specified in milliseconds)

FTP Activities
If you wish to strip the line feed character (\n) when executing FTP PUT command, you must set the following property to "true": bw.plugin.ftp.stripLineFeedInPut=false (the default setting is "false")

File activities
When a file is saved on a Windows platform using UTF-8 encoding, the Windows OS adds a Byte Order Mark (BOM) to the beginning of the file. This BOM is not necessary for UTF-8,

Generated by Clearspace on 2011-01-25-06:00 12

Understanding BW engine properties

but it is valid nonetheless. Prior to release 2.0.6, the File Reader activitys output will include the BOM at the beginning of the data read from the file. The property below will strip the BOM from the file when encountered. Its default value is "true". Thus, if you wish to retain the BOM, you set this property to "false" java.property.DiscardUTF8BOM=false

General activities
Wait-Notify
By default, the Wait-Notify activity will use the following settings for its transports: Bus.Default.Service Bus.Default.Network Bus.Default.Daemon These are the same settings used by other components of the engine, including FT, RV sink, etc. If you wish to give explicit settings for Wait-Notify transports, use these settings instead: WaitNotify.Service WaitNotify.Network WaitNotify.Daemon

External Command
Use the following property to set the thread pool for the External Command activity: CmdExec.ThreadCount=5

Timer
Before BW release 5.2.0, the Timer process starter used the Java convention (0-11) for the number of months in its output; however, the expected convention for the number of months

Generated by Clearspace on 2011-01-25-06:00 13

Understanding BW engine properties

is 1-12. In release 5.2.0, the month is returned as a number between 1 and 12. If you wish to maintain backward compatibility, set the following property to "true": bw.plugin.timer.useJavaMonth

HTTP activities
Threads for Incoming HTTP Requests
The property below sets them minimum and maximum number of threads for incoming HTTP requests. By default, the minimum and maximum thread value is set to 10 and 75, respectively. bw.plugin.http.server.minProcessors=10 bw.plugin.http.server.maxProcessors=150 bw.plugin.http.server.acceptCount=10

Connection Pooling
The following properties are used to set connection pooling and configure the number of connections in the pool: bw.plugin.http.client.usePersistentConnectionManager (flag to turn on connection pooling) bw.plugin.http.client.maxConnectionsPerHost (maximum connection to each remote host with a default of 20) bw.plugin.http.client.maxTotalConnections (maximum connection for all HTTP server with a default of 200) bw.plugin.http.client.checkForStaleConnections (check for stale connection in the pool)

Request-Response Thread Pool

Each HTTP request is executed in a separate thread belonging to a thread pool associated with the activity. The number of threads in the pool determines the maximum number of concurrent requests a HTTP request/response activity can execute. The following property sets the number of threads in the pool:

Generated by Clearspace on 2011-01-25-06:00 14

Understanding BW engine properties

bw.plugin.http.client.ResponseThreadPool The default value of this property is 10.

Default Host
Set the following property to specify the name of the default host that must be used when the machine has multiple domains or IP addresses, noting that it takes either the host name or its IP address as its value: bw.plugin.http.server.defaultHost

Encode QueryString
As of BW release 5.2.0, the QueryString input element of the Send HTTP Request activity is not automatically URL-encoded. This was not the case in prior releases. Therefore, this change may cause backward compatibility issues, if you rely on the activity to perform the URL-encoding of the QueryString. If set to "true", the following property will revert to the behavior of previous BW releases. bw.plugin.http.client.urlEncodeQueryString

HTTPS/Security
This property defers client authentication and outputs the clients security context when the client connects to the server using HTTPS: bw.plugin.https.server.deferClientAuthentication To specify the "entrust" security or "JSSE" vendor, set the following properties: java.property.TIBCO_SECURITY_VENDOR=entrust61 java.property.TIBCO_SECURITY_VENDOR=j2se

Idle Connection Timeout

By default, connections in a pool will close after idle timeout period of 5 minutes. If you wish to set a different idle timeout (in minutes), use this property: java.property.bw.engine.dbConnection.idleTimeout

Generated by Clearspace on 2011-01-25-06:00 15

Understanding BW engine properties

Login Timeout
The property below refers to time-to-wait (in seconds) for a successful database connection. Only JDBC drivers that support connection timeouts can use this property; otherwise, it is ignored. The value of this property overrides any value set for connection timeouts in the "Configuration" tab of the JDBC Connection resource. Config.JDBC.Connection.SetLoginTimeout

Setting Optional Parameters

Optional parameters for a call procedure activity have never been supported, but was allowed in BW releases prior to 5.2. Thus, when migrating a project from a pre-5.2 release, there will be validation errors for any unspecified input elements for stored procedure parameters. These migrated projects cannot be executed until such errors are resolved. If you wish to migrate a project without resolving this issue, you must set the following property to "true" Config.JDBC.CallProcedure.InputOptional

Set Output Nil

Prior to BW release 5.1.2, if a value returned from a database table was null, the output element corresponding to that table value was not included into the output schema for a JDBC Call Procedure activity if the output element was optional. The element will be placed into the output schema with "xsi:nil = true" to indicate the element is null. In order to achieve the behavior of previous Pre-5.1.2 releases, you must set the property below to "false". Config.JDBC.CallProcedure.OutputUseNil

Test Statement
When a SQL error occurs during statement execution, BW will execute a test SQL statement to determine if the error is caused by a bad connection. If the error is due to a bad connection, the statement then can be re-executed using a different connection in the connection pool.The SQL test statement is unmodifiable for Oracle, Sybase, SQL Server, or DB2 databases. However, the property below should allow you to specify SQL test statement for databases other than those cited above. All you need to do is specify the database name and set the value of the property to a valid SQL statement. Engine.Database.TestStatement.<name>=<sql statement used to test connection>

Generated by Clearspace on 2011-01-25-06:00 16

Understanding BW engine properties

Recover Startup Error

When a process engine containing JMS process starters attempts to startup while the JMS server is not running, the initialization of such process flows will fail. Setting the following property to "true" allows the process engine to start and the JMS process starters will wait until the JMS sever is up and running before starting: bw.plugin.jms.recoverOnStartupError

Reconnection
The property below is used in conjunction with FT URL setup in JMS shared connection. For this property to take effect, you need EMS client API 4.2 or higher, which means that this property will have no effect for BW releases 5.1.3, 5.2.0, etc. The syntax for the following property is 20 attempts within a span of 5000 milliseconds: java.property.com.tibco.tibjms.reconnect.attempts 20,5000

Java Activities
By default, the Java Code activity uses the system encoding. It does not use the encoding set in Designer or Administrator. To use a different encoding, for instance UTF-8, use the following property in "designer.tra" or "bwengine.tra": java.extended.properties=-Dfile.encoding=UTF-8

Mail activities
This discission referrs to the Java Mail API properties. Since we use the SMTP provider from Sun, the following Java properties can be used: mail.smtp.connectiontimeout(Socket conn timeout(ms),default is infinite timeout) mail.smtp.timeout(Socket I/O timeout(ms),default is infinite timeout.) The following are not BW properties; they are standard Java Mail API properties. java.property.mail.debug=true (throws debug information about mail to stdout) java.property.mail.smtp.auth=false (sets smtp authentication to "false")

Generated by Clearspace on 2011-01-25-06:00 17

Understanding BW engine properties

A new property to handle discrete media types (RFC2047). It handles four top-level media types (including image/*, application/*, audio/*, video/*), assuming that the message has only one binary part. This property has to be set to "true". bw.plugin.mail.receiverHandleDiscreteTypes A new property to flatten multiple nested mime sub-parts under any mime part. This property has to be set to "true" as well. bw.plugin.mail.receiverFlattenNestedAttachments The following property allows you to specify the number of times the Receive Mail process starter will attempt to receive the same message. The amount of time allotted for re-trials will be the value of this property multiplied by the polling interval. bw.plugin.mail.receiverRetryCount

Mapper Activities
The "Mapping Wizard" was creating empty tags for each optional element, even if the optional elements did not appear in the input data. To avoid the empty tags in the output when the input did not contain the optional element, the user had to manually create "xsl:if" statement. A new system property "automatic_mapper_if_surround" is added to fix this problem. Set this the following property to "true" in the designer.tra file in order to surround all new optional-to-optional mappings (including child elements) by an xsl:if statement. If the system property is set to "false" (or entirely absent) , child elements will not be surrounded with the xsl:if statement. java.property.automatic_mapper_if_surround=true

Parse Data Activities

If the line length is 2000 and the data format length is 100 and where the entire data is on one line, the expectation is that the parser would yield after 200 lines of the structure defined in the data format. Adding the property below and setting its value to "true" will fix the problem. bw.plugin.parseData.enforceLineLength

Generated by Clearspace on 2011-01-25-06:00 18

Understanding BW engine properties

RV transport
RV Transport
To use non-default values for RV transport, set these properties: Bus.User.Service=7501 Bus.User.Daemon=tcp:7501 Bus.User.Network=

SOAP Activities
java.property.com.tibco.plugin.soap.RetrieveResources.IgnoreInputHostForImportLo cations=true java.property.com.tibco.plugin.soap.RetrieveResources.IgnoreInputHostForWsil=tru e

TCP Activities
To Specify Accept Count (i.e. Connection Queue length) for TCP Server, set the following property, noting that 50 is the default setting: bw.plugin.tcp.server.acceptCount=50

XML Activities
java.property.com.tibco.bw.use.old.validator true java.property.com.tibco.xml.use.old.render.code true java.property.com.tibco.schema.ae.makeNillable true java.property.com.tibco.xml.schema.preserve-boolean-lexical-value=true Set the last property in designer.tra and then run the tester in Designer to enable the property. After adding it, you should see that boolean "0" will not be changed to "false".

Generated by Clearspace on 2011-01-25-06:00 19