Integration Matters Documentation Documentation

Integration Matters DocumentationDocumentation

IM

Mar 01, 2021

nJAMS Client for BW6

1 Installation 31.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

1.1.1 Supported software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.1.2 Hardware requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.1.3 Supported Platforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.1.4 TIBCO EMS Client libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.1.5 Additional Software requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

1.2 Preparing for installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51.2.1 Preparing TIBCO BusinessWorks™ 6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51.2.2 Preparing TIBCO Enterprise Message Service™ . . . . . . . . . . . . . . . . . . . . . . . 51.2.3 Preparing network security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51.2.4 Preparing nJAMS Server® . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

1.3 Installing and configuring nJAMS Client for BW6 . . . . . . . . . . . . . . . . . . . . . . . . . . . 61.3.1 Installing nJAMS Client for BW6 in “Console mode” . . . . . . . . . . . . . . . . . . . . 141.3.2 Installing nJAMS Client for BW6 in “Unattended mode” . . . . . . . . . . . . . . . . . . 14

1.4 Update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151.5 Uninstalling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161.6 Use nJAMS Client for BW6 with BWCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

1.6.1 Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181.6.2 Extend TIBCO BWCE base Docker image . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

2 Using nJAMS palette in TIBCO Business Studio 212.1 LogInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222.2 LogSuccess . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222.3 LogWarn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222.4 LogError . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232.5 SetContext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232.6 GetContext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232.7 Combination of log activities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232.8 Activity: Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242.9 Activity: Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242.10 Activity: Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262.11 Activity: Fault output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272.12 Run configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

3 Working with nJAMS Client for BW6 313.1 Tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

i

3.2 Extracts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323.3 Replay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

4 Reference: General properties 354.1 Communication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 354.2 Replay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384.3 Subagent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384.4 Inline Sub Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394.5 Use encrypted passwords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394.6 Memory Management / Sender Pool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394.7 Additional properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

5 Reference: Application based configuration 455.1 LogMode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455.2 LogLevel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455.3 Exclude . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465.4 Activity configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465.5 Recording . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465.6 Data Masking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465.7 Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

6 Reference: Configuration 496.1 Activating nJAMS Client for BW6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 496.2 Java System Properties Configuration Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . 506.3 Configuration by environment variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

7 Reference: Restrictions 53

ii

Integration Matters Documentation Documentation

Version 4.2

Released February 2020

Publication Mar 01, 2021

nJAMS Client for BW6 allows to monitor process transactions and its execution states of TIBCO BusinessWorks™6. nJAMS Client for BW6 thus achieves more visibility into the process platform while reducing the diagnosis andresolution efforts, hence reducing costs through the overall integration project lifecycle.

Installation: Installation guides you through installation and setup of nJAMS Client for BW6.

Using nJAMS palette: Using nJAMS palette in TIBCO Business Studio shows how to use nJAMS palette in TIBCOBusiness Studio.

Working with nJAMS Client for BW6: Working with nJAMS Client for BW6 describes basic topics to work withnJAMS Client for BW6.

Reference general properties: Reference: General properties lists and explains general nJAMS Client for BW6settings.

Reference application based properties: Reference: Application based configuration describes application basednJAMS Client for BW6 settings.

Reference client configuration: Reference: Configuration explains how to use different nJAMS Client for BW6configurations.

Reference restrictions: Reference: Restrictions lists known limitations of nJAMS Client for BW6.

nJAMS Client for BW6 1


2 nJAMS Client for BW6

CHAPTER 1

Installation

This document describes the process for installing and configuring nJAMS Client® for BW6 on a single computer.It is recommended to read the entire document before starting installation.

Chapter 1: Introduction gives an overview of the installation process and informs what is required for the installationprocess

Chapter 2: Preparing for installation walks through installing and configuring prerequisite software

Chapter 3: Installing and configuring nJAMS Client for BW6 explains the installation process of nJAMS Client forBW6 exemplary for Windows

Chapter 4: Update shows how to update an existing installation of nJAMS Client for BW6

Chapter 5: Uninstalling describes how to uninstall nJAMS Client for BW6 from your machine

Chapter 6: Use nJAMS Client for BW6 with BWCE guides through configuring nJAMS Client for BW6 with TIBCOBusinessWorks Container Edition

1.1 Introduction

nJAMS Client for BW6 comes with an installer for Linux and Windows. The installer is very well suited for a quickand easy installation on your machine. The installer also detects a previous version of nJAMS Client for BW6 andallows to upgrade to the most recent version. Furthermore, the installer is able to perform an unattended installation,which allows you to install nJAMS Client for BW6 silently by scripts.

Before you begin with the installation there are some preconditions, which must be checked in advance.

3


1.1.1 Supported software

For on-premise installations nJAMS Client for BW6 requires the following software installed and running:

• nJAMS Server® 4.4, 5.0, or higher

• TIBCO ActiveMatrix BusinessWorks™ 6.5, or 6.6, respectively TIBCO BusinessWorks™ Container Edition2.4, or 2.5

• TIBCO Enterprise Message Service™ 8.4, 8.5. If you want to use nJAMS Cloud, TIBCO EMS is not required.

If you are using nJAMS Cloud, you will need:

• a valid nJAMS Cloud instance

• TIBCO ActiveMatrix BusinessWorks™ 6.5, or 6.6, respectively TIBCO BusinessWorks™ Container Edition2.4, or 2.5

1.1.2 Hardware requirements

• Computer and processor: A computer with Intel x86-64 Bit, 2 GHz, multi-core recommended or divergentarchitecture with comparable performance characteristics.

• Memory: 2 GB RAM minimum

• Disc space: 100 MB free disc space minimum

1.1.3 Supported Platforms

Linux:

• Ubuntu Server 16.04, 18.04 on x86-64

• CentOS 6.x, 7.x on x86-64

• SUSE Linux Enterprise Server (SLES) 11.x, 12.x on x86-64

• Red Hat Enterprise Linux (RHEL) 5.x, 6.x, 7.x on x86-64

Windows:

• Microsoft Windows 7, 8, 10 64-bit on x86-64 including most recent updates

• Microsoft Windows Server 2008 R2, 2012, 2012 R2, 2016 64-bit on x86-64 including most recent updates

Others: Please contact Faiz & Siegeln Software GmbH

1.1.4 TIBCO EMS Client libraries

