Reference nJAMS Client for BW properties

This is the reference of available nJAMS Client for BW properties:

Initialize nJAMS Client for BW

Replace Java Start Class preset by TIBCO with Java Start Class of nJAMS Client for BW in order to initialize nJAMS Client for BW once the BW eninge starts.

Update BW engine TRA file by commenting original start class and adding njams start class:

# java.start.class=com.tibco.pe.PEMain
java.start.class=com.faizsiegeln.njams.client.run

General settings

The following properties determine the general configuration of nJAMS Client for BW.

tibco.clientVar.nJAMS/logMode:  

Globally controls the operation mode of the nJAMS Client for BW:

complete nJAMS Client for BW will monitor all processes that are executed within the TIBCO BusinessWorks engine (default).

exclusive nJAMS Client for BW will only monitor processes, that make explicit use of the nJAMS Client for BW palette. All other processes will be ignored.

none the nJAMS Client for BW functionality is completely disabled; event instrumented processes that are using the nJAMS Client for BW palette are not monitored.

tibco.clientVar.nJAMS/confiruationFile:  

Defines the path to a directory or file name where the configuration of this client is stored. Directory: If a directory is configured, nJAMS Client for BW will search for a file of name <ENGINE_NAME>_njams_config.xml. Absolute file name: if an absolute file name is configured, nJAMS Client for BW will use that file as its configuration file. Default is not specified.

tibco.clientVar.nJAMS/publishSources:  

Controls whether to publish process definition or not. If no process definition is sent, there will be no process graph visible in nJAMS UI.

true publishes process definitions (default).

false does not publish process definitions.

tibco.clientVar.nJAMS/flushOnCheckpoint:  

Controls how to proceed, when TIBCO BusinessWorks Checkpoint activity is executed.

true sends event message, when executing BW Checkpoint activity regardless of other nJAMS Client for BW settings (logMode, timeoutPush) (default).

false continues with respect of other nJAMS Client for BW settings.

tibco.clientVar.nJAMS/logAllErrors:  

Controls when nJAMS Client for BW should send error events.

true automatically creates error events for catched and uncatched exceptions.

false automatically creates error events only for uncatched exceptions (default).

Sample settings for general configuration of nJAMS Client for BW:

tibco.clientVar.nJAMS/logMode=complete
tibco.clientVar.nJAMS/configurationFile=
tibco.clientVar.nJAMS/flushOnCheckpoint=true
tibco.clientVar.nJAMS/logAllErrors=false

Data Providers - general

The following settings apply to all Data Providers.

tibco.clientVar.nJAMS/DataProvider/instantPush:  

Controls whether to collect events within a period of time and send the events by one single message or to send out a message for each event.

true sends instantly an event message on each event.

false collects events within a period of time according to timeoutPush (default).

tibco.clientVar.nJAMS/DataProvider/timeoutPush:  

Period of time for collecting events. Enter any integer value in miliseconds. Default is 30000.

tibco.clientVar.nJAMS/DataProvider/timeoutCheckInterval:  

Period of time for timeout check. Enter any integer value in miliseconds. Default is 5000.

Sample settings for general data provider settings:

# Typical general settings for Data Providers are:
tibco.clientVar.nJAMS/DataProvider/instantPush=false
tibco.clientVar.nJAMS/DataProvider/timeoutPush=30000
tibco.clientVar.nJAMS/DataProvider/timeoutCheckInterval=5000

Data Provider - Cloud

The following properties have to be configured to allow nJAMS Client for BW to create a secure connection via https to a designated nJAMS Cloud Instance. You can find the configuration of the Cloud Data Provider within the Instance Setup of your Integration Matters account. A subscription of nJAMS Cloud is required.

tibco.clientVar.nJAMS/DataProvider/Cloud/apiKey:  

Refers to absolute path of API key file.

tibco.clientVar.nJAMS/DataProvider/Cloud/enabled:  

Enables/disables sending of event messages to nJAMS Cloud Instance.

true enables Cloud Data Provider.

false disables Cloud Data provider (default).

tibco.clientVar.nJAMS/DataProvider/Cloud/endpoint:  

Endpoint of Integration Matters client hub. Default is hub.integrationmatters.com and does not need to be changed.

tibco.clientVar.nJAMS/DataProvider/Cloud/Client/certificate:  

Refers to absolute path of client certificate file.

tibco.clientVar.nJAMS/DataProvider/Cloud/Client/instanceId:  

Unique id of your nJAMS Cloud Instance.

tibco.clientVar.nJAMS/DataProvider/Cloud/Client/privateKey:  

Refers to absolute path of private key file.

Sample configuration of a Cloud Data Provider:

# Cloud Data Provider:
tibco.clientVar.nJAMS/DataProvider/Cloud/apiKey=/opt/tibco/njams/api.key
tibco.clientVar.nJAMS/DataProvider/Cloud/enabled=true
tibco.clientVar.nJAMS/DataProvider/Cloud/endpoint=hub.integrationmatters.com
tibco.clientVar.nJAMS/DataProvider/Cloud/Client/certificate=/opt/tibco/njams/certificate.pem
tibco.clientVar.nJAMS/DataProvider/Cloud/Client/instanceId=4711
tibco.clientVar.nJAMS/DataProvider/Cloud/Client/privateKey=/opt/tibco/njams/private.pem.key

Data Provider - JMS

The following properties have to be configured to allow nJAMS Client for BW to create a connection to designated JMS provider.

tibco.clientVar.nJAMS/DataProvider/JMS/enabled:  

Enables or disables the sending of event messages via JMS.

true nJAMS Client for BW communicates with the nJAMS Server using JMS.

false JMS communication is disabled (default).

tibco.clientVar.nJAMS/DataProvider/JMS/destination:  

The JMS destination name prefix. The prefix will be extended with “.event” for event messages send by nJAMS Client for BW and “.command” for messages send from the server to the nJAMS Client for BW. Default is njams.

tibco.clientVar.nJAMS/DataProvider/JMS/server:  

The JMS or JNDI server connection url. This can either be the JNDI connection URL, if JNDI is enabled, or the native JMS server connection URL.

Examples for TIBCO EMS are: tibjmsnaming://localhost:7222 (for JNDI) or tcp://localhost:7222 (no JNDI). For TIBCO EMS fault-tolerant or load-balanced URLs are supported.

Examples for ActiveMQ are: tcp://localhost:61616 or failover:(tcp://localhost:61616,tcp://remotehost:61616)?warnAfterReconnectAttempts=1&initialReconnectDelay=100 for fault tolerant connections.

tibco.clientVar.nJAMS/DataProvider/JMS/user:  

The JMS server user name to use. Use any valid JMS server user that has the required privileges to send and receive messages on the destinations defined in tibco.clientVar.nJAMS/DataProvider/JMS/destination.

tibco.clientVar.nJAMS/DataProvider/JMS/password:  

The JMS user’s password. The password is allowed to be clear text (not recommened) or obfuscated (using TIBCO’s obfuscation tool).

tibco.clientVar.nJAMS/DataProvider/JMS/clientId:  

Specifies the TIBCO EMS connection’s clientId to be set.

tibco.clientVar.nJAMS/DataProvider/JMS/deliveryMode:  

Sets the producer’s default delivery mode. Delivery mode is set to PERSISTENT by default, alternatively use NON_PERSISTENT.

The following properties have been introduced with version 4.0.8:

tibco.clientVar.nJAMS/DataProvider/JMS/pool/min:  This property configures minimum pool size of JMS connection. Default is 1. tibco.clientVar.nJAMS/DataProvider/JMS/pool/max:  This property configures maximum pool size of JMS connection. Default is 20. tibco.clientVar.nJAMS/DataProvider/JMS/pool/idleTimeoutMs:  Idle connection timeout to close and remove JMS connection in msec. Default is 60000. tibco.clientVar.nJAMS/DataProvider/JMS/pool/borrowTimeoutMs:  Timeout to wait for a JMS connection before throwing jmsConnectionLoss exception in msec. Default is 5000.

JNDI

Use these properties for JNDI:

tibco.clientVar.nJAMS/DataProvider/JMS/useJNDI:  

Controls whether to use JNDI to lookup (JMS) connection factories, or not.

true use a JNDI server to lookup connection factories (default).

false no JNDI lookup.

tibco.clientVar.nJAMS/DataProvider/JMS/JNDI/user:  

Set JNDI user name.

tibco.clientVar.nJAMS/DataProvider/JMS/JNDI/password:  

Set JNDI user’s password.

tibco.clientVar.nJAMS/DataProvider/JMS/connectionFactory:  

Sets the JNDI context factory.

tibco.clientVar.nJAMS/DataProvider/JMS/connectionFactory/compress:  

Determine, if the the JMS messages should be send in compressed mode to save bandwidth.

true means the JMS header “JMS_TIBCO_COMPRESS” is set to “true”; the TIBCO EMS libraries will compress the message before sending (default).

false means the JMS message is send without compression.

tibco.clientVar.nJAMS/DataProvider/JMS/contextFactory:  

Sets the JNDI context factory. For TIBCO EMS use com.tibco.tibjms.naming.TibjmsInitialContextFactory (default).

SSL

Use these properties for using SSL connection:

tibco.clientVar.nJAMS/DataProvider/JMS/ssl/useSSL:  

Turn on/off SSL connections.

true enables SSL

false disables SSL (default).

tibco.clientVar.nJAMS/DataProvider/JMS/ssl/ssl_ciphers:  

Name of the SSL ciphers to use. For example: +RC4-MD5:+RC4-SHA

tibco.clientVar.nJAMS/DataProvider/JMS/ssl/ssl_debug:  

Turn on/off SSL debug tracing.

true enables SSL debug tracing

false disables SSL debug tracing (default).

tibco.clientVar.nJAMS/DataProvider/JMS/ssl/ssl_hostname:  

If set, the JMS server name presented in the server’s certificate is matched against this name. If they do not match, the SSL connection is not established.

tibco.clientVar.nJAMS/DataProvider/JMS/ssl/ssl_identity:  

Absolute path to a PKCS12 identity, which is used to establish the SSL connection. For example: /home/njams/certificates/njams.p12.

tibco.clientVar.nJAMS/DataProvider/JMS/ssl/ssl_key:  

Absolute path to a private key file.

tibco.clientVar.nJAMS/DataProvider/JMS/ssl/ssl_password:   tibco.clientVar.nJAMS/DataProvider/JMS/ssl/ssl_trace:  

Turn on/off SSL tracing.

true enables SSL tracing.

false disables SSL tracing (default).

tibco.clientVar.nJAMS/DataProvider/JMS/ssl/ssl_trusted:  

Absolute path to file or folder with trusted certificates (in PEM format). For example: /home/njams/certificates/njams.cert.pem.

tibco.clientVar.nJAMS/DataProvider/JMS/ssl/ssl_vendor:  

Name of the SSL vendor to use. For example: j2se

Sample configuration of an JMS Data Provider using TIBCO EMS w/ JNDI:

# TIBCO EMS Data Provider:
    tibco.clientVar.nJAMS/DataProvider/JMS/enabled=true
    tibco.clientVar.nJAMS/DataProvider/JMS/destination=njams
    tibco.clientVar.nJAMS/DataProvider/JMS/useJNDI=true
    tibco.clientVar.nJAMS/DataProvider/JMS/server=tibjmsnaming\://localhost\:7222
    tibco.clientVar.nJAMS/DataProvider/JMS/connectionFactory=QueueConnectionFactory
    tibco.clientVar.nJAMS/DataProvider/JMS/contextFactory=com.tibco.tibjms.naming.TibjmsInitialContextFactory
    tibco.clientVar.nJAMS/DataProvider/JMS/user=admin
    tibco.clientVar.nJAMS/DataProvider/JMS/password=admin
    tibco.clientVar.nJAMS/DataProvider/JMS/JNDI/user=admin
    tibco.clientVar.nJAMS/DataProvider/JMS/JNDI/password=admin

Sample configuration of an JMS Data Provider using ActiveMQ:

# AMQ JMS Data Provider:
    tibco.clientVar.nJAMS/DataProvider/JMS/enabled=true
    tibco.clientVar.nJAMS/DataProvider/JMS/destination=njams
    tibco.clientVar.nJAMS/DataProvider/JMS/useJNDI=true
    tibco.clientVar.nJAMS/DataProvider/JMS/server=tcp\://localhost\:61616
    tibco.clientVar.nJAMS/DataProvider/JMS/connectionFactory=QueueConnectionFactory
    tibco.clientVar.nJAMS/DataProvider/JMS/contextFactory=org.apache.activemq.jndi.ActiveMQInitialContextFactory
    tibco.clientVar.nJAMS/DataProvider/JMS/user=admin
    tibco.clientVar.nJAMS/DataProvider/JMS/password=admin
    tibco.clientVar.nJAMS/DataProvider/JMS/JNDI/user=admin
    tibco.clientVar.nJAMS/DataProvider/JMS/JNDI/password=admin

Data Provider - EngineLog

tibco.clientVar.nJAMS/DataProvider/EngineLog/enabled:  

Enables or disables the writing of event messages into bw engine’s log file.

true nJAMS Client for BW writes event messages into bw engine’s log file.

false disables writing event messages into bw engine’s log file (default).

Data Provider - File

tibco.clientVar.nJAMS/DataProvider/File/enabled:  

Enables or disables the writing of event messages into log file.

true nJAMS Client for BW writes event messages into log file.

false disables writing event messages into log file (default).

tibco.clientVar.nJAMS/DataProvider/File/name:  

Absolute path of the log file to write log entries to (if enabled). For example: /tmp/njams_events.log.

Memory Management

See the following properties to adjust nJAMS Client for BW’s memory management:

tibco.clientVar.nJAMS/MemoryManagement/maxMsgSizeMB:  

Maximum internal message size. If size of internal message is reached, an instant push is triggered. Enter any integer value > 0 in MB. Default is 10.

tibco.clientVar.nJAMS/MemoryManagement/maxQueueLength:  

Maximum internal queue size, before discardPolicy is applied. Enter any integer value > 0. Default is 20.

tibco.clientVar.nJAMS/MemoryManagement/discardPolicy:  

Discards messages from memory, when maxQueueLength is exceeded.

none blocks the engine until queue size is below threshold (default).

discard will discard of the message.

OnConnectionLoss only discards event messages, if there is no connection available to JMS or Cloud provider. Otherwise the engine is slowed down until all log messages are sent, respectively queue size is below threshold.

Sample settings for memory management:

# Memory manangement settings for usual scenarios:
tibco.clientVar.nJAMS/MemoryManagement/maxMsgSizeMB=10
tibco.clientVar.nJAMS/MemoryManagement/maxQueueLength=20
tibco.clientVar.nJAMS/MemoryManagement/discardPolicy=none

Log4j configuration

nJAMS Client for BW uses the TIBCO BusinessWorks log4j configuration for its technical logging. By default, nJAMS messages will be logged into bw engine’s log file. You can use an individual logger for nJAMS Client for BW, if you want to log nJAMS message into a separate log file.

Modify <TIBCO_HOME>/bw/5.x/lib/log4j.xml and add an additional logger for nJAMS Client for BW, e.g.:

<appender name="njams_log" class="org.apache.log4j.RollingFileAppender">
    <param name="File" value="/tmp/njams.log"/>
    <layout class="org.apache.log4j.PatternLayout">
        <param name="ConversionPattern" value="%d{yyyy-MM-dd HH:mm:ss} %-5p %c{1}:%L - %m%n" />
    </layout>
</appender>

<logger name="bw.logger.njams" additivity="false">
    <level value="INFO" />
    <appender-ref ref="njams_log" />
</logger>

Also add the following property to your bw engine TRA file to make use of this logger:

tibco.clientVar.nJAMS/logger=bw.logger.njams

Subagent

The following properties configure Subagent against nJAMS Agent service:

tibco.clientVar.nJAMS/Subagent/enabled:  

Turn on/off Subagent.

true enables Subagent (default).

false disables Subagent.

tibco.clientVar.nJAMS/Subagent/host:  

Name of the server that hosts nJAMS Agent service. Enter a hostname or ip-address, default is localhost.

tibco.clientVar.nJAMS/Subagent/port:  

Port number of nJAMS Agent service, default is 6450.

Sample settings for Subagent:

# Enable Subagent and configure against nJAMS Agent on localhost:
tibco.clientVar.nJAMS/Subagent/enabled=true
tibco.clientVar.nJAMS/Subagent/host=localhost
tibco.clientVar.nJAMS/Subagent/port=6450

Quick sample configuration

Please find below a sample configuration that enables nJAMS Client for BW in non-invasive mode while using TIBCO EMS. After applying the configuration to BW engine TRA file, you have to restart the BW engine.

Use the following sample properties as a template in order to instantly start with nJAMS Client for BW:

java.start.class=com.faizsiegeln.njams.client.run
tibco.clientVar.nJAMS/logMode=complete
tibco.clientVar.nJAMS/DataProvider/JMS/useJNDI=true
tibco.clientVar.nJAMS/DataProvider/JMS/destination=njams
tibco.clientVar.nJAMS/DataProvider/JMS/enabled=true
tibco.clientVar.nJAMS/DataProvider/JMS/user=<your-ems-username>
tibco.clientVar.nJAMS/DataProvider/JMS/password=<your-ems-password>
tibco.clientVar.nJAMS/DataProvider/JMS/server=tibjmsnaming\://<your-ems-machine>\:7222
tibco.clientVar.nJAMS/DataProvider/JMS/contextFactory=com.tibco.tibjms.naming.TibjmsInitialContextFactory
tibco.clientVar.nJAMS/DataProvider/JMS/connectionFactory=QueueConnectionFactory