Installing and configuring nJAMS Client for BW

The installation process of nJAMS Client for BW is straight forward and only consists of the following three steps:

  1. Copy nJAMS Client for BW, represented by a Java Archive File (JAR), to your TIBCO BusinessWorks palettes folder
  2. Configure nJAMS Client for BW according to your needs
  3. (Re-)Start all engines of TIBCO BusinessWorks that should use nJAMS Client for BW, respectively (re-)start TIBCO Designer

Copy nJAMS Client for BW to TIBCO BusinessWorks palettes folder

Download the distirbution package of nJAMS Client for BW from Integration Matters Download Portal and extract the package to a folder of your choice. The distribution package just consists of a single JAR file: njams.jar.

This JAR file has to be copied to TIBCO BusinessWorks palettes folder. The TIBCO BusinessWorks palettes folder is usually as follows:

<TIBCO_HOME>/bw/plugins/lib/palettes

On Unix/Linux, for example:

cp njams.jar /opt/tibco/bw/plugins/lib/palettes/

On Windows, for example:

copy njams.jar c:\tibco\bw\plugins\lib\palettes

Warning

Make sure there is only one single njams.jar file available in the class path. The presence of multiple versions of njams.jar may cause unexpected results.

Configuration of nJAMS Client for BW

The configuration of nJAMS Client for BW basically specifies how to monitor TIBCO BusinessWorks and how to communicate with a dedicated nJAMS Instance.

Configure nJAMS Client for BW in TIBCO BusinessWorks runtime

Specify logging mode: There are two common scenarios to use nJAMS Client for BW in TIBCO BusinessWorks runtime environment:

  • Non-invasive monitoring: attach nJAMS Client for BW to your existing TIBCO BusinessWorks engines; make use of nJAMS Client for BW implicit monitoring capabilities and start instantly.
  • Explicit monitoring: Instrument your services and make use of nJAMS Client for BW log activities of nJAMS palette to benefit from the full feature set of nJAMS Client for BW. Please refer to nJAMS Client for BW User Manual to learn more about nJAMS Client for BW logging modes.

Specify communication: Furthermore, you have to specify how nJAMS Client for BW should communicate with a dedicated nJAMS Instance in order to provide event messages.

Non-invasive monitoring

If you want to use nJAMS Client for BW with your existing TIBCO BusinessWorks engines and without changing your existing TIBCO BusinessWorks process design, the TRA file of your TIBCO BusinessWorks engine has to be modified.

Add the following properties to the end of the BW engine’s TRA file to enable non-invasive monitoring:

# Replace previous start class "java.start.class=com.tibco.pe.PEMain" with:
java.start.class=com.faizsiegeln.njams.client.run

# Enable nJAMS Client for BW:
tibco.clientVar.nJAMS/logMode=complete

Explicit monitoring

If you want to use explicit monitoring, you have to instrument your processes explicitly with nJAMS Client for BW log activities. Explicit monitoring does not require to update BW engine’s TRA file. Use TIBCO Designer to add nJAMS log activities to your TIBCO BusinessWorks process. nJAMS Client for BW provides s set of global variables for its configuration. The configuration of nJAMS Client for BW will be done during deployment of the BW engine. For example, you can use TIBCO Administrator to set the global variables according to your target environment.

Data Providers

nJAMS Client for BW generates event messages for different channels. A channel is called Data Provider. A Data Provider can be a communication channel between nJAMS Client for BW and an nJAMS Instance, or just a log file. nJAMS Client for BW is designed to allow multiple Data Providers in parallel to address different targets simultaneously.

The JMS Data Provider allows nJAMS Client for BW to send event messages to an nJAMS Server Instance via JMS. That is the typical approach for on-premise installations.

The Cloud Data Provider on the other side allows to target event messages to an nJAMS Cloud Instance, the subscription based service of nJAMS.

In addition, it is possible to generate event messages into BW engine’s log file or any custom log file.

JMS Data Provider

Use the JMS Data Provider to send event messages generated by nJAMS Client for BW to nJAMS Server. The following properties have to be specified to use TIBCO EMS as 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. For TIBCO EMS fault-tolerant or load-balanced URLs are supported.
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).
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/contextFactory:
 

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

Sample configuration of nJAMS Client for BW using the JMS Data Provider with JNDI:

# Replace TIBCO start class java.start.class=com.tibco.pe.PEMain with:
java.start.class=com.faizsiegeln.njams.client.run
# Enable nJAMS Client for BW:
tibco.clientVar.nJAMS/logMode=complete
# Configure JMS Data Provider:
# 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=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
Cloud Data Provider

For using nJAMS Client for BW with nJAMS Cloud service configure the Cloud Data Provider. Login to your Integration Matters account, select your nJAMS Cloud Instance setup, and get the required information for the following configuration:

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

API key of your nJAMS Cloud Instance.
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:
 

Client endpoint of nJAMS Cloud Service.
tibco.clientVar.nJAMS/DataProvider/Cloud/instanceId:
 

Id of your nJAMS Cloud instance.
tibco.clientVar.nJAMS/DataProvider/Cloud/certificate:
 

Full path to your certificate file.
tibco.clientVar.nJAMS/DataProvider/Cloud/privateKey:
 

Full path to your private key file.

Sample configuration of nJAMS Client for BW using the Cloud Data Provider:

# Replace TIBCO start class java.start.class=com.tibco.pe.PEMain with:
java.start.class=com.faizsiegeln.njams.client.run
# Enable nJAMS Client for BW:
tibco.clientVar.nJAMS/logMode=complete
# Configure 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/Client/endpoint=hub.integrationmatters.com
tibco.clientVar.nJAMS/DataProvider/Cloud/Client/instanceId=my_instanceid
tibco.clientVar.nJAMS/DataProvider/Cloud/Client/certificate=/opt/tibco/njams/<id>-certificate.pem
tibco.clientVar.nJAMS/DataProvider/Cloud/Client/privateKey=/opt/tibco/njams/<id>-private.pem.key
BW engine’s log file

You can use the Data Provider for BW engine’s log file, if you want nJAMS Client for BW to send event messages into the BW engine’s log file. It is recommended to use this Data Provider only in addition to the JMS or Cloud Data Provider, but not alone.

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).
Custom log file

You can use this Data Provider, if you want nJAMS Client for BW to send event messages into a separate log file. It is recommended to use this Data Provider only in addition to the JMS or Cloud Data Provider, but not alone.

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.

Configure nJAMS Client for BW in TIBCO Designer

You cannot just use nJAMS Client for BW in TIBCO BusinessWorks runtime environment, but also in development by using TIBCO Designer. As soon as nJAMS Client for BW resides in the palettes folder of TIBCO BusinessWorks and you start TIBCO Desginer, the nJAMS palette of various log activities is available. Start TIBCO Designer, open a project, and drag and drop an nJAMS activity into a process definition:

nJAMS palette

Thereupon a group of global variables is created for configuration of nJAMS Client for BW:

nJAMS palette

Once you start the “Tester” in TIBCO Designer, nJAMS Client for BW is initialized based on the configuration specified in the global variables. Alternatively, the “Tester” lets you also refer to an individual properties file that may contain an alternative configuration of nJAMS Client for BW. See nJAMS Client for BW User Guide for more information.

Restart TIBCO BusinessWorks engine(s)

Once you applied nJAMS Client for BW to your TIBCO BusinessWorks engines, the BW engines have to be restarted. You can use TIBCO Administrator to restart all engines, which are currently running on your machine. Please check your engine log file and verify that nJAMS Client for BW has been initialized correctly.

On a development machine you have to restart TIBCO Designer. After restarting TIBCO Designer you can see a new palette called nJAMS in your palettes menu.

Determining whether nJAMS Client for BW is successfully installed

When the TIBCO BusinessWorks engine is getting started, nJAMS Client for BW produces banner text information into the BW engine’s log file. By default you can find the BW engine’s log file at <TIBCO_HOME>/tra/domain/<your domain name>/application/logs.

Please verify the banner text information to make sure that nJAMS Client for BW has been started successfully. For example:

Info [bw.logger] BW-EXT-LOG-300000 nJAMS: initialize BW mode
Info [bw.logger] BW-EXT-LOG-300000 ************************************************************
Info [bw.logger] BW-EXT-LOG-300000 ***
Info [bw.logger] BW-EXT-LOG-300000 ***      nJAMS - Faiz & Siegeln GmbH (C) 2011-2019
Info [bw.logger] BW-EXT-LOG-300000 ***      initializing nJAMS library - version 4.0.0.0
Info [bw.logger] BW-EXT-LOG-300000 ***      registering nJAMS with engine
Info [bw.logger] BW-EXT-LOG-300000 ***      initializing JMS appender
Info [bw.logger] BW-EXT-LOG-300000 ************************************************************
Info [bw.logger] BW-EXT-LOG-300000 ***      nJAMS: initializing jms interface
Info [bw.logger] BW-EXT-LOG-300000 ***      JMS User                : admin
Info [bw.logger] BW-EXT-LOG-300000 ***      use JDNI                : true
Info [bw.logger] BW-EXT-LOG-300000 ***      JNDI Url                : tibjmsnaming://localhost:7222
Info [bw.logger] BW-EXT-LOG-300000 ***      JNDI User               : admin
Info [bw.logger] BW-EXT-LOG-300000 ***      Provider Context Factory: com.tibco.tibjms.naming.TibjmsInitialContextFactory
Info [bw.logger] BW-EXT-LOG-300000 ***      Connection Factory      : QueueConnectionFactory
Info [bw.logger] BW-EXT-LOG-300000 ***      Command Destination     : njams.command
Info [bw.logger] BW-EXT-LOG-300000 ***      JMS Selector            : NJAMS_BWENGINE=fs_pres.C1_Services-C1_Services
Info [bw.logger] BW-EXT-LOG-300000 ***      looking up "QueueConnectionFactory"
Info [bw.logger] BW-EXT-LOG-300000 ***      connecting ...
Info [bw.logger] BW-EXT-LOG-300000 ***      Initialization routine finished successfuly
Info [bw.logger] BW-EXT-LOG-300000 ***
Info [bw.logger] BW-EXT-LOG-300000 ************************************************************
Info [bw.logger] BW-EXT-LOG-300000 ***
Info [bw.logger] BW-EXT-LOG-300000 ************************************************************
Info [bw.logger] BW-EXT-LOG-300000 ***      check destination  ...
Info [bw.logger] BW-EXT-LOG-300000 ***      create receiver  ...
Info [bw.logger] BW-EXT-LOG-300000 ************************************************************
Info [bw.logger] BW-EXT-LOG-300000 ***
Info [bw.logger] BW-EXT-LOG-300000 ***      nJAMS: preparing to publish resources
Info [bw.logger] BW-EXT-LOG-300000 ***      reading resources from file system
Info [bw.logger] BW-EXT-LOG-300000 ***      found 133 resources to publish
Info [bw.logger] BW-EXT-LOG-300000 ***      publishing sources to njams.event
Info [bw.logger] BW-EXT-LOG-300000 ***