For using JMS Data Provider, nJAMS Client for BW6 requires TIBCO EMS 8.4, 8.5 client libraries. Please makesure, the TIBCO EMS Client libs are available.

1.1.5 Additional Software requirements

None.

4 Chapter 1. Installation


1.2 Preparing for installation

This chapter lists prerequisites for the istallation.

1.2.1 Preparing TIBCO BusinessWorks™ 6

nJAMS Client for BW6 requires TIBCO BusinessWorks 6 to be installed. For installing TIBCO BusinessWorks 6please follow the instructions of the installation manual that comes with TIBCO BusinessWorks 6.

1.2.2 Preparing TIBCO Enterprise Message Service™

nJAMS Client for BW6 requires TIBCO EMS for communication with on-premise nJAMS Server. TIBCO EMShas to be up and running and available on your network/subnet. nJAMS Client for BW6 uses several destinationson your TIBCO EMS Server for communication with with an nJAMS Server Instance. These destinations mustcorrespond to the Data Provider settings of your nJAMS Server Instance.

You need the following information about your TIBCO EMS Server:

• IP-Address / Servername, Port Number

• TIBCO EMS Account (Username, Password)

• Permissions send, receive on queues <prefix>.event, <prefix>.error, <prefix>.metrics

• Permissions publish, subscribe on topic <prefix>.commands

Tip: It is recommended to add an expiration time of e.g. 5 seconds to the <prefix>.commands destination.

nJAMS Client for BW6 requires to use JNDI, so the following information is required also:

• IP-Address / Servername, Port Number of JNDI server

• JNDI Account (Username, Password)

• Name of ConnectionFactory (e.q. QueueConnectionFactory)

1.2.3 Preparing network security

If you want to use the Cloud Data Provider of nJAMS Client for BW6, your network must allow HTTPS for externalcommunication. nJAMS Client for BW6 uses HTTPS transport based on certificates to communicate with yournJAMS Cloud Instance.

1.2.4 Preparing nJAMS Server®

nJAMS Client for BW6 requires a running nJAMS Instance, either on-premise (nJAMS Server), oder in the cloud(nJAMS Cloud). However, the nJAMS Instance is not required during installation of nJAMS Client for BW6, but atthe latest before the first use of nJAMS Client for BW6.

1.2. Preparing for installation 5


1.3 Installing and configuring nJAMS Client for BW6

Run the corresponding nJAMS Client for BW6 installer depending on your operating system:

For Unix/Linux platforms:

• nJAMSClientForBW6_unix_<version>.sh

For Windows:

• 64 Bit: nJAMSClientForBW6_windows-x64_<version>.exe

The following procedure shows by way of example an interactive installation on a Windows machine:

1. Start the installer executable nJAMSClientForBW6_windows-x64_<version>.exe.

2. Click Next on Welcome dialog:

3. Select your TIBCO_HOME directory either by selecting variable or by manually selecting TIBCOBusinessWorks 6 installation folder. Optionally you can backup existing config files from a previousinstallation of nJAMS Client for BW6. Make sure you have sufficient privileges to access thisdirectory. Click on Next to proceed:



4. Specify installation type:

1.3. Installing and configuring nJAMS Client for BW6 7


Standard installation Installs all components that are pre-selected in “custom installation”(see below)

Full installation Installs runtime and designtime components in parallel. This option is usefulfor development environments for example.

Custom installation Specify components to install separately:



nJAMS binaries Essential component for runtme and designtime. This option is madatory.

Default EMS configuration Creates a default JMS connection for TIBCO EMS. The defaultconfiguration is stored by default in <TIBCO_HOME>/bw/<VERSION>/config/njams/njams.properties. This file contains the default configuration of nJAMSClient for BW6. It is recommended to enter a default JMS connection during installa-tion. However, it is not required. You can enter a JMS connection afterwards by editingnjams.properties.

Enable replay plugin Select this option, if you want to use nJAMS Replay with nJAMSClient for BW6. nJAMS Replay requires a separate license.

Update log configuration Select this option, if you want the installer to update all appnodeson this machine in order to enable logging of nJAMS Client for BW6 for all appnodes.It is recommended to enable this option.

nJAMS palette Select this option, if you want to use nJAMS log activities in your BW6 pro-cesses. This option installs nJAMS palette in TIBCO BusinessWorks 6 runtime envi-ronment. If TIBCO Business Studio is installed on this machine, nJAMS palette is alsoinstalled in TIBCO Business Studio. If you do not want to use nJAMS palette and just usenJAMS in non-invasive mode, you can omit this option.

Update TIBCO Business Studio Workspace Select this option, if you want to enablenJAMS Client for BW6 in TIBCO Business Studio. This option is recommended, ifyou want to use nJAMS Client for BW6 in designtime. This option allows you to testyour processes in TIBCO Business Studio and see the results in nJAMS GUI.

If you have multiple workspaces, you can enable nJAMS Client for BW6 in all of themone after another.



5. Specify TIBCO EMS default configuration. Click Next to proceed:

JNDI URL Enter JNDI connection string. You can also enter fault tolerant connections, e.g.tibjmsnaming:://vslems01:7222,tibjmsnaming:://vslems02:7222.

Initial context factory Typically the JNDI context factory for TIBCO EMS is com.tibco.tibjms.naming.TibjmsInitialContextFactory.

JNDI user name Name of JNDI user.

JNDI password Password of JNDI user.

Connection factory Enter your connection factory here.

EMS destination prefix Enter your preferred prefix of destinations used by nJAMS Clientfor BW6. Make sure the destinations match the configuration of your nJAMS instance.

EMS authentication same as JNDI Select this option, if JNDI credentials are same as forEMS authentication. Otherwise, enter individual username/password for EMS authenti-cation.

6. Update appnodes. Enable nJAMS Client for BW6 for all appnodes available in the specified direc-tory and enter log level of nJAMS Client for BW6. Click Next to continue:



7. The summary shows the selected options. Click Next to continue:

8. Add nJAMS Client for BW6 to TIBCO Business Studio:



The installer adds nJAMS Client for BW6 to TIBCO Business Studio and creates a launch configurationfor the specified workspace.

Workspace location Enter directory to your workspace of TIBCO Business Studio.

nJAMS configuration file Confirm the default configuration file, or specify a different con-figuration file.

Launch configuration name Confirm the default launch configuration name, or enter a dif-ferent name.

Click Next to continue. The installer will update the workspace. If you have multiple workspaces, youare asked for another workspace you want to update. Click ‘Yes’ to enable nJAMS Client for BW6 foranother workspace. Click ‘No’, when you are done.

9. Finish installtion, close nJAMS Client for BW6 installer:



10. Restart appnodes and bwagents.

Verify the banner text information to make sure that nJAMS Client for BW6 has been started success-fully:

com.im.njams.sdk.Njams -→˓************************************************************com.im.njams.sdk.Njams - *** nJAMS SDK: Copyright (c) 2020 Faiz &→˓Siegeln Software GmbHcom.im.njams.sdk.Njams - ***com.im.njams.sdk.Njams - *** Version Info:com.im.njams.sdk.Njams - *** scmBranch: origin/mastercom.im.njams.sdk.Njams - *** cloudCommunicationVersion: 4.1com.im.njams.sdk.Njams - *** scmCommit:→˓08d4feef9f06bdad917f6a46daaa794b29cc2faecom.im.njams.sdk.Njams - *** sdkVersion: 4.1com.im.njams.sdk.Njams - *** clientVersion: 4.2.0com.im.njams.sdk.Njams - ***com.im.njams.sdk.Njams - *** Settings:com.im.njams.sdk.settings.Settings - *** njams.sdk.communication = CLOUDcom.im.njams.sdk.settings.Settings - *** njams.sdk.communication.cloud.→˓apikey = C:/TIBCO/njams/client/bw6/bjosyuh/api.keycom.im.njams.sdk.settings.Settings - *** njams.sdk.communication.cloud.→˓endpoint = ingest.test.njams.cloudcom.im.njams.sdk.settings.Settings - *** njams.sdk.configuration.file.→˓file = C:\TIBCO\bw\6.5\config\njams\BWEclipseDomain_BWEclipseAppSpace_→˓BWEclipseAppNode_Nested_DynSpawnSubProcesses.application.json

(continues on next page)



(continued from previous page)

com.im.njams.sdk.settings.Settings - *** njams.sdk.communication.cloud.→˓client.instanceId = bjosyuhcom.im.njams.sdk.settings.Settings - *** njams.sdk.communication.cloud.→˓client.privatekey = C:/TIBCO/njams/client/bw6/bjosyuh/8fc4b2ea16-private.→˓pem.keycom.im.njams.sdk.settings.Settings - *** njams.bw6.replayEnabled = falsecom.im.njams.sdk.settings.Settings - *** njams.bw6.config = C:/TIBCO/bw/→˓6.5/config/njams/njams.propertiescom.im.njams.sdk.settings.Settings - *** njams.sdk.configuration.→˓provider = filecom.im.njams.sdk.settings.Settings - *** njams.sdk.communication.cloud.→˓client.certificate = C:/TIBCO/njams/client/bw6/bjosyuh/8fc4b2ea16-→˓certificate.pemcom.im.njams.sdk.Njams -→˓************************************************************com.faizsiegeln.njams.bw6.ClientInstance - Replay functionality is disbled→˓by configuration.com.im.njams.sdk.communication.CommunicationFactory - Create Receiver CLOUDcom.im.njams.sdk.communication.cloud.CloudTopic - Creating→˓KeyStorePasswordPair from C:/TIBCO/njams/client/bw6/bjosyuh/8fc4b2ea16-→˓certificate.pem and C:/TIBCO/njams/client/bw6/bjosyuh/8fc4b2ea16-private.→˓pem.key

1.3.1 Installing nJAMS Client for BW6 in “Console mode”

On Unix/Linux systems you can either run installer in GUI mode or console mode. To run the installer in consolemode follow these steps:

1. Extract the content of the package to a temporary directory

2. Inside console window navigate to temporary directory

3. Execute nJAMSClientForBW6_unix_<version>.sh -console

4. Respond to the console window prompts step by step.

1.3.2 Installing nJAMS Client for BW6 in “Unattended mode”

The unattended mode of the installer allows to run the installation automatically by using pre-defined settings. An unat-tended installation has to refer to a response var file that includes pre-defined installation settings. It is recommendedto use a response var file from an attended installation as a template and adapt the settings in this file accordingly. Aresponse var file is generated obligatory and resides in <installationfolder>/.install4j/.

Run installer in Unattended Mode as follows:

nJAMSClientForBW6_unix_<version>.sh -console -q -varfile response.varfile

Please find below a sample response.varfile that can be adapted according to your requirements:

# install4j response file for nJAMS Client for BW6 4.2.0connectionFactory=ConnectionFactorydirDomains=/opt/tibco/bw/6.6/domainsdoBackup$Boolean=falseemsDestination=queue.njamsemsPwd.encoded=emsUser=njams





jndiContextFactory=com.tibco.tibjms.naming.TibjmsInitialContextFactoryjndiPwd.encoded=kZWekow\=jndiUrl=tibjmsnaming\://vslems01\:7222jndiUser=njamslogLevelSelectIndex$Integer=0radioSelect=dirrepeatJndiPwd.encoded=kZWekow\=repeatPwd.encoded=sameAuth$Boolean=trueselectedIndex$Integer=-1sys.adminRights$Boolean=falsesys.component.client$Boolean=truesys.component.defaultConfig$Boolean=truesys.component.logging$Boolean=truesys.component.palette$Boolean=truesys.component.replayEnabled$Boolean=falsesys.component.studio$Boolean=falsesys.installationDir=/opt/tibco/bw/6.6sys.installationTypeId=1092sys.languageId=entgtDir=/opt/tibco/bw/6.6tibcoHome=/opt/tibcotra.njams.config=\ -Dnjams.bw6.config\="/opt/tibco/bw/6.6/config/njams/njams.→˓properties"tra.weaver=\ -javaagent\="/opt/tibco/bw/6.6/system/lib/aspectjweaver.jar"

1.4 Update

Use nJAMS Client for BW6 installer to update an existing installation. nJAMS Client for BW6 installer detectsan existing installation automatically and suggests to perform an update. Performing an update also allows to addadditional features to the current installation of nJAMS Client for BW6.

Before you update an nJAMS Client for BW6 installaton, stop all running appnodes and bwagents on this machine.If applicable, also close TIBCO Business Studio.

Follow the update procedure:

1. Start the installer.

2. Enter existing target of the TIBCO BusinessWorks 6 installation.

3. If the installer detects an existing installation of nJAMS Client for BW6, you are asked to perform an updateor to change the existing installation:

Select Update, if you want to update an existing installation. nJAMS Client for BW6 installer willperform an update of the installed features of nJAMS Client for BW6.

Select Configure, if you want to perform an update and change the existing installation of nJAMSClient for BW6, respectively add additional features.

1.4. Update 15


You should also use Configure for updating your TIBCO Business Studio Workspace(s). SelectInstallaton Type “Custom installation” and choose option “Update Business Studio Workspace”.Please note that in previous releases of nJAMS Client for BW6 it was required to use the follow-ing start option: -javaagent:C:/TIBCO/bw/6.x/system/lib/aspectjweaver.jar.From release 4.2 this start option is no longer valid and must not be used! When you update yourWorkspace(s), this start option will be removed automatically by nJAMS installer. In case you havea Workspace that is not updated, your TIBCO BusinessWorks 6 application might not start properly.You have to remove this entry manually from Run Configuration:

4. Restart appnodes and bwagents. If applicable, restart TIBCO Business Studio.

1.5 Uninstalling

Uninstalling nJAMS Client for BW6 removes all nJAMS components from TIBCO BusinessWorks 6.

Caution: If you instrumented your BW6 applications with nJAMS activities, you have to update the processdesign and remove nJAMS activities from all applications before you uninstall nJAMS Client for BW6. YourBW6 applications will fail to start, when nJAMS Client for BW6 has been uninstalled, but your BW6 applicationsstill contain nJAMS activities.

Before you uninstall nJAMS Client for BW6, stop all running appnodes and bwagents on this machine. If applicable,also close TIBCO Business Studio.

Follow the uninstallation procedure:

1. Start uninstaller from <TIBCO_HOME>/bw/6.x

2. Click Next on Welcome dialog:



3. Select delete to remove existing configuration files. Click on Next to start uninstalling nJAMSClient for BW6:

4. Click Finish to close uninstaller:

1.5. Uninstalling 17


5. Restart appnodes and bwagents.

1.6 Use nJAMS Client for BW6 with BWCE

TIBCO BusinessWorks Container Edition is a Cloud Native Application framework that runs within containers.nJAMS Client for BW6 can be configured to run within a container next to TIBCO BusinessWorks Container Edition.

1.6.1 Prerequisites

The following prerequisites are required:

• TIBCO BusinessWorks Container Edition base Docker Image including your BWCE application. Please referto TIBCO documentation for creating a base Docker image.

• nJAMS BWCE package. Enter Integration Matters Download Portal to download nJAMS BWCEpackage file. nJAMS BWCE package is part of nJAMS Client for BW6 download package, seenjams-client-bw6-installer-<VERSION>-bwce-assembly.zip.

1.6.2 Extend TIBCO BWCE base Docker image

The TIBCO BWCE base Docker image can be extended to support nJAMS Client for BW6 as follows:

1. Download nJAMS BWCE package file.

2. Copy nJAMS BWCE package file to a temporary folder and unzip the package for example into sub foldernjams.



3. If not included in your base image, add TIBCO EMS driver files (tibjms.jar, and tibjmsadmin.jar)to the nJAMS BWCE package by putting both files into the njams/jars folder.

4. Adapt njams/conf/njams-bw6.properties according to your connection requirements.

5. In the temporary folder create a Dockerfile that copies the nJAMS BWCE package file into the base Dockerimage. Adapt the reference to your base image as needed.

FROM tibco/bwce:latestADD ./njams/ /resources/addons/thirdparty-installs/njams

6. Build the Docker image by running the following command from the temporary folder:

docker build -t <YOUR-TAG> .

1.6. Use nJAMS Client for BW6 with BWCE 19



CHAPTER 2

Using nJAMS palette in TIBCO Business Studio

nJAMS Client for BW6 is represented by a full featured palette in TIBCO Business Studio. The nJAMS paletteconsists of various activities that generates log events of individual severities.

A TIBCO BusinessWorks 6 developer can use nJAMS activities within a process definition in order to send technicalor functional log events at particular stages of the process. This chapter explains available nJAMS activities anddemonstrates how to use nJAMS activities in context with the process design.

When nJAMS palette is selected for installation, the installer installs nJAMS activities in TIBCO Business Studio. Youcan use nJAMS activities as usual, just drag and drop nJAMS activities to your process design, and optionally do themappings.

21


2.1 LogInfo

The LogInfo activity is used to send a log event with status INFO.

Since INFO is a neutral severity level, this status is typically used to indicate a specific milestone of your process hasbeen reached, without making a statement whether the execution was erroneous or successful so far.

2.2 LogSuccess

The LogSuccess activity is used to send a log event with status SUCCESS.

A SUCCESS represents a severity level that is used to indicate a successful finish of an activity or an entire processexecution.

In contrast to LogInfo the LogSuccess activity indicates an explicit successful state.

In the world of nJAMS a LogSuccess overrules a previous LogWarn or LogError status related to a process evaluation.For example, an ERROR event was sent during the process execution, but at the end the entire process could be turnedinto success by sending a SUCCESS event. In this scenario the process execution is evaluated as “Success with Error”.

2.3 LogWarn

The LogWarn activity is used to send a log event with status WARNING.

A WARNING represents a status that is typically used to indicate a situation that is undesirable or unexpected, but notnecessarily erroneous.

Furthermore, LogWarn can also used to indicate a functional failure, but not a technical error. For example, if anincoming message does not contain the expected content, but does not cause a schema validation error, a LogWarn canindicate bad data quality, respectively wrong functional behavior.

22 Chapter 2. Using nJAMS palette in TIBCO Business Studio


2.4 LogError

The LogError activity is used to send a log event with status ERROR.

An ERROR represents a status that is used to indicate a technical error.

You can map an individual event code and event message to LogError also. This can be useful, if you want to searchfor your specific event codes within nJAMS

2.5 SetContext

The setContext activity is used to set the nJAMS log context from the current process instance. No event will be send.

The setContext activity is used to set a different nJAMS log context. For example, if you want to overwrite thecorrelation id in order to correlate multiple dependent process instances by using the same correlation log id, youwould use setContext.

Each nJAMS LogEvent activity (LogInfo, LogSuccess, LogWarn, LogError) lets you set the current nJAMS log con-text, but it is not always desired to send a log event, when you only want to set context information.

2.6 GetContext

The getContext activity is used to get nJAMS log context from the current process instance. No event will be send.

Each nJAMS LogEvent activity (LogInfo, LogSuccess, LogWarn, LogError) provides you with the current nJAMSlogcontext, but it is not always desired to send a log event when you only want to retrieve the context information.

2.7 Combination of log activities

Log activities may be combined within a TIBCO BusinessWorks 6 process to indicate different milestones and theirstatus. The severity levels are as follows:

2.4. LogError 23


• 0: Info

• 1: Success

• 2: Warning

• 3: Error

The following table shows the possible combinations and how the overall status of the process will be represented innJAMS UI:

2.8 Activity: Configuration

You can change the name of a nJAMS activity and add a meaningful description; see tab “General”, respectively“Description”.

2.9 Activity: Input

The input structure of nJAMS activities allows you to map additional content to nJAMS. Since all elements of theinput structure are optional it is not required to provide input for any field.



The following fields are available:

2.9. Activity: Input 25


Element Datatypemaxlength

Description

EventMs-gCode

string 1000byte1

User defined log message code id.

EventMsg string 1000byte1

User defined log message name such as description of the event, postition of theevent, etc.

Payload string un-lim-ited2

Ths is the payload message transported by the process.

Stack-trace

string un-lim-ited2

The stacktrace object contains technical error information. This element is especiallysuitable for activity LogError.

At-tributes

This element contains information that can be mapped individually. Typically at-tributes contain business related content like order number, customer name, etc.

Attribute This is the repeating element.Name string 1000

byte1The name of an attribute describes meaning of the content.

Type string 100byte1

You can declare a specific type of the attribute like “string”, “number”, “date”. Thiselement is optional. If not provided, a string will be assumed.

value string 4000byte1

The attribute value contains the data of the attribute. For example if attribute type is“OrderId”, a valid content might be “A4711”.

LogCon-textCorre-lation-LogID

string 1000byte1

This Id is used by nJAMS to correlate multiple log entries to a log entry chain.

Parent-LogID

string 1000byte1

This ID allows a hierarchical composition of log entries. The ParentLogID is theLogID of the process instance that calls the current process.

External-LogID

string 1000byte1

This ID is a user defined identifier.

Busi-nessSer-vice

string 1000byte1

Name of the Business Service that is represented by one or more technical processes.

Busines-sObject

string 1000byte1

Name of the Business Object that is delivered by one or more technical processes.

2.10 Activity: Output

The output structure contains information about the current log context of nJAMS.

1 maximum size for singlebyte charactersets, such as UTF-8 or Latin1. For multibyte charactersets, such as UTF-16 or UTF-32, the maximumlength must be divided by the amount of bytes required to encode a single character.

2 there is no practical limit, though the underlying messaging system (JMS) or persistence layer may have a limitation.



The following fields are available:

Ele-ment

DatatypeDescription

Log-Con-text

This element contains information about the current log context of nJAMS.

LogID string LogID is a unique identifier that identifies a log entry with regards to a single process execution.Each single process execution is represented in nJAMS by a unique Log ID. The main view innJAMS UI represents a list of log entries, respectively LogIDs.

Au-dit-Sta-tus

in-te-ger

The audit status of an activity. The following values represent the AuditStatus: 0: LogInfo, 1:LogSuccess, 2: LogWarning, 3: LogError

The other attributes and elements are the same as on the Input tab.

2.11 Activity: Fault output

The fault output is not used by nJAMS. Any error that occurred inside of a nJAMS activity will be logged in the BWeninge log file, respectively in the console of TIBCO Business Studio console.

2.12 Run configurations

Run your process(es) in TIBCO Business Studio by “Run configurations. . . ” or “Debug configurations. . . ”. Select“BWApp_with_nJAMS” to run your process(es) with nJAMS and see the reasults in nJAMS GUI.

2.11. Activity: Fault output 27


Note: If you updated from previous version of nJAMS Client for BW6, you might have to remove outdated -javaagent setting in your TIBCO Business Studio workspace configuration. Please check “Run Configurations”,“BWApp_with_nJAMS”, tab “Arguments”, and remove setting -javaagent:C:/TIBCO/bw/6.x/system/lib/aspectjweaver.jar, if applicable. In case you updated your Workspace with nJAMS installer, this settingis removed automatically, no action has to be taken.



2.12. Run configurations 29



CHAPTER 3

Working with nJAMS Client for BW6

This chapter gives a basic description of how to use nJAMS Client for BW6 with TIBCO BusinessWorks 6.

3.1 Tracing

Enable Tracing allows you to monitor more details with regards to a specific activity. You can use nJAMS UI toconfigure Tracing, e.g.:

31


Alternatively you can modify nJAMS Client for BW6 properties file <your_appnode>.json in<TIBCO_HOME>/bw/<VERSION>/config/njams and add or update Tracing without using the User Interface.This is an example for enabling Tracing:

">bw65_domain>bw65_appspace>bw65_appnode>tibco.bw.sample.core.soa.CallProcess.→˓application>tibco/bw/sample/core/soa/callprocess/MainProcess>" : {"logLevel" : "INFO","exclude" : false,"activities" : {"ClassificationByGenre" : {

"tracepoint" : {"starttime" : "2018-11-11T08:00:00.000","endtime" : "2018-11-11T09:00:00.000","iterations" : 0,"deeptrace" : false

}}

},"recording" : true

}

Note: After modifying nJAMS Client for BW6 properties file, you have to restart BW6 AppNode to make thesettings become effective.

3.2 Extracts

An Extract is a non-invasive way to add nJAMS events with regards to specific activities. You can use nJAMS UI toconfigure an Extract:

32 Chapter 3. Working with nJAMS Client for BW6


The following dialog allows you to configure an Extract:

You can also modify nJAMS Client for BW6 properties file <your_appnode>.json in <TIBCO_HOME>/bw/<VERSION>/config/njams and add or update Extracts without using the User Interface.

This is an example for creating an Extract:

"processes" : {">bw65_domain>bw65_appspace>bw65_appnode>tibco.bw.sample.core.soa.CallProcess.

→˓application>tibco/bw/sample/core/soa/callprocess/MainProcess>" : {"logLevel" : "INFO","exclude" : false,"activities" : {

"ClassificationByGenre" : {"extract" : {"name" : "ExtractruleType","extractRules" : [ {

"attribute" : "MovieName","attributeType" : "attribute","ruleType" : "xpath","rule" : "//*:movieName","inout" : "in"

} ]}

}},"recording" : true

}

Note: After modifying nJAMS Client for BW6 properties file, you have to restart BW6 AppNode to make thesettings become effective.

3.3 Replay

nJAMS Replay extends the capabilities of nJAMS by not only monitoring process executions, but also by restartingprocess executions. nJAMS Replay allows you to record data of a process execution and replay that process with the

3.3. Replay 33


same or modified data.

nJAMS Client for BW6 comes with built-in nJAMS Replay capabilities.

In order to make use of nJAMS Replay with nJAMS Client for BW6 you have to enable nJAMS Replay on Clientside. In addition, you need nJAMS Replay Server plugin for nJAMS Server.

In nJAMS UI you can triggr a Replay by the following dialog:

To enable nJAMS Replay in nJAMS Client for BW6 you have to set njams.bw6.replayEnabled=true innjams.properties.

34 Chapter 3. Working with nJAMS Client for BW6

CHAPTER 4

Reference: General properties

The basic configuration of nJAMS Client for BW6 takes place in config file njams.properties. This configu-ration file resides in <TIBCO_HOME>/bw/<VERSION>/config/njams. Use an editor of your choice and editnjams.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.

4.1 Communication

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

njams.sdk.communication Select type of communication with nJAMS Server, respectively nJAMSCloud:

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

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

In case you are using JMS:

njams.sdk.communication.jms.connectionFactory Sets the connection factory, for example “Connec-tionFactory”.

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

njams.sdk.communication.jms.password The JMS user’s password.

35


njams.sdk.communication.jms.destination The JMS destination name prefix. The prefix will be ex-tended with .event for event messages send by nJAMS Client for BW6 and .command formessages 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 tosend commands from nJAMS Server to nJAMS Client for BW6. This setting is optional and onlyused, 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:

## SDK configuration# Communication settingsnjams.sdk.communication=JMS

# JMS settingsnjams.sdk.communication.jms.connectionFactory=ConnectionFactorynjams.sdk.communication.jms.username=njamsnjams.sdk.communication.jms.password=njamsnjams.sdk.communication.jms.destination=njams.endurance

# JNDI settingsnjams.sdk.communication.jms.java.naming.factory.initial=com.tibco.tibjms.naming.→˓TibjmsInitialContextFactorynjams.sdk.communication.jms.java.naming.security.principal=njamsnjams.sdk.communication.jms.java.naming.security.credentials=njamsnjams.sdk.communication.jms.java.naming.provider.url=tibjmsnaming://vslems01:7222

In case you are using JMS with SSL:

njams.sdk.communication.jms.com.tibco.tibjms.ssl.vendor Specify j2se for JSSE SSL vendor, oruse entrust6 for Entrust SSL vendor.

njams.sdk.communication.jms.com.tibco.tibjms.ssl.verify_host Indicates whether or not host shouldbe verified.

njams.sdk.communication.jms.com.tibco.tibjms.ssl.trace true enables ssl trace, use false to dis-able trace.

njams.sdk.communication.jms.com.tibco.tibjms.ssl.trusted_certs Absolute path to directory or filewith trusted certificate(s).

njams.sdk.communication.jms.com.tibco.tibjms.ssl.expected_hostname Optional. The expectedname 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 pro-tocol to use in Tibjms JNDI lookups. Use security protocol ssl.

njams.sdk.communication.jms.com.tibco.tibjms.naming.ssl_trusted_certs Absolute path to direc-tory or file with trusted certificate(s).

njams.sdk.communication.jms.com.tibco.tibjms.naming.ssl_verify_host Indicates whether or nothost should be verified.

36 Chapter 4. Reference: General properties


njams.sdk.communication.jms.com.tibco.tibjms.naming.ssl_verify_host_name Indicates whether ornot the name of the host should be verified.

njams.sdk.communication.jms.com.tibco.tibjms.naming.ssl_expected_hostname Specify the com-mon name in the server certificate in Tibjms JNDI lookups.

njams.sdk.communication.jms.com.tibco.tibjms.naming.ssl_identity Specify the client-side identityin Tibjms JNDI lookups.

njams.sdk.communication.jms.com.tibco.tibjms.naming.ssl_password Specify the password for theprivate 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=ConnectionFactorynjams.sdk.communication.jms.connectionFactory=SSLConnectionFactorynjams.sdk.communication.jms.username=adminnjams.sdk.communication.jms.password=adminnjams.sdk.communication.jms.destination=njams

# ssl settingsnjams.sdk.communication.jms.com.tibco.tibjms.ssl.vendor=j2senjams.sdk.communication.jms.com.tibco.tibjms.ssl.verify_host=disablednjams.sdk.communication.jms.com.tibco.tibjms.ssl.trace=truenjams.sdk.communication.jms.com.tibco.tibjms.ssl.trusted_certs=C\:/tibco/ems/8.5/→˓samples/certs/server_root.cert.pemnjams.sdk.communication.jms.com.tibco.tibjms.ssl.expected_hostname=server

# JNDI settingsnjams.sdk.communication.jms.java.naming.factory.initial=com.tibco.tibjms.naming.→˓TibjmsInitialContextFactorynjams.sdk.communication.jms.java.naming.security.principal=adminnjams.sdk.communication.jms.java.naming.security.credentials=adminnjams.sdk.communication.jms.java.naming.provider.url=tibjmsnaming://vswtibco01:7242njams.sdk.communication.jms.com.tibco.tibjms.naming.security_protocol=sslnjams.sdk.communication.jms.com.tibco.tibjms.naming.ssl_trusted_certs=C\:/tibco/ems/8.→˓5/samples/certs/server_root.cert.pemnjams.sdk.communication.jms.com.tibco.tibjms.naming.ssl_verify_host=falsenjams.sdk.communication.jms.com.tibco.tibjms.naming.ssl_verify_host_name=falsenjams.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 CLOUD:

The following properties have to be configured to allow nJAMS Client for BW6 to create a secure connection viahttps to a designated nJAMS Cloud instance. You can find the configuration of the Cloud Data Provider within theInstance 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 isingest.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.

4.1. Communication 37


Sample configuration of a Cloud Data Provider:

## SDK configuration# Communication settingsnjams.sdk.communication=CLOUD

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

4.2 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.

4.3 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 orip-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 pro-cess instrumentation to be activated in TIBCO BusinessWorks 6. This switch enables/disables acti-vation of process instrumentation in TIBCO BusinessWorks 6.

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

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

Sample settings for Subagent:

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



4.4 Inline Sub Processes

In TIBCO BusinessWorks 6 non-spawned sub processes always create new jobs and are therefore represented innJAMS by separate process instances. Since these process instances are correlated with the main process, whichcalls the sub process, the Result list of correlated entries may get very long. Furthermore, the number of nJAMS logmessages 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 pro-cesses”. Inline sub processes means, nJAMS Client for BW6 will NOT create a separate process instance for anon-spawned sub process call. This behavior is therefore similar to the behavior of nJAMS Client for BW in connec-tion with TIBCO BusinessWorks 5.

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

njams.bw6.inlineSubProcesses Enables/disables inline sub processes.

true enables inline sub processes.

false disables inline sub processes (default).

4.5 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 asfollows:

Assume, the password of your JMS account is foo:

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

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

3. Restart AppNode to make change effective

4.6 Memory Management / Sender Pool

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

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

njams.client.sdk.sharedcommunications This option is available since |BW6| release 4.2.2.

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

4.4. Inline Sub Processes 39


true Use a single shared connection pool for communications.

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

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 bediscarded (default).

discard will discard the message. When using this option make sure to configuremaxqueuelength and maxsenderthreads reasonably so that the client can handle messagebursts 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 queuelength is below threshold.

njams.client.sdk.maxqueuelength Maximum internal queue size, before discardPolicy is applied. Enterany integer value > 0. Default is 8.

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

njams.client.sdk.maxsenderthreads This property configures maximum sender threads for the selectedimplementation. Default is 8.

njams.client.sdk.minsenderthreads This property configures minimum sender threads for the selectedimplementation. Default is 1.

njams.client.sdk.senderthreadidletime Idle connection timeout to close and remove connections inmsec. 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, aninstant 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=5242880njams.client.sdk.maxqueuelength=8njams.client.sdk.discardpolicy=none

4.7 Additional properties

njams.bw6.start This setting allows disabling nJAMS Client for BW6 completely.

true nJAMS Client for BW6 is enabled (default).

false nJAMS Client for BW6 is disabled.

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 ofyour TIBCO BusinessWorks 6 environment. Please note that also no metrics data is being sent ofdomains, which are not listed.

By default, this property is empty. When this property is empty, respectively unused, all domainsare 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 applicationsthat should not be monitored by nJAMS Client for BW6.

By default, this property is empty. When this property is empty, respectively unused, no applicationis 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.client.sdk.deprecatedsubprocesspathfield nJAMS Client for BW6 uses a new way in handlingsub process calls. The more efficient approach of nJAMS Client for BW6 requires nJAMS Server5.1 or higher. In order to be compatible with prior releases of nJAMS Server, this setting has beenintroduced with release 4.2 of nJAMS Client for BW6.

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

false disables compatibility mode (default). Use this setting or omit it, when you use nJAMSServer 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 processespassword information. By default, the nJAMS UI provides Trace Data including the password in-formation in plain text. To prevent password information from being shown in plain text, you canuse 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 con-figuration file, see Appendix B.

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

4.7. Additional properties 41


false disables data masking.

njams.sdk.datamasking.regex.<your-regex-name> Use a regular expression to specify a pattern fordata 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 errorevents.

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

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

njams.sdk.truncateActivitiesLimit When setting this option to a positive number, nJAMS Client forBW6 will stop sending detailed activity- and transition information to the server once that numberof activities has been reached. The client will however continue sending job status- and event infor-mation. 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 differentsettings 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 forBW6 will not send detailed activity- and transition information for job instances that completed suc-cessfully. The client will however send job status- and event information. Job instances completingwith any other status than success are not affected by this setting. In nJAMS Server you will notsee transitions between activities for such job instances. This setting has only limited effect on jobinstances 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 transac-tions). 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 This option is available since |BW6| release 4.2.2.

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

Each process instance that is monitored by nJAMS Client for BW6 and does not make any progressin TIBCO BusinessWorks 6 for the configured amount of time (in seconds) will be unconditionallyremoved 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 negativevalue for disabling (default).

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

4.7. Additional properties 43



CHAPTER 5

Reference: Application based configuration

The application related configuration of nJAMS Client for BW6 takes place in a separate nJAMSproperties file for each AppNode. These property files reside in <TIBCO_HOME>/bw/<VERSION>/config/njams. Typically the name of the application related nJAMS property file followsthis pattern: <DOMAIN>_<APPSPACE>_<APPNODE>_<APPLICATION>.application.json,e.g. bw6_endurance_bw6_endurance_appspace_bw6_endurance_node1_HFMService.application.json You can edit the properties file according to your needs.

This is the reference of available application related nJAMS Client for BW6 properties.

Note: Any change in this configuration file requires a re-start of the BW6 AppNode, respectively of the BW6application.

5.1 LogMode

logMode Controls operation mode of the nJAMS Client for BW6:

complete nJAMS Client for BW6 will monitor all processes that are executed within the TIBCOBusinessWorks 6 application (default).

exclusive nJAMS Client for BW6 will only monitor processes, that executes an nJAMS Clientfor BW6 activity, respectively executes an Extract. All other processes will be ignored.

none the nJAMS Client for BW6 functionality is completely disabled.

5.2 LogLevel

Loglevel controls the log level of an individual application.

logLevel Valid values for Loglevel can be:

45


0: Info (default)

1: Success

2: Warning

3: Error

5.3 Exclude

This setting allows to exclude individual processes from being monitored by nJAMS.

exclude Turn on/off exclujding processes.

true excludes process.

false do not exclude process (default).

5.4 Activity configuration

Contains Tracing and Extract configuration for activities.

For example:

"activities" : {"ClassificationByGenre" : {

"tracepoint" : {"starttime" : "2018-11-11T08:00:00.000","endtime" : "2018-11-11T09:00:00.000","iterations" : 0,"deeptrace" : false}

}

5.5 Recording

Enables/disables recording data for nJAMS Replay. This setting can be applied to the entire application or to indi-vidual processes.

recording Turn on/off recording.

true enables recording (default).

false disables recording.

5.6 Data Masking

Data Masking allows you to mask particular parts of Trace Data, which should remain confidential. Assume you haveTracing enabled for an activity that processes password information. By default, the nJAMS UI provides Trace Dataincluding the password information in plain text. To prevent password information from being shown in plain text,you can use Data Masking. This setting can be applied to the entire application or to individual processes.

46 Chapter 5. Reference: Application based configuration


Note: Starting with this release of nJAMS Client for BW6, Data Masking is moved from application based config-uration file to nJAMS Client for BW6 general properties file. However, for compatibility reason the Data Maskingconfiguration here is still considered.

dataMasking Enter a regular expression. For example, the following regular expression replaces anyinformation that matches XML tag “Password” in Trace Data with an asterisk character (“*”):

"dataMasking" : [ "<Password>(\\p{Alpha}|/|\\p{Digit})*</Password>" ]

5.7 Example

This is an example of an application based nJAMS Client for BW6 properties file:

{"logMode" : "COMPLETE","processes" : {

">bw65_domain>bw65_appspace>bw65_appnode>tibco.bw.sample.core.soa.CallProcess.→˓application>tibco/bw/sample/core/soa/callprocess/MainProcess>" : {

"logLevel" : "INFO","exclude" : false,"activities" : {

"ClassificationByGenre" : {"tracepoint" : {

"starttime" : "2018-11-11T08:00:00.000","endtime" : "2018-11-11T09:00:00.000","iterations" : 0,"deeptrace" : false

}"extract" : {

"name" : "ExtractruleType","extractRules" : [ {"attribute" : "MovieName","attributeType" : "attribute","ruleType" : "xpath","rule" : "//*:movieName","inout" : "in"} ]

}}

},"recording" : true},">bw65_domain>bw65_appspace>bw65_appnode>tibco.bw.sample.core.soa.CallProcess.

→˓application>tibco/bw/sample/core/soa/callprocess/OtherMoviesList>" : {"logLevel" : "INFO","exclude" : false,"activities" : {

"Start" : {"extract" : {

"name" : "ExtractruleType","extractRules" : [ {"attribute" : "Movie","attributeType" : "attribute",


5.7. Example 47



"ruleType" : "xpath","rule" : "//*:movieName","inout" : "in"} ]

}}

},"recording" : true}

},"dataMasking" : [ ],"recording" : true}

48 Chapter 5. Reference: Application based configuration

CHAPTER 6

Reference: Configuration

All settings of the nJAMS Client for BW6 can be made at different locations. Depending on where the settings aremade, they may overwrite the settings in other locations.

The settings can be made in the following locations:

1. nJAMS Client for BW6 properties file (njams.properties)

2. Environment variables (will override settings in properties file)

3. Java system properties (will override settings in environment variables)

Note: In all cases, settings are case-sensitive.

6.1 Activating nJAMS Client for BW6

When nJAMS Client for BW6 client is installed, it requires specifying a reference to its configuration file usingthe njams.bw6.config=<path-to-properties> parameter. This setting can be given either as Java systemproperty, or as environment variable (from release 4.2.3).

If the njams.bw6.config setting is not specified, or the referenced file is not found, nJAMS Client for BW6 willnot start and an according error message is logged.

nJAMS Client for BW6 can be temporarily disabled by adding the following setting to either the Java system prop-erties, or as environment variable (from release 4.2.3): njams.bw6.start=false

Note: Though it is actually possible to completely configure the client via Java system proprties and/or environmentvariables, it is anyway necessary to specify a configuration file as explained above. The settings in this file areoverwritten by the given Java system properties or environment variables.

49


6.2 Java System Properties Configuration Hierarchy

TIBCO BusinessWorks 6 uses a top-down hierarchy of TRA files for configuring the Java environments of all nodes ina TIBCO BusinessWorks 6 installation. Any setting in a parent is inherited by its children, and any child can overrideits parent configuration. Please refer to TIBCO Product Documentation for more information.

In general, if you configure a parameter in bwappnode.tra, that parameter is inherited by all its children files(AppSpace.tra, AppNode.tra) unless the children override the configuration.

Java system properties can be added by extending the java.extended.properties setting in each TRA file.Settings given as Java system properties need to be prefixed with -D, for example:

java.extended.properties=-Xmx1024m -Xms128m -XX:+HeapDumpOnOutOfMemoryError-Dnjams.bw6.config=/opt/tibco/bw/6.6/config/njams/njams.properties

Note: When running the nJAMS Client for BW6 installer, the TIBCO BusinessWorks 6 home is scanned for allAppNode configuration TRA files and the -Dnjams.bw6.config=njams.properties setting is appended toeach active java.extended.properties setting. If you afterwards manually add (or uncomment) the java.extended.properties setting in any TRA file in the configuration hierarchy, you need to make sure to includethe -Dnjams.bw6.config=njams.properties in this entry also. Otherwise nJAMS Client for BW6 willno longer start for the related nodes.

Java System Properties in TIBCO Business Studio

At design-time you can specify Java system properties at Run configuration of TIBCO Business Studio in tab Argu-ments, by adding to the VM arguments field:

50 Chapter 6. Reference: Configuration

https://docs.tibco.com/products/tibco-activematrix-businessworks-6-6-1


Note: It is recommended to create a copy of the existing BWApplication run configuration and add the nJAMSconfiguration to that copy, because in some cases, TIBCO Business Studio automatically resets its default run config-uration.

6.3 Configuration by environment variables

Use environment variables to override or complete settings in the properties file.

For example, if you want to define an individual event destination for nJAMS Client for BW6, you can add the en-vironment variable njams.sdk.communication.jms.destination in the operating system. Add a systemenvironment variable in Windows as follows:

Windows

A new environment variable is now available:

6.3. Configuration by environment variables 51


Linux

On Linux, use the export command for defining environment variable, for instance: export njams.sdk.communication.jms.destination=njams.bw6

Note: To make environment variables effective you have to restart TIBCO BW6 AppNode, respectively TIBCOBusiness Studio.

52 Chapter 6. Reference: Configuration

CHAPTER 7

Reference: Restrictions

Conversations Conversations in TIBCO BusinessWorks 6 are not supported.

Replay for 3rd party palettes Replay function may be restricted for third party palettes and activities.

Do not exclude process diagram information in EAR file nJAMS Client for BW6 requires processdiagram information during packaging not to be excluded, exactly as it is specified by default inTIBCO BusinessWorks 6.

Since TIBCO BusinessWorks 6.6 it is possible to exclude process diagram information, when cre-ating the EAR file. However, this setting would prevent nJAMS Client for BW6 from monitoringTIBCO BusinessWorks 6 application. It is therefore necessary to include process diagram informa-tion in the EAR, as usual.

53

Documents

Integration Matters Documentation Documentation