TIBCO ActiveMatrix BusinessWorks Process Monitor Client for BW. User Guide

Transcription

1 TIBCO ActiveMatrix BusinessWorks Process Monitor Client for BW User Guide Software Release Published: May 2013

2 Important Information SOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCH EMBEDDED OR BUNDLED TIBCO SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY (OR PROVIDE LIMITED ADD-ON FUNCTIONALITY) OF THE LICENSED TIBCO SOFTWARE. THE EMBEDDED OR BUNDLED SOFTWARE IS NOT LICENSED TO BE USED OR ACCESSED BY ANY OTHER TIBCO SOFTWARE OR FOR ANY OTHER PURPOSE. USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS AND CONDITIONS OF A LICENSE AGREEMENT FOUND IN EITHER A SEPARATELY EXECUTED SOFTWARE LICENSE AGREEMENT, OR, IF THERE IS NO SUCH SEPARATE AGREEMENT, THE CLICKWRAP END USER LICENSE AGREEMENT WHICH IS DISPLAYED DURING DOWNLOAD OR INSTALLATION OF THE SOFTWARE (AND WHICH IS DUPLICATED IN LICENSE FILE) OR IF THERE IS NO SUCH SOFTWARE LICENSE AGREEMENT OR CLICKWRAP END USER LICENSE AGREEMENT, THE LICENSE(S) LOCATED IN THE LICENSE FILE(S) OF THE SOFTWARE. USE OF THIS DOCUMENT IS SUBJECT TO THOSE TERMS AND CONDITIONS, AND YOUR USE HEREOF SHALL CONSTITUTE ACCEPTANCE OF AND AN AGREEMENT TO BE BOUND BY THE SAME. This document contains confidential information that is subject to U.S. and international copyright laws and treaties. No part of this document may be reproduced in any form without the written authorization of TIBCO Software Inc. TIBCO, The Power of Now, TIBCO ActiveMatrix BusinessWorks, TIBCO Rendezvous, TIBCO Administrator, TIBCO Enterprise Message Service, TIBCO InConcert, TIBCO Policy Manager, and TIBCO Hawk are either registered trademarks or trademarks of TIBCO Software Inc. in the United States and/or other countries. EJB, Java EE, J2EE, and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries. All other product and company names and marks mentioned in this document are the property of their respective owners and are mentioned for identification purposes only. THIS SOFTWARE MAY BE AVAILABLE ON MULTIPLE OPERATING SYSTEMS. HOWEVER, NOT ALL OPERATING SYSTEM PLATFORMS FOR A SPECIFIC SOFTWARE VERSION ARE RELEASED AT THE SAME TIME. SEE THE README FILE FOR THE AVAILABILITY OF THIS SOFTWARE VERSION ON A SPECIFIC OPERATING SYSTEM PLATFORM. THIS DOCUMENT IS PROVIDED AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. THIS DOCUMENT COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THIS DOCUMENT. TIBCO SOFTWARE INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THIS DOCUMENT AT ANY TIME. THE CONTENTS OF THIS DOCUMENT MAY BE MODIFIED AND/OR QUALIFIED, DIRECTLY OR INDIRECTLY, BY OTHER DOCUMENTATION WHICH ACCOMPANIES THIS SOFTWARE, INCLUDING BUT NOT LIMITED TO ANY RELEASE NOTES AND "READ ME" FILES. Copyright TIBCO Software Inc. ALL RIGHTS RESERVED. TIBCO Software Inc. Confidential Information

3 Contents Important Information... 2 Contents... 3 Preface... 5 How to use this document... 5 Related Documentation... 5 Release Notes:... 5 Chapter 1: Introducing TIBCO BWPM Client for BW... 6 About TIBCO BWPM... 6 Make use of TIBCO BWPM explicitly... 7 Make use of TIBCO BWPM implicitly... 8 Chapter 2: Using TIBCO BWPM Client palette in TIBCO Designer... 8 LogInfo... 9 LogSuccess... 9 LogWarn LogError getcontext setcontext Combination of log activities: Configuration: Tab: Configuration Tab: Input Tab: Output Tab: Error output Chapter 3: Design use cases Save payload after Start Activity Capture exceptions and log technical errors Logging of functional errors Logging a successful state The Lazarus scenario Logging of business related attributes Building a correlation between multiple processes Create a relationship between business services and technical processes Using TIBCO BWPM in exclusive mode... 31

4 Configuring TIBCO BWPM BWPM Client Configuration File Logging configuration TIBCO BWPM Log Appender Appendix A: Configuring: Description of each global variable / properties (TRA settings) Appendix B Configuration XSD... 42

5 Preface This document describes the TIBCO ActiveMatrix BusinessWorks ProcessMonitor Client for BW. The TIBCO BWPM Client for BW enables TIBCO BusinessWorks engines to connect with TIBCO BWPM Server for process monitoring purposes. This ensures more visibility into the process platform while reducing the diagnosis and resolution efforts, hence reducing costs through the overall integration project lifecycle. How to use this document This document contains the following chapters: Chapter 1: Introducing TIBCO BWPM Client for BW gives you a quick overview of the components and functionality of BWPM. Chapter 2: Using TIBCO BWPM Client palette in TIBCO Designer explains the basic usage of BWPM activities with TIBCO Designer. Chapter 3: Design Guidelines for using BWPM activities demonstrates by means of several best practice scenarios how to use BWPM. Chapter 4: Advanced topics list various setting options for different operation modes of BWPM. Furthermore this chapter provides configuration options for memory optimization, performance enhancement, etc. Appendices: Appendix A: Global variables / TRA settings list all parameters for configuration purposes. Related Documentation Additional information about TIBCO BWPM Client for BW is available from the following sources: Release Notes: The Release Notes contain additional information about: Restrictions or known issues. Fixes that have been done. Any other information that was not available when this document was created

6 Chapter 1: Introducing TIBCO BWPM Client for BW TIBCO BWPM Client for BW provides a set of unique capabilities that simplify the monitoring of an end to end chain of TIBCO BusinessWorks processes. It is in charge of automatically generating and collecting monitoring events that occur in TIBCO BusinessWorks engines and providing those events to a TIBCO BWPM Server for further processing. The out of the box capabilities help to speed up the development process and ensure a uniform way of logging information to the monitoring server across the entire integration platform. The features of TIBCO BWPM Client for BW are based on the TIBCO BusinessWorks platform and therefore the client offers the same ease of use capability with regards to design, test and deployment. About TIBCO BWPM TIBCO BWPM is a multi- platform monitoring solution for TIBCO BusinessWorks. It facilitates the interaction of users with a distributed TIBCO platform and provides a single point of access to all running TIBCO BusinessWorks engines for managing successfully executed processes as well as warnings and errors. It also provides a set of technical capabilities to manage the interaction with the processes and generates reports. The BWPM solution consists of mainly 2 parts: - - The TIBCO BWPM Server running in a web application container. The TIBCO BWPM Client for BW, a TIBCO BusinessWorks plugin running within the same JVM hosting TIBCO BusinessWorks.

7 Webbrowser njams Instance HTTP Web-Application Server Presentation Layer njams Server Core UI Database Access Layer Data Provider JDBC Database system JMS Log Message Bus JMS njams Client Client for BW BW Engine The TIBCO BWPM Server collects all monitoring events sent by all TIBCO BWPM Client for BW instances and save those events in the underlying relational database for further processing. The server and all clients communicate asynchronously via JMS and are loosely decoupled. End users interact with BWPM via a web based GUI, which supports a technical and a business view and supports the following concepts: Authentication Authorization Role based access to monitoring objects Tasks Administration o Role and User management o System management o Configuration Make use of TIBCO BWPM explicitly The TIBCO BWPM Client for BW can be used in to different modes depending on the needs and project circumstances: - - Explicit mode using the palette in TIBCO Designer Implicit mode using the client without changing the TIBCO repositories Explicit mode is intended for users to implement monitoring activities and events at design time using TIBCO Designer. The TIBCO BWPM Client for BW adds a palette to TIBCO Designer. The palette consists of a set of different activities and enables you to equip the processes with many monitoring events as appropriate and needed. At the process level you can drag and drop the activities from the palette to the design panel and configure them accordingly. The palette automatically adds a BWPM

8 section in the global variables tab in the left panel of TIBCO Designer. The global variables show the default configuration that you adjust according to your environment. For more information about the palette and the global variables, see Chapter2: Using njmas Client palette in TIBCO Designer. Make use of TIBCO BWPM implicitly Using BWPM explicitly requires the user to open up the repository using the TIBCO Designer, enhance the implementation of the processes and then go through the major tasks of the project lifecycle including regression testing and deployments. There are particular cases where it is necessary to avoid this overhead in order to save efforts and costs for the project or to quickly enable a large number of existing projects and processes for monitoring. For this purpose BWPM provides the possibility to instrument the TIBCO BusinessWorks engines with TIBCO BWPM Client for BW without using the BWPM palette at design time. Instead, the TIBCO BWPM Client for BW is configured through the TRA file of the TIBCO BusinessWorks engine to run in the same JVM as the engine that it monitors. For more information on the TRA settings, see Appendix A. Chapter 2: Using TIBCO BWPM Client palette in TIBCO Designer The TIBCO BWPM Client for BW is represented as a full featured palette in TIBCO Designer. A palette within TIBCO Designer consists of specific activities that can be configured individually. The BWPM log activities are designed to send specific log events to TIBCO BWPM Server. The developer can use BWPM activities within the process definition at any place he wants to log technical or functional log information. This chapter walks you through all BWPM activities in detail and explains how to use the specific log actions. After installation of TIBCO BWPM Client for BW you will have a new palette available to your TIBCO Designer. The TIBCO Designer will optionally ask you to accept the palette to be added to the list. Once accepted, the palette is available to you to be used during the design of your processes. You can drag and drop BWPM activities to your process as you are used to do with other BusinessWorks activities.

9 LogInfo A LogInfo activity is used to send a log event with status INFO. This is a status typically used to indicate a specific transition has been executed within the process flow or a milestone has been reached. Furthermore, INFO can be used to log the payload of the process start activity. Having the payload logged via LogInfo activity allows for a complete error analysis including issues related to the content of the payload. In addition a LogInfo is typically used to correlate two or more dependent process instances into one process instance chain, by mapping the CorrelationLogID of the predecessor process to the successor process. LogSuccess A LogSuccess activity is used to send a log event with status SUCCESS. A SUCCESS represents a status that is typically used to indicate a successful finish of an activity or an entire process instance. In contrast to LogInfo the LogSuccess activity indicates an explicit successful state. Whereas LogInfo is more or less a neutral state, LogSuccess is a valuated successful state. In addition a LogSuccess can overrule any LogWarn or LogError activity that was

10 executed before. For example an error event was send first, but at the end the entire process could be turned into success, so that a LogSuccess is sent. In this scenario the process instance is declared as success with error. LogWarn A 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 not necessarily erroneous. Furthermore LogWarn is also used to indicate a functional failure that does not cause a technical error. For example if an incoming message does not contain an expected data format, but does not cause a schema validation error, a LogWarn indicates bad data quality, respectively wrong functional behavior. LogError A 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. When a process instance generates an error, the exception is captured and the Stacktrace is mapped to LogError activity. You can assign an individual event code and event message to LogError also. This is useful if you want to search for your specific event codes within BWPM webui. getcontext A getcontext activity is used to get the BWPM log context from the current process instance. No event will be send. Typically the getcontext activity is used to retrieve the current BWPM log status. If you want to retrieve the current BWPM log id for example you can do this by using getcontext. Each BWPM LogEvent activity (LogInfo, LogSuccess, LogWarn, LogError) provides you with the current BWPM log context, but it is not always appropriate to send a log event when you only want to retrieve the context information.

11 setcontext A setcontext activity is used to set the BWPM log context from the current process instance. No event will be send. Typically the setcontext activity is used to set a different BWPM log context without sending a log event. For example if you want to overwrite the correlation id in order to combine multiple dependent process instances by using the same correlation log id you can use setcontext. Each BWPM LogEvent activity (LogInfo, LogSuccess, LogWarn, LogError) lets you set the current BWPM log context, but it is not always appropriate to send a log event when you only want to set the context information. Combination of log activities: Log activities may be combined in a BusinessWorks process to indicate different milestones and their status. The log levels correspond to severities as follows: : Info 1: Success 2: Warning 3: Error The following table shows the possible combinations and how the overall status of the process will be shown in the user interface. Highest Severity logged Last activity logged Overall process status Icon in user interface

12 Note: If a logsuccess activity executes after the last logwarn or the last logerror activity, the overall status of the process will be shown as successful with warning and accordingly error. LogInfo activities executed at the end of a process do not change the overall status. Configuration: The configuration of the BWPM activities is done by setting the BWPM global variables. These settings apply to all BWPM activities of the entire project. As soon as you use a BWPM activity for the first time in a new project, the global variables are added automatically to the project under the root BWPM.

13 Tab: Configuration You can change the name of a BWPM activity and add a more meaningful description to it as you would do with other activities. You can also check the connection between the BWPM activity and the JMS Server by clicking on Test Connection. If the connection could be established the result will be Success. If the connection could not be established, an error message will pop up containing further information about what went wrong. Tab: Input The input structure of BWPM activities allows you to map additional content to BWPM. Since all elements of the input structure are optional it is not required to provide an input for any field.

14 You can provide a value for the following fields: Element Datatype Description EventMsgCode string User defined log message code EventMsg string User defined log message name such as description of the event, position of the event, etc. Payload string This is the payload message you may want to get logged Stacktrace string The stacktrace object contains technical error information. This element is especially suitable for the LogError activity. Attributes Attribute This element contains information that can be mapped individually. Typically attributes contain business related content like order number, customer name, etc. This is the repeating element Name string The name of an attribute describes meaning of the content. For example order_no is a typical attribute name. Type string You can declare a specific type of the attribute like string, number, date. This element is optional. If not provided,

15 a string will be assumed. Value string The attribute value contains the data of the attribute. For example if attribute type is order_no, a valid content might be A4711. LogContext This element contains information about the current log context of BWPM CorrelationLogID string This ID is used by BWPM to correlate multiple log entries to a log entry chain ParentLogID string This ID allows a hierarchical composition of log entries. The ParentLogID is the LogID of the process instance that calls the current process. ExternalLogID string This ID is a user defined identifier BusinessService string Name of the Business Service that is represented by one or more technical processes. BusinessObject string Name of the Business Object that is delivered by one or more technical processes. BusinessStart datetime User defined starting timestamp that can differ from current system timestamp BusinessEnd datetime Use defined ending timestamp that can differ from current system timestamp. Tab: Output The output structure contains information about the current log context of BWPM.

16 Element Datatype Description LogContext This element contains information about the current log context of BWPM AuditStatus integer The audit status of the activity. The LogInfo activity returns the status 0 The other attributes and elements are the same as in the input tab. Tab: Error output The error output is not used by BWPM. Any error that occurred inside of a BWPM activity will be logged in the BusinessWorks logfile, respectively in the console of TIBCO Designer.

17 Chapter 3: Design use cases Save payload after Start Activity The LogInfo activity can be used to log the payload of the process start activity. Having the payload logged via LogInfo activity allows for a complete error analysis including issues related to the content of the payload.

18 The event table in the BWPM user interface has the following attributes: Name Message Eventdatetime L: Log S: Stacktrace Mapping the payload ensures the GUI shows this payload associated with the event in the event list in the column L.

19 You can view the payload by clicking on the payload icon in column L.

20 Capture exceptions and log technical errors A logerror activity is used whenever the user explicitly captures an error by design. The remaining errors are typically captured using the Catch activity with the option Catch All. In this case the LogError activity can be used as part of the error handling process to log the error information including the stack trace to the TIBCO BWPM Server. The log error event is shown in the user interface and is associated with stack trace information. The user can view the stack trace by clicking the stack trace icon in column S.

21 Logging of functional errors The LogWarn activity may be used in case there is a functional error during the processing of data, such as missing business information that might be useful for routing purposes or for the determination of further required steps. The running process is considered successful but with warning. The warning message is sent to the TIBCO BWPM Server and will be displayed on the user interface.

22

23 Logging a successful state When processes are executed successfully the user can see the successful state of these processes in the UI. However, using a logsuccess activity in the process indicates an explicit successful state. In this case the user can assume the process has been technically as well as functionally processed successfully. In case there are warnings or errors happened before logging a success event, the process will be shown as successfully executed with warning, respectively with errors.

24

25 The Lazarus scenario Consider a scenario where an involved application is by chance often not available. There are different design patterns that can be implemented to overcome this issue. A possible scenario is to loop over the issue and retry multiple times until the process executes successfully. In the following example a SOAP request is executed against a web service, which availability is unpredictable. The designer decides to implement an error handling procedure by retrying to invoke this service multiple times until it succeeds. The maximum number of iterations in this example is limited to 100 and the process sleeps 15 seconds between the retries. The logerror activity is used to log the exact error message and to send the stack trace to the TIBCO BWPM Server. However, sending the same error message to the TIBCO BWPM Server 100 times could increase the diagnosis and resolution efforts and add unnecessary load on the server. Log activities should therefore be used in iterations only if: The number of iterations is not too high It is expected that errors will not occur very frequently A log activity outside the iteration cannot provide necessary information, which would be available only in the context of the iteration.

26 Logging of business related attributes Business related information can be logged by using custom attributes. These are user defined attributes that can be set at each BWPM log activity. The attributes are of type sequence. The user can define as many as required by duplicating the attribute element. An attribute consists of name, type and value. Name and value are displayed in the BWPM user interface and can be used in searching for processes. The example below uses 2 attributes, order number and customer ID. Both attributes are of type String which is the default type for attributes.

27 Note: The BWPM user interface displays the alphabetical first 2 attributes under the process name in the list of processes. Other attributes are available for search.

28 Building a correlation between multiple processes 2 or more processes can be correlated by using the same correlation ID. A sender process sends the correlation ID e.g. as part of a JMS message using the JMSCorrelationID. The receiver process retrieves this correlation ID and maps it to the CorrelationLogID available in the log context of a BWPM log activity. Both sender and receiver use BWPM activities and therefore the TIBCO BWPM Server correlates the messages and can therefore build a chain of processes. The processes are chained according to the execution timestamps. Note: BusinessWorks generates a correlationid for each process instance. The BWPM log activities can overwrite this ID or just use it by not mapping any value to this field.

29

30 Create a relationship between business services and technical processes BWPM allows a view on the platform based on service names. The activities in the palette provide the user with a field called BusinessService. This name is used to classify technical services within a business context, the user can use for searching.

31 Using TIBCO BWPM in exclusive mode You can control the log mode of BWPM by setting the global variable logmode. Setting the value of this variable to exclusive ensure that BWPM sends log entries to the server only if an BWPM activity has been executed in a process. This mode can be very useful to avoid useless log information in BWPM. In the following example, the process starts with a timer activity, which triggers the process in regular timeframes, e.g. every 2 minutes. The process checks if there are any new files made available for processing. In case there are no files, nothing happens and the TIBCO BWPM Client does not send any log events to the TIBCO BWPM Server. Otherwise a subprocess will be invoked to process the existing file(s). The BWPM user interface would show only processes that have been executed while file(s) were to be executed.

32 In this case no log events are sent to TIBCO BWPM Server.

33 The LogInfo activity is executed and therefore this case and all related log information will be shown in the user interface.

34 Configuring TIBCO BWPM The behavior of the TIBCO BWPM Client for BW can be controlled by setting numerous properties, referred to as Global Variables by TIBCO BusinessWorks. Those Global Variables can be set in various ways, just like any other Global Variable of TIBCO BusinessWorks: 1) If the TIBCO BusinessWorks project is instrumented using the TIBCO BWPM Client for BW palette for TIBCO BusinessWorks, they appear in the Global variables tab of the TIBCO Designer. The developer can set the values as required during the design phase, while the Global Variables are also available during a project s deployment. This is the preferred and most recommended option. 2) The second option to set the Global Variables is to define a properties file and make the TIBCO Designer Tester using it for its configuration (see the TIBCO Designer documentation for more information). Add the following properties to that file and update their values accordingly: tibco.clientvar.njams/logmode=complete tibco.clientvar.njams/dataprovider/file/name=/tmp/out.trace tibco.clientvar.njams/dataprovider/file/enabled=false tibco.clientvar.njams/dataprovider/jms/usejndi=true tibco.clientvar.njams/dataprovider/jms/usequeues=true tibco.clientvar.njams/dataprovider/jms/destination=bwpm tibco.clientvar.njams/dataprovider/jms/enabled=true tibco.clientvar.njams/dataprovider/jms/user=admin tibco.clientvar.njams/dataprovider/jms/password=admin tibco.clientvar.njams/dataprovider/jms/server= tibjmsnaming://localhost:7222 tibco.clientvar.njams/dataprovider/jms/contextfactory= com.tibco.tibjms.naming.tibjmsinitialcontextfactory tibco.clientvar.njams/dataprovider/jms/connectionfactory= QueueConnectionFactory

35 tibco.clientvar.njams/dataprovider/enginelog/enabled=false 3) For deployed projects the Global Variables listed above in option (2) can be added to the TIBCO BusinessWorks engine s TRA file, which can be found at <TIBCO_DOMAIN_HOME>/application/<application name>/<engine name>.tra Keep in mind that all changes made to an engine specific TRA file will be lost after a redeployment of that component! Hence, this option is only recommended to the advanced administrator. It is recommended to store the BWPM related global variables in an extra properties file and use the TRA setting tibco.env.app_args to point to that extra file. For example: tibco.env.app_args=- p /opt/tibco/bw/5.11/bwpm.properties 4) If the Global Variables should be set using the engines TRA files, settings introduced above can be added to the end of the bwengine.tra template file located at <TIBCO_BW_HOME>/<version>/bin/bwengine.tra. Any subsequent deployment will now automatically add the Global Variables to the newly deployed engine s TRA file. All configuration settings of the TIBCO BWPM Client for BW can be made using the concept of Global Variables. However, not all Global Variables available for configuration are automatically added to a TIBCO BusinessWorks project, when the TIBCO BWPM Client for BW palette is used. BWPM differentiates between palette generated settings, which are of common interest to all developers and administrators. Those settings control the overall behavior of the TIBCO BWPM Client for BW, such as which appender to use (File or JMS), or the JMS connection parameters. BWPM Client Configuration File In most cases an administrator wants to pre- configure not only the technical aspects of the BWPM Client for BW, such as JMS connection, etc; the configuration of the functional extracts are equally or even more important. To pre- configure log level, traces and extracts an administrator can create an XML file containing the configuration of those features. An example XML configuration can look like this; the corresponding XSD can be found in the Appendix of this document: <?xml version="1.0" encoding="utf-8" standalone="yes"?> <config xmlns=" lastdeploymenttime=" "> <tracing/> <extracts> <extract activity="loginfo" process="process Definition.process"> <extractionrules> <extractrule inout="out" rule="//ns0:logid" ruletype="xpath" attribute="myid"/>

36 <extractrule inout="in" rule="//ns0:name" ruletype="xpath" attribute="businessservice"/> </extractionrules> </extract> <extract activity="jms Queue Receiver" process="process Definition (1).process"> <extractionrules> <extractrule rule="a" ruletype="regexp" attribute="businessservice"/> </extractionrules> </extract> <extract activity="start" process="process Definition.process"> <extractionrules> <extractrule inout="out" rule="//job" ruletype="xpath" attribute="correlationlogid"/> </extractionrules> </extract> </extracts> </config> In order to preconfigure the BWPM Client for BW using this XML configuration file, the filename must be of this pattern: <ENGINE_NAME>_njams_config.xml and be located in this directory: <TIBCO_DOMAIN_HOME>/applications/<APPLICATION_NAME>/resource When the TIBCO BusinessWorks engine starts and the BWPM Client for BW is in its initialization phase, it will look for and read this configuration file. Also, it will send its new configuration to the BWPM Server, so that the server knows about any configuration update of the BWPM Client. In larger installations creation and rollout of this configuration file could be automated. Logging configuration The BWPM Client for BW uses the TIBCO BusinessWorks log4j configuration for its technical logging. To change the log level from INFO the log4j configuration of TIBCO BusinessWorks bw.logger must be changed. The log level can be configured in the file <BW_HOME>/5.x/lib/log4j.xml: <!-- TIBCO BusinessWorks Logger

37 ========================== The logger "bw.logger" can be used by the third party application or java code executing in the TIBCO BusinessWorks JVM to write the log messages to the TIBCO BusinessWorks log file. TIBCO BusinessWorks Logger. The logger level is "INFO" and the appender is "tibco_bw_log". --> <logger name="bw.logger"> <level value ="INFO"/> <appender-ref ref="tibco_bw_log"/> </logger> TIBCO BWPM Log Appender As a default the TIBCO BWPM Client for BW sends events to the JMS server via JMS. In this case the BWPM installation is used with all features including the TIBCO BWPM Server and the user interface. Optionally the user can send the log events to a local log file. The following global variables are used to enable and disable the log appenders: tibco.clientvar.njams/dataprovider/jms/enabled=true tibco.clientvar.njams/dataprovider/file/enabled=true tibco.clientvar.njams/dataprovider/file/name=<path and file name> In addition, BWPM can be configured to write log messages to the BusinessWorks log file by using this global variable: tibco.clientvar.njams/dataprovider/enginelog/enabled=true Appendix A: Configuring: Description of each global variable / properties (TRA settings) Description of BWPM Global Variables & Settings Name Description Valid Values Default Value njams /logmode Globally controls the operation mode of the TIBCO BWPM Client for BW complete: BWPM will monitor all processes that are executed within the TIBCO BusinessWorks engine. complete

38 njams /DataProvider /File /enabled Enables or disables the writing of log entries to a local log file exclusive: BWPM will only monitor processes, that make explicit use of the TIBCO BWPM Client for BW palette. All other processes will be ignored. none: the BWPM functionality is completely disabled; event instrumented processes that are using the TIBCO BWPM Client for BW palette are not monitored. true: write log entries to a local log file false: disable local log file writing false /name The full name of the log file to write log entries to (if enabled) complete path to a log file; for example: /tmp/bwpm.log <none> njams /DataProvider /JMS /clientid /usejndi Specifies the EMS connection s clientid to be set Controls whether to use JNDI to lookup (JMS) connection factories, or not Any valid clientid string; for example: OrderService- Engine1 true: use a JNDI server to lookup connection factories <TIBCO_DOM AIN_NAME>- <BW_ENGINE _NAME> true false: no JNDI lookup /usequeues Set this global variable to control whether to use (JMS) queues or topics to communicate with the TIBCO BWPM Server true: use (JMS) queues false: use (JMS) topics true /destination The (JMS) destination name prefix. The prefix will be extended with.event for BWPM event messages and.command for messages send from the server to the TIBCO BWPM Client for BW Any valid JMS destination name is allowed for this global variable. BWPM

39 ory /enabled /user Enabled or disables the sending of BWPM events via JMS The JMS server user name to use true: BWPM communicates with the TIBCO BWPM Server using JMS false: JMS communication is disabled. Any valid JMS server user that has the required privileges to send and receive messages on the destinations defined using the BWPM/DataProvider/JMS/destin ation global variable. /password The JMS user s password The matching password for the configured JMS user. The password is allowed to be clear text (not recommened) or obfuscated (using TIBCO s obfuscation tool). /server /contextfact The JMS or JNDI server connection url If using JNDI, this sets the JNDI context factory 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://localho st:7222 (for JNDI) or tcp://localhost:7222. For TIBCO EMS fault- tolerant or load- balanced URLs are supported. For TIBCO EMS use: com.tibco.tibjms.naming.tibjmsi nitialcontextfactory true <none> <none> tibjmsnami ng://local host:7222 com.tibco. tibjms.nam ing.tibjms InitialCon textfactor y /connectionf actory Configures the connection factory to lookup, when using JNDI Any configured (JMS) connection factory QueueConne ctionfacto ry /compress njams /DataProvider /EngineLog Determined if the the JMS messages should be send in compressed mode to save bandwidth. true: the JMS header JMS_TIBCO_COMPRESS is set to true ; the TIBCO EMS libraries will compress the message before sending. false: the JMS message is send without compression. true

40 /enabled Controls whether BWPM will write log messages to the TIBCO BusinessWorks engine s log file, or not true: write log messages to the TIBCO BusinessWorks engine log file false false: disable this feature The following table represents advanced settings: Name Description Valid Values Default Value njams /publishsources Controls whether to publish process definition or not. If no process definition is sent, there will be no process graph visible in BWPM webui true: publishes process definition false: do not publish process definition true njams /DataProvider /instantpush Controls whether to collect events within a period of time and send the events by one single message or to send out a message for each event true: sends out an event message on each event activity instantly false: collects events within a period of time according to the setting of /timeoutpush false /timeoutpush Period of time for collecting events. A period of time in [ms] /timeoutchecki nterval Period of time for timeout check A period of time in [ms] njams /MemoryManage ment

41 B /maxmsgsizem Maximum internal message size. If size of internal message is reached, an instant push is triggered. Any integer value > 0 in [MB] 10 gth /maxqueuelen maximum internal queue size, before discardpolicy is applied Any integer value (represents number of messages) > 0 20 /discardpolicy njams /RegEx keep/discard newly added log messages from memory, when maxqueuelength is exceeded; a setting of none blocks the engine until queue size is below threshold The usage of this setting is deprecated as of this release (2.1)! none / discard none /UseRegEx Controls whether BWPM uses regular expressions to evaluate the payload data of a start activity of a process for specific content. If the contect of the payload matches the regex, this part of the content is mapped into the BWPM log message. true: use regular expressions false false: do not use regular expressions njams /RegEx /Attributes The usage of these settings is deprecated as of this release (2.1)! ogid /CorrelationL Evaluates the payload for content that can be used as CorrelationLogID /ParentLogID Evaluates the payload for content that can be used as ParentLogID Any valid regular expression. Example: <CustomerCorrID>(.*?)< /CustomerCorrID) <none>

42 D /ExternalLogI Evaluates the payload for content that can be used as ExternalLogID vice /BusinessSer Evaluates the payload for content that can be used as BusinessService ect /BusinessObj Evaluates the payload for content that can be used as BusinessObject java.start.class=com.tibco.processmonitor.client.run Replace Java Start Class in order to start BWPM in non- invasive mode. Appendix B Configuration XSD <?xml version="1.0" encoding="utf-8"?> <xsd:schema xmlns:xsd=" xmlns=" targetnamespace=" /" elementformdefault="qualified" attributeformdefault="unqualified"> <xsd:simpletype name="ruletype"> <xsd:restriction base="xsd:string"> <xsd:enumeration value="event" /> <xsd:enumeration value="regexp" /> <xsd:enumeration value="value" /> <xsd:enumeration value="xpath" /> <xsd:enumeration value="disabled" /> </xsd:restriction> </xsd:simpletype> <xsd:complextype name="extractruletype"> <xsd:attribute name="attribute" type="xsd:string" /> <xsd:attribute name="ruletype" type="ruletype" /> <xsd:attribute name="rule" type="xsd:string" /> <xsd:attribute name="inout" type="xsd:string" default="out"/> </xsd:complextype> <xsd:element name="extract"> <xsd:complextype> <xsd:sequence> <xsd:element name="extractionrules"> <xsd:complextype>

43 <xsd:sequence> <xsd:element name="extractrule" type="extractruletype" minoccurs="1" maxoccurs="unbounded" /> </xsd:sequence> </xsd:complextype> </xsd:element> </xsd:sequence> <xsd:attribute name="process" type="xsd:string" /> <xsd:attribute name="activity" type="xsd:string" /> <xsd:attribute name="name" type="xsd:string" /> </xsd:complextype> </xsd:element> <xsd:element name="extracts"> <xsd:complextype> <xsd:sequence> <xsd:element ref="extract" minoccurs="1" maxoccurs="unbounded" /> </xsd:sequence> </xsd:complextype> </xsd:element> <xsd:element name="tracepoint"> <xsd:complextype> <xsd:attribute name="process" type="xsd:string" /> <xsd:attribute name="activity" type="xsd:string" /> <xsd:attribute name="starttime" type="xsd:long" /> <xsd:attribute name="endtime" type="xsd:long" /> <xsd:attribute name="iterations" type="xsd:int" /> </xsd:complextype> </xsd:element> <xsd:element name="tracing"> <xsd:complextype> <xsd:sequence> <xsd:element ref="tracepoint" minoccurs="1" maxoccurs="unbounded" /> </xsd:sequence> </xsd:complextype> </xsd:element> <xsd:element name="loglevel"> <xsd:complextype> <xsd:attribute name="process" type="xsd:string" /> <xsd:attribute name="loglevel" type="xsd:string" /> </xsd:complextype> </xsd:element> <xsd:element name="logging"> <xsd:complextype> <xsd:sequence> <xsd:element ref="loglevel" minoccurs="0" maxoccurs="unbounded" /> </xsd:sequence> </xsd:complextype> </xsd:element> <xsd:element name="config"> <xsd:complextype> <xsd:sequence>

44 <xsd:element ref="logging" minoccurs="0" maxoccurs="1" /> <xsd:element ref="tracing" minoccurs="0" maxoccurs="1" /> <xsd:element ref="extracts" minoccurs="0" maxoccurs="1" /> </xsd:sequence> <xsd:attribute name="lastdeploymenttime" type="xsd:long" default="0" /> </xsd:complextype> </xsd:element> </xsd:schema>