Reference: General properties

The basic configuration of nJAMS Client for BW6 takes place in config file njams.properties. This configuration file resides in <TIBCO_HOME>/bw/<VERSION>/config/njams. Use an editor of your choice and edit njams.properties according to your needs.

This is the reference of general nJAMS Client for BW6 properties.

Note

Any change in this configuration file requires a re-start of the BW6 AppNode.

Communication

The following properties deal with the communication between nJAMS Client and nJAMS Server, respectively nJAMS Cloud.

njams.sdk.communication:

Select type of communication with nJAMS Server, respectively nJAMS Cloud:

JMS nJAMS Client for BW6 communicates with nJAMS Server instance via TIBCO EMS. This settings is used for using nJAMS Server on premise, respectively private cloud.

CLOUD nJAMS Client for BW6 communicates with a nJAMS Cloud Instance. This setting is used, if you are using nJAMS Cloud service.

In case you are using JMS:

njams.sdk.communication.jms.connectionFactory:

Sets the connection factory, for example “ConnectionFactory”.

njams.sdk.communication.jms.username:

Use a valid JMS server user that has the required privileges to send and receive messages on the destinations defined in njams.sdk.communication.jms.destination.

njams.sdk.communication.jms.password:

The JMS user’s password.

njams.sdk.communication.jms.destination:

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

njams.sdk.communication.jms.destination.commands:

Name of the JMS destination that is used to send commands from nJAMS Server to nJAMS Client for BW6. This setting is optional and only used, if you want to use a dedicated topic commands.

njams.sdk.communication.jms.java.naming.factory.initial:

Sets the JNDI context factory.

njams.sdk.communication.jms.java.naming.security.principal:

Set JNDI user name.

njams.sdk.communication.jms.java.naming.security.credentials:

Set JNDI user’s password.

njams.sdk.communication.jms.java.naming.provider.url:

The JNDI server connection url. Fault-tolerant or load-balanced URLs are supported.

Sample configuration of a JMS Data Provider using TIBCO EMS:

## SDK configuration
# Communication settings
njams.sdk.communication=JMS

# JMS settings
njams.sdk.communication.jms.connectionFactory=ConnectionFactory
njams.sdk.communication.jms.username=njams
njams.sdk.communication.jms.password=njams
njams.sdk.communication.jms.destination=njams.endurance

# JNDI settings
njams.sdk.communication.jms.java.naming.factory.initial=com.tibco.tibjms.naming.TibjmsInitialContextFactory
njams.sdk.communication.jms.java.naming.security.principal=njams
njams.sdk.communication.jms.java.naming.security.credentials=njams
njams.sdk.communication.jms.java.naming.provider.url=tibjmsnaming://vslems01:7222

Sample configuration of a JMS Data Provider using Amazon MQ (Apache MQ):

## SDK configuration
# Communication settings
njams.sdk.communication=JMS

# JMS settings
njams.sdk.communication.jms.connectionFactory=ConnectionFactory
njams.sdk.communication.jms.username=njams
njams.sdk.communication.jms.password=njams
njams.sdk.communication.jms.destination=njams.endurance

# JNDI settings
njams.sdk.communication.jms.java.naming.factory.initial=org.apache.activemq.jndi.ActiveMQInitialContextFactory
njams.sdk.communication.jms.java.naming.security.principal=njams
njams.sdk.communication.jms.java.naming.security.credentials=njams
njams.sdk.communication.jms.java.naming.provider.url=ssl://<instance-name>.amazonaws.com:61617

In case you are using JMS with SSL:

njams.sdk.communication.jms.com.tibco.tibjms.ssl.vendor:

Specify j2se for JSSE SSL vendor, or use entrust6 for Entrust SSL vendor.

njams.sdk.communication.jms.com.tibco.tibjms.ssl.verify_host:

Indicates whether or not host should be verified.

njams.sdk.communication.jms.com.tibco.tibjms.ssl.trace:

true enables ssl trace, use false to disable trace.

njams.sdk.communication.jms.com.tibco.tibjms.ssl.trusted_certs:

Absolute path to directory or file with trusted certificate(s).

njams.sdk.communication.jms.com.tibco.tibjms.ssl.expected_hostname:

Optional. The expected name of the remote host.

The following parameters are used for JNDI w/ SSL:

njams.sdk.communication.jms.com.tibco.tibjms.naming.security_protocol:

Specify the security protocol to use in Tibjms JNDI lookups. Use security protocol ssl.

njams.sdk.communication.jms.com.tibco.tibjms.naming.ssl_trusted_certs:

Absolute path to directory or file with trusted certificate(s).

njams.sdk.communication.jms.com.tibco.tibjms.naming.ssl_verify_host:

Indicates whether or not host should be verified.

njams.sdk.communication.jms.com.tibco.tibjms.naming.ssl_verify_host_name:

Indicates whether or not the name of the host should be verified.

njams.sdk.communication.jms.com.tibco.tibjms.naming.ssl_expected_hostname:

Specify the common name in the server certificate in Tibjms JNDI lookups.

njams.sdk.communication.jms.com.tibco.tibjms.naming.ssl_identity:

Specify the client-side identity in Tibjms JNDI lookups.

njams.sdk.communication.jms.com.tibco.tibjms.naming.ssl_password:

Specify the password for the private key or the identity store in Tibjms JNDI lookups.

Sample configuration of a JMS Data Provider using SSL:

njams.sdk.communication=JMS

# JMS settings
#njams.sdk.communication.jms.connectionFactory=ConnectionFactory
njams.sdk.communication.jms.connectionFactory=SSLConnectionFactory
njams.sdk.communication.jms.username=admin
njams.sdk.communication.jms.password=admin
njams.sdk.communication.jms.destination=njams

# ssl settings
njams.sdk.communication.jms.com.tibco.tibjms.ssl.vendor=j2se
njams.sdk.communication.jms.com.tibco.tibjms.ssl.verify_host=disabled
njams.sdk.communication.jms.com.tibco.tibjms.ssl.trace=true
njams.sdk.communication.jms.com.tibco.tibjms.ssl.trusted_certs=C\:/tibco/ems/8.5/samples/certs/server_root.cert.pem
njams.sdk.communication.jms.com.tibco.tibjms.ssl.expected_hostname=server

# JNDI settings
njams.sdk.communication.jms.java.naming.factory.initial=com.tibco.tibjms.naming.TibjmsInitialContextFactory
njams.sdk.communication.jms.java.naming.security.principal=admin
njams.sdk.communication.jms.java.naming.security.credentials=admin
njams.sdk.communication.jms.java.naming.provider.url=tibjmsnaming://vswtibco01:7242
njams.sdk.communication.jms.com.tibco.tibjms.naming.security_protocol=ssl
njams.sdk.communication.jms.com.tibco.tibjms.naming.ssl_trusted_certs=C\:/tibco/ems/8.5/samples/certs/server_root.cert.pem
njams.sdk.communication.jms.com.tibco.tibjms.naming.ssl_verify_host=false
njams.sdk.communication.jms.com.tibco.tibjms.naming.ssl_verify_host_name=false
njams.sdk.communication.jms.com.tibco.tibjms.naming.ssl_expected_hostname=server
#njams.sdk.communication.jms.com.tibco.tibjms.naming.ssl_identity
#njams.sdk.communication.jms.com.tibco.tibjms.naming.ssl_password

In case you are using Kafka:

The following properties allow to use Kafka for the communication between nJAMS Client and nJAMS Server.

njams.sdk.communication.kafka.topicPrefix:

The prefix for the name of the topic. The prefix will be extended with .event for event messages send by nJAMS Client for BW6 and .command for messages send from the server to the nJAMS Client for BW6. Default is njams.

njams.sdk.communication.kafka.client.bootstrap.servers:

Machine name and port of the Kafka instance, e.g. vslkafka01:9092.

In case you are using CLOUD:

The following properties have to be configured to allow nJAMS Client for BW6 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.

njams.sdk.communication.cloud.apikey:

Refers to absolute path of API key file.

njams.sdk.communication.cloud.endpoint:

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

njams.sdk.communication.cloud.certificate:

Refers to absolute path of client certificate file.

njams.sdk.communication.cloud.instanceid:

Refers to absolute path of nJAMS Cloud instance id file.

njams.sdk.communication.cloud.privatekey:

Refers to absolute path of private key file.

Sample configuration of a Cloud Data Provider:

## SDK configuration
# Communication settings
njams.sdk.communication=CLOUD

# Cloud Data Provider:
njams.sdk.communication.cloud.apikey=/opt/tibco/njams/api.key
njams.sdk.communication.cloud.endpoint=ingest.integrationmatters.com
njams.sdk.communication.cloud.certificate=/opt/tibco/njams/certificate.pem
njams.sdk.communication.cloud.instanceid=/opt/tibco/njams/instanceId
njams.sdk.communication.cloud.privatekey=/opt/tibco/njams/private.pem.key

Replay

The following property enables/disables Replay in nJAMS Client for BW6:

njams.bw6.replayEnabled:

Turn on/off Replay.

true enables Replay (default).

false disables Replay.

Subagent

The following properties configure Subagent against nJAMS Agent service:

njams.sdk.subagent.enabled:

Turn on/off Subagent.

true enables Subagent (default).

false disables Subagent.

njams.sdk.subagent.host:

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

njams.sdk.subagent.port:

Port number of nJAMS Agent service, default is 6450.

njams.bw6.enableProcessInstrumentation:

For collecting complete statistics, the subagent needs process instrumentation to be activated in TIBCO BusinessWorks 6. With this switch set to true the client will enable process instrumentation on startup.

Note: Process instrumentation can be activated or disabled manually at any time using TIBCO BusinessWorks 6 management tools.

true The client activates process instrumentation in TIBCO BusinessWorks 6 on startup (default).

false The client does not activate process instrumentation. It can however be activated manually using TIBCO BusinessWorks 6 management tools.

Sample settings for Subagent:

# Enable Subagent and configure against nJAMS Agent on localhost:
njams.sdk.subagent.enabled=true
njams.sdk.subagent.host=localhost
njams.sdk.subagent.port=6450
njams.bw6.enableProcessInstrumentation=true

Inline Sub Processes

In TIBCO BusinessWorks 6 non-spawned sub processes always create new jobs and are therefore represented in nJAMS by separate process instances. Since these process instances are correlated with the main process, which calls the sub process, the Result list of correlated entries may get very long. Furthermore, the number of nJAMS log messages may also increase significantly, if the main process calls the sub process(es) very often.

To counter this, nJAMS Client for BW6 optionally supports to treat non-spawned sub processes as “inline sub processes”. Inline sub processes means, nJAMS Client for BW6 will NOT create a separate process instance for a non-spawned sub process call. This behavior is therefore similar to the behavior of nJAMS Client for BW in connection with TIBCO BusinessWorks 5.

Spawned sub processes in TIBCO BusinessWorks 6 are not affected by this setting. They are still represented in nJAMS by separate process instances.

njams.bw6.inlineSubProcesses:

Enables/disables inline sub processes.

true enables inline sub processes.

false disables inline sub processes (default).

Use encrypted passwords

In njams configuration files passwords are usually entered in plain text, such as njams.sdk.communication.jms.password=foo. In case you do not want to use uncoded passwords, you can use encrypted passwords as follows:

Assume, the password of your JMS account is foo:

1. Download nJAMS SDK containing the encryption utility from Github: IntegrationMatters/njams-sdk

2. Call java -jar njams-sdk-4.x.x.jar foo will output encrypted password: ??0190029006d0048004c0055000c0017002d00090005006a004d007100b500bd

3. Place encrypted password into njams.properties at njams.sdk.communication.jms.password=??0190029006d0048004c0055000c0017002d00090005006a004d007100b500bd

4. Restart AppNode to make change effective

Memory Management / Sender Pool

The following properties are not required to be changed in most cases. Please only change these values, if you are fully aware of the effects.

Note

By default a dedicated connection pool is created for each TIBCO BusinessWorks 6 application running on a certain node. Starting with release 4.2.2 there is a new option njams.client.sdk.sharedcommunications that allows using a single shared connection pool for all TIBCO BusinessWorks 6 applications.

njams.client.sdk.sharedcommunications:

Specifies whether each TIBCO BusinessWorks 6 application uses its own dedicated connection pool for communications with nJAMS Server (default) or a global shared connection pool is used for all applications. Depending on this setting, the properties minsenderthreads and maxsenderthreads either apply to each TIBCO BusinessWorks 6 application separately, or just once globally. Therefore this option directly affects the number of connections being created.

true Use a single shared connection pool for communications.

false Use a dedicated connection pool for each TIBCO BusinessWorks 6 application (default).

This option is available since nJAMS Client for BW6 release 4.2.2.

njams.client.sdk.discardpolicy:

Discards messages from memory, when maxQueueLength is exceeded.

none blocks the application processing until queue size is below threshold, no message will be discarded (default).

discard will discard the message. When using this option make sure to configure maxqueuelength and maxsenderthreads reasonably so that the client can handle message bursts like they can occur for instance during startup.

onConnectionLoss only discards messages, if there is no connection to JMS or Cloud provider. Otherwise application processing is slowed down until all log messages are sent, respectively queue length is below threshold.

njams.client.sdk.maxqueuelength:

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

Note

Since release 4.2.2 the default queue size is 50 when discard-policy is set to discard and neither maxqueuelength nor maxsenderthreads is specified. This is to reduce the probability of discarding, when the client creates multiple (project-) messages during startup.

njams.client.sdk.maxsenderthreads:

This property configures maximum sender threads for the selected implementation. Default is 8.

njams.client.sdk.minsenderthreads:

This property configures minimum sender threads for the selected implementation. Default is 1.

njams.client.sdk.senderthreadidletime:

Idle connection timeout to close and remove connections in msec. Default is 10000.

njams.client.sdk.flush_interval:

Period of time for collecting events. Enter integer value in seconds. Default is 30.

njams.client.sdk.flushsize:

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

Sample settings for memory management:

# Memory manangement default settings for usual scenarios:
njams.client.sdk.flushsize=5242880
njams.client.sdk.maxqueuelength=8
njams.client.sdk.discardpolicy=none

Additional properties

njams.bw6.start:

This setting allows disabling nJAMS Client for BW6 within an AppNode.

true nJAMS Client for BW6 is enabled (default).

false nJAMS Client for BW6 is disabled.

Note

This property cannot be used in njams.properties, but only in context of the Java Extended Properties for starting the AppNode. See also Disabling nJAMS Client for BW6 for a particular AppNode for more information.

njams.bw6.domains:

Specify domain(s) that should be explicitly monitored by nJAMS Client for BW6. By setting this property, nJAMS Client for BW6 only monitors applications of this domain(s). Domains that are not listed will not be monitored.

You can use this setting, if you do not want to monitor all domains, but only specific domains of your TIBCO BusinessWorks 6 environment. Please note that also no metrics data is being sent of domains, which are not listed.

By default, this property is empty. When this property is empty, respectively unused, all domains are monitored.

The following example will only monitor domain “my_domain_1”:

njams.bw6.domains=my_domain_1

This example will monitor both domains:

njams.bw6.domains=my_domain_1,my_domain_2

njams.bw6.processExcludePattern.<id>:

This property specifies TIBCO BusinessWorks 6 applications that should not be monitored by nJAMS Client for BW6.

By default, this property is empty. When this property is empty, respectively unused, no application is excluded.

The following example will exclude process “my_app_1” from being monitored:

njams.bw6.processExcludePattern.1=my_app_1

The next example excludes processes with names matching a regular expression, such as containing “starter” in process name:

njams.bw6.processExcludePattern.1=.*starter.*

If you have further applications that should be excluded, you can add additional properties:

njams.bw6.processExcludePattern.2=my_app_2

njams.bw6.processExcludePattern.3=my_app_3

njams.client.sdk.deprecatedsubprocesspathfield:

nJAMS Client for BW6 uses a new way in handling sub process calls. The more efficient approach of nJAMS Client for BW6 requires nJAMS Server 5.1 or higher.

true enables compatibility mode. Use this setting in nJAMS Client for BW6, when you are on nJAMS Server 4.x or 5.0.

false disables compatibility mode (default). Use this setting or omit it, when you use nJAMS Server 5.1 or higher.

Note

Make sure to include this setting when running nJAMS Server before version 5.1.

njams.sdk.datamasking.enabled:

Data Masking allows you to mask particular parts of Trace Data, which should remain confidential. Assume you have Tracing enabled for an activity that processes password information. By default, the nJAMS UI provides Trace Data including the password information in plain text. To prevent password information from being shown in plain text, you can use data masking.

This property corresponds to property njams.sdk.datamasking.regex.<your-regex-name>, which specifies the data masking pattern.

In addition, this property also corresponds to Data Masking configuration in application based configuration file, see Appendix B.

true enables data masking (default). Use njams.sdk.datamasking.regex.<your-regex-name> to specify data masking pattern.

false disables data masking.

njams.sdk.datamasking.regex.<your-regex-name>:

Use a regular expression to specify a pattern for data masking.

For example, the following regular expression replaces any information that matches XML tag “Password” in Trace Data with an asterisk character (“*”):

njams.sdk.datamasking.regex.maskPW=<Password>(\\p{Alpha}|/|\\p{Digit})*</Password>

You can specify multiple regex definitions by defining further properties of regular expressions:

njams.sdk.datamasking.regex.mask1=my_first_regex

njams.sdk.datamasking.regex.mask2=my_second_regex

njams.sdk.logAllErrors:

Configures in which situations nJAMS Client for BW6 will create error events.

true nJAMS Client for BW6 will create error events even for errors that are actually handled by the applications.

false nJAMS Client for BW6 creates error events only for errors that are not handled by the application (default).

njams.sdk.truncateActivitiesLimit:

When setting this option to a positive number, nJAMS Client for BW6 will stop sending detailed activity- and transition information to the server once that number of activities has been reached. The client will however continue sending job status- and event information. In nJAMS Server you will not see the transitions between activities for such job instances.

This option goes along with the according setting in nJAMS Server. But when using different settings here and in the server, the smaller value (greater than 0) will take effect.

This option is disabled by default, which can be achieved by setting 0.

Note

Requires nJAMS Server 5.1 or later to work properly.

njams.sdk.truncateOnSuccess:

When this setting is enabled by setting to true, the nJAMS Client for BW6 will not send detailed activity- and transition information for job instances that completed successfully. The client will however send job status- and event information. Job instances completing with any other status than success are not affected by this setting. In nJAMS Server you will not see transitions between activities for such job instances. This setting has only limited effect on job instances that send more than a single message because it only affects the last message being sent.

This option goes along with the according setting in nJAMS Server (compress successful transactions). It will be effective if it is either set here in the nJAMS Client for BW6, or in the server.

This option is disabled by default, i.e., false.

Note

Requires nJAMS Server 5.1 or later to work properly.

njams.bw6.maxIdleTimeSec:

When enabled, this option removes stale TIBCO BusinessWorks 6 process instances from nJAMS Client for BW6 monitoring.

Each process instance that is monitored by nJAMS Client for BW6 and does not make any progress in TIBCO BusinessWorks 6 for the configured amount of time (in seconds) will be unconditionally removed from nJAMS Client for BW6, freeing all resources occupied by this instance.

Specify the maximum idle time in seconds for enabling this functionality, or set to 0 or a negative value for disabling (default).

This option is available since nJAMS Client for BW6 release 4.2.2.

Note

This option is a kind of error handling for processes hanging in TIBCO BusinessWorks 6 and is actually not required for normal processing. Be aware that when enabled, this setting is appplied to all process instances. So, make sure to choose a value that respects proceeding of all job instances, even those proceeding commonly slowly.

njams.bw6.configFolderOverride:

By default, the nJAMS Client for BW6 application based configuration files (JSON files) are located in same folder as the nJAMS Client for BW6 configuration file (njams.properties). The location of the folder can now be changed with this property.

njams.client.sdk.disable.startdata:

Disabling start data prevents nJAMS Client for BW6 from sending the input data of a process execution.

true disables collecting and sending sending start data of a process execution

false enables collecting and sending start data of a process execution (default).

Note

This property affects nJAMS Replay in the way that when start data is disabled there is no recorded data available that can be used for replaying a process execution.

njams.bw6.multipleAppVersionsEnabled:

Use this option to disable support for multiple application versions. This option can be used in environments that only run a single version of each application. It removes the additional version level from the main object tree and Argos identifiers in nJAMS like it used to be in previous client releases. However, internally the client now always separates application versions from each other.

true enables support of multiple appication versions in TIBCO BW6 AppSpace (default).

false disables support of multiple application versions and sets the previously known behavior.

If this option is disabled and an additional version of an application is detected by the client, it will log an error message and completely ignore that second and any further version of that application.

This property is introduced with version 4.5 of nJAMS Client for BW6.

njams.bw6.configCloningEnabled:

Each application version now has a separate application based configuration file (JSON). This allows different configurations for each application version. If nJAMS Client for BW6 detects a new application version for that no configuration file exists, it clones the configuration of the closest but smaller version of the same application. For instance, if versions 2.0 and 3.0 of application ‘App’ is already running and both have a configuration file, and then version 2.5 of ‘App’ is started that does not yet have an own configuration file, nJAMS Client for BW6 will clone the configuration of version 2.0 and re-use it for 2.5 also.

true enables cloning of configuration files for application versions (default).

false disables cloning.

Note

Cloning configurations from earlier nJAMS Client for BW6 versions (without application version number) for this new client version (with application version numbers) is not affected by this settings. The client will always clone configurations in that case.

This property is introduced with version 4.5 of nJAMS Client for BW6.

njams.bw6.modelTimeoutMs:

Specifies the maximum time (in milliseconds) that nJAMS Client for BW6 will wait for process models to become available. Default is 30000 msecs. This value is a kind of error handling that cancels waiting for process models, when a model is not received by the nJAMS Client for any reason. Increase this value only if your environment contains a large number of process models and the default wait time of 30000 msecs is not sufficient.

Note

In most cases the default value should be sufficient. Processing of process models usually does not need more than a few seconds, depending on the number of applications and process modes. If the default is not sufficient, you should first check your system’s performance, before increasing the timeout.