Emmanuel Marchiset 2

In BusinessWorks JDBC connections are managed in a pool. By default, JDBC connections are managed using the approach described below. Default behavior When a JDBC activity needs a connection to send an SQL statement the BusinessWorks engine will first check if there is an available connection in the pool, if this is the case the connection is tested by sending a test SQL statement to the target database and if the test is successful, the connection is assigned to the activity. It is my understanding, but I am not 100 % sure, that if a connection appears to be inactive, BusinessWorks automatically tries with another connection from the pool. In the case there would be no connection available from the pool, and the number of Maximum Connections defined in the JDBC Connection shared resource won’t be reached BusinessWorks will try to open a new connection. In the case the Maximum Connections would be reached the activity has to wait until a connection from the pool is available. If no connection becomes available before the expiry of the activity Time out, the activity execution ends with a timeout error. Note also that JDBC connections from the pool are closed by BusinessWorks if they are not used within the duration defined by the ‘Connection Idle Timeout’ property in the JDBC Connection shared resource. The above explanations are summarized in the diagram below, note that this is indicative and may not be 100 % accurate: Overall this is beneficial to manage JDBC connections in a pool but always testing the selected JDBC connection before executing a JDBC activity has a negative impact on performances. JDBC performances improvements This is why since BusinessWorks 6.8 and BusinessWorks Container Edition 2.7, two properties have been introduced to change this behavior. bw.application.jdbc.validateConnection : with this property set to false, available connections from the pool are assigned to activities without being tested. Instead of testing a connection everytime it is used, connections from the pool are tested periodically. bw.application.jdbc.validateConnection.frequency : this property defines the frequency of the test of the pool connections. The value is in seconds and should not be above the Connection Idle Timeout property in the JDBC Connection shared resource. Example: bw.application.jdbc.validateConnection=false bw.application.jdbc.validateConnection.frequency=50 Those properties can be set in an appnode config.ini file. When using those properties, it is important to include the JDBC activities in a retry mechanism, possibly using the approach described in this other article: https://emarchiset.medium.com/how-to-implement-a-retry-mechanism-in-businessworks-6-x-and-businessworks-container-edition-564b7b33ebc6 The above explanations are summarized in the diagram below, note that this is indicative and may not be 100 % accurate: Summary For applications sending JDBC queries at a relatively high frequency, say more than a few queries per minute, it is recommended to use the properties described above to make sure application performances are optimal. In such case this is important to implement a retry mechanism for JDBC activities in the application logic. Reference elements Extract from BusinessWorks 6.8 release notes: The default JDBC Connection shared resource configuration (note that the Connection Idle Timeout property value is in seconds):

An operating bwagent manage in the ‘domains’ file directory tree an image of the configurations of the domains, appspaces, appnodes and applications it manages. Example of a bwagent directory tree It might be needed in some cases to recreate this directory tree from the bwagents database, like after a full re-installation of the BusinessWorks stack on the target machine. This can be done with the following command: bwadmin restore agent <AGENT_NAME> Example: bwadmin restore agent esbsrv01 Note that for this command to work the bwagent must be running on the machine. Also changes directly made in the appspace or appnode .config files and changes made in the .tra files are lost while such changes are not kept in the bwagent database.

This article is to explain how to access both Module property values and Java property values in a BusinessWorks mapping. Module properties There are two kinds of module properties some are defined by the application developer and some are predefined in BusinessWorks. The module properties defined by the application developer are managed in the ‘User’ tab of the Module Properties: The predefined module properties are visible in the ‘System’ tab of the Module Properties: The value of a given module property can be accessed in a mapping using the following XPATH function: bw:getModuleProperty() For example to access a property called ‘MyProperty’ that is part of a group called ‘Service’ you have to use the following XPATH formula: bw:getModuleProperty(“/Service/MyProperty”) Similarly, this function can also be used to access the predefined properties. For example, to access the property ‘BW.APPNODE.NAME’, that contains the name of the appnode hosting the application, have to use the following XPATH formula: bw:getModuleProperty(“BW.APPNODE.NAME”) Note that the deployment unit name and version are the name and version of the running application. It is also possible to access properties defined in Shared Modules using the following syntax: bw:getModuleProperty(“//<Shared Module Name>///<GroupName>/<PropertyName>”) For example to access the value of the property “MsgLabel” part of the “SMProperties“ group of the “MySharedModule” Shared Module you have to use the following syntax: bw:getModuleProperty(“//MySharedModule///SMProperties/MsgLabel”) In case there are multiple group levels the name of each sub-level should be included like this: bw:getModuleProperty(“//<Shared Module Name>///<GroupNameLevel1>/<GroupNameLevel2>/<GroupNameLevelN>/<PropertyName>”) For more details you may refer to the following KB article: https://support.tibco.com/s/article/Tibco-KnowledgeArticle-Article-46830 Note that starting from BusinessWorks 6.10 it is possible to directly use Module Properties in Mappings (with the limitation that in case the name of a property would change the developer would have to update the impacted mappings manually). Module Properties are available in the DataSource tab of the Mapper, you can select a property and drag and drop it in the target field, this automatically creates an XPATH formula using the getModuleProperty() function to access the property value. System properties System properties are in fact the Java properties defined by default in Java or defined in the appnode tra file or config.ini file. The value of a given system property can be accessed in a mapping using the following XPATH function: bw:getSystemProperty() The values of the following java system properties are accessible using this approach: file.encoding java.version user.home os.name For example to access the Java property ‘java.version’ you have to use the following XPATH formula: bw:getSystemProperty(“java.version”) The values of the properties defined in an appnode tra file or config.ini file, can also be accessed using this function but for some properties it is only working in deployed mode. For example to access the appnode Java property ‘logback.configurationFile’ you have to use the following XPATH formula: bw:getSystemProperty(“logback.configurationFile”) Additional elements A sample project is attached. AccessSystemProperties.zip

Updating an XSD schema namespace in a BusinessWorks application or shared module have a significant impact for the processes using it while all the activities using the updated schema are impacted. Even if not explicitly mentioned in the documentation, it is possible in BusinessWorks Studio to update an XSD schema namespace and to update automatically all the impacted processes. This can be done with the following: . Right click on the target xsd file . Select ‘Refactor -> Rename XSD schema namespace’ . Update the name space as needed and make sure the option ‘Update references to the XSD schema namespace’ is checked Once done you can check that all activities in all processes using the schema have been updated. If the XSD schema is in a shared module the update is made in all applications referring to the shared module that are opened in the current workspace.

It is quiet common for BusinessWorks developers to encounter difficulties in understanding when Module Shared Variables can be accessed directly and when it is necessary to use a Critical Section. This article goal is to bring needed clarifications on this topic. Module Shared Variables can be shared between multiple processes definitions and multiple process instances. Because of the multi-threaded nature of the BusinessWorks engine there are some cases where it is necessary to use Critical Sections. One important thing to know is that accesses to a given Module Shared Variable, using the ‘Get Shared Variable’ and ‘Set Shared Variable’ activities, are synchronized. Reading or setting the value of a Module Shared Variable This means that for just reading the current value of a Module Shared Variable, at the moment of the Process execution, it is possible to just use the ‘Get Shared Variable’ activity without using a Critical Section. This means also that for just setting the value of a Module Shared Variable without taking care of its current value it is possible to just use the ‘Set Shared Variable’ without using a Critical Section. Updating the value of a Module Shared Variable in a process In the case of a process that needs to read the current value of a Module Shared Variable and update it, for example to increase a counter or update some king of semaphore flag, it is necessary to use a critical section while multiple instances of this Process might be executing and accessing the variable at the same time. In such case the ‘Get Shared Variable’ and ‘Set Shared Variable’ activities must be included in a Critical Section. Updating the value of a Module Shared Variable in different processes It is also possible for different process definitions to update the same Module Shared Variable using a different logic. In that case it is necessary to use a Critical Section in each of the process definitions and to synchronize them using the Module Shared Variable. This can be done by checking the ‘Shared Lock’ option and selecting a Module Shared Variable. The selected Module Shared Variable is then used as a semaphore to control execution of the different Critical Sections referring to it. Using a Module Shared Variable as a Semaphore The approach to use multiple critical sections synchronized with a Module Shared Variable can also be used to manage accesses to external resources like for example a file, in such case a Critical Section with a Shared Lock can be used to manage concurrent accesses to the target file from different processes of an application. Accesses to Job Shared Variables Job Shared Variables are local to a process instance and there is no need to use Critical Sections to access them except in case where the same Job Shared Variable would be updated in parallel branches of a process definition. Additional elements A sample project is attached to this article. Elements for BusinessWorks 5.X The elements provided in this article also applies to BusinessWorks 5.X except that the ‘Shared Lock’ mechanism is not available in BusinessWorks 5.X. Reference elements https://docs.tibco.com/pub/activematrix_businessworks/6.10.0/doc/html/Default.htm#app-dev-guide/working-with-critica.htm https://docs.tibco.com/pub/activematrix_businessworks/6.10.0/doc/html/Default.htm#binding-palette/critical-section.htm Additional elements You can refer to the attached sample project. SharedVariableAccess.zip

While I sometimes receive the question to know how to get started on BusinessWorks or BusinessWorks Container Edition I thought this would be useful to write an article listing resources freely available on line and giving directions for people willing to discover and learn by themselves. My recommendation is to take the following approach: . Read the product documentations introducing BusinessWorks concepts and architecture for both design time and run time . Download the product, install it in a sand box environment and try it . Check the samples provided with the product . Read some blog articles I would also recommend to consider using TIBCO Education training services, there are two options available: . On line training . Instructor lead training More details are available here: https://www.tibco.com/education Documentations to read BusinessWorks and BusinessWorks Container Edition documentations are freely available at the following URL: https://docs.tibco.com/products/tibco-activematrix-businessworks For BusinessWorks, I recommend reading the following documents in the order they appear below: . ‘Getting started’ . ‘Concepts’, that gives an introduction of what is BusinessWorks and how it is working . ‘Application Development’, that gives an introduction on developing with BusinessWorks and provide details on important design time concepts . ‘Administration’, that present the BusinessWorks run time architecture and provide details on how to configure the BusinessWorks run time components (you can focus on the introduction part of each chapter and keep the details for later) If you are interested by the solutions available to migrate BusinessWorks 5.X applications to BusinessWorks 6.X you may also have a look to the ‘Migration’ document. The other documents should be used as references when you need detailed elements on something, at this stage you can just have a quick look to familiarize on their content. In the ‘Binding and Palettes References’ document you have details on each activity or Shared Resource, in the ‘REST reference’ document you have all details about REST Bindings and etc… For BusinessWorks Container Edition, I recommend reading the following documents in the order they appear below: . ‘Getting started’ . ‘Concepts’, that gives an introduction of what is BusinessWorks and how it is working . ‘Application Development’, that gives an introduction on developing with BusinessWorks and provide details on important design time concepts . the ‘Application Development for Docker’ section of the ‘Application Development’ documentation. https://docs.tibco.com/pub/bwce/2.9.1/doc/html/Default.htm#app-dev-guide/application-developm3.htm Downloading BusinessWorks Download BusinessWorks using your company account on the TIBCO edelivery site: https://edelivery.tibco.com If you are on your own it is possible to download BusinessWorks and BusinessWorks Container Edition from the TIBCO Access Point page: https://tap.tibco.com/storefront/index.ep Note that you will need to register and the versions available from this site are not recent. Once registered you can login and download BusinessWorks. Once downloaded you can install BusinessWorks following the ‘Installation’ document available on the page mentioned before. Looking at samples provided with BusinessWorks Once installed you can launch Studio and start creating an application with a few processes. After creating a first workspace a page with links to sample applications is displayed, you can have a look to some of them. BusinessWorks and BusinessWorks Container Edition general samples are available in the following directory: <TIBCO_HOME>/bw/6.10/samples/AppSpace BusinessWorks Container Edition specific samples are available in the following directory: <TIBCO_HOME>/bw/6.10/samples/Container Going further After reading the documentation, installing BusinessWorks and looking at the samples you can go further by looking at other articles on TIBCO Community or on Internet blogs.

Since the early days of BusinessWorks 6.X, applications using resources that cannot be properly initialized are considered to be impaired and cannot start. Generally, this is because one of the Shared Resources used by an application cannot start without error, this can be for example a JMS connection resource that cannot connect to the target EMS server because it is unavailable, or an HTTP Connector resource that cannot initialize because the port it is using is already opened by another application. This behavior allows to make sure an application start only in a consistent state but in some cases, it is useful to start an application even if some of its Components or Process Starters are not available (for debugging purpose or to allow running an application in a production environment even if some part of it are not active). Since BusinessWorks 6.9.1 a property has been introduced to force an application to start even if it is impaired. The property name is: bw.independent.component.startup To enable applications to start even if they are impaired you then have to do the following: . Go to the target appnode directory: <TIBCO_HOME>/bw/6.X/domains/<DOMAIN_NAME>/appnodes/<APPSPACE_NAME>/<APPNODE_NAME> . Edit the config.ini file to add the property and set it to true: bw.independent.component.startup=true . restart the appnode Useful things to know I tested this with a JMS Receive Message Process Starter and it is working fine: . If the EMS server is down while the application is started the corresponding Components (or Process Starters) are disabled, and you can see this in the TEA or using the bwagent REST API: . Then once the EMS server is restarted you can re-enable the JMS components in the TEA or using the bwagent REST API : . And check the Component is now enabled: I also tested with a Rendezvous Subscriber Process Starter and a Receive Email Process Starter and it is working fine. I didn’t found a way to get an application to be in an Impaired state because of a problem with a File Poller Process Starter or a TCP Receiver Process Starter. Limitations I also tested this with a REST Binding Component using an HTTP Connector resource and unfortunately it is not working with both BusinessWorks 6.9.1 and BusinessWorks 6.10. I got also the same behavior for HTTP Receive Process starters. I reported this to TIBCO support. Reference elements Extract from the TIBCO Documentation: TIBCO support knowledge base article on Impaired applications: https://support.tibco.com/s/article/Tibco-KnowledgeArticle-Article-41342 Additional elements You can also have a look to this article from my colleague Alexandre Vasquez: https://medium.com/coderbyte/tibfaqs-how-to-solve-an-impaired-status-on-your-businessworks-application-326c23a3f624

It is sometimes needed to do things before starting to process events in an application, like for example loading values from files or databases in Shared Variables, or checking the availability of resources that are critical for the application. It is also sometimes needed to do things when an application is shutting down, like for example cleaning temporary files in a working directory or sending a JMS message to notify a monitoring solution. This can be done in BusinessWorks and BusinessWorks Container Edition by using an Activator Process, such Process can be created with the following: . Go to the Module Descriptor Overview panel of your application and click on the Create Activator Process button . The Activator Process Creation panel is displayed, selected the target Process Folder and Package, then enter a name for the Process and click Finish . The Activator Process is now created . Now you can implement your Activator Process as you need You can have only one Activator Process per application. This is generally a good practice to limit the number of activities in an Activator Process and to use Sub Processes if different things have to be done. In the case you would not need to do something at Startup and nothing at Shutdown you can just leave empty the onShutdown branch (and vice versa). Additional elements You can refer to the attached sample project. OnStartUpDemo.zip

One challenge while handling files in BusinessWorks is that we generally don’t have control on the actual file sizes and this sometimes require to use large amounts of memory and may even create situations where ‘Out of Memory’ errors occurs. An interesting feature introduced in BusinessWorks 6.9.1 is the capability to send or receive a file using HTTP Send and HTTP Receive activities without having to load the whole file content in memory. With this new feature files are sent or received in chunks of a limited size and directly read from disk or wrote to disk. Such approach is sometimes referred to has file streaming. This blog article is to explain how to use this new feature. Sending a file over HTTP The ‘Send HTTP Request’ activity has to be configured with the following: . In the General tab, select an available HTTP Client resource, or createn a new one, and set the Post Data Type configuration option to ‘File’ . In the Input tab — Set the ‘Method’ field to “POST” — Set the ‘FilePath’ field to the full path of the file to be sent — Set the ‘Time out’ field to an Integer value (in milli seconds — for example 60 000 for a minute) — Set the ‘Dynamic Headers’ -> ‘Header’ -> ‘Name’ to “Content-Disposition” — Set the ‘Dynamic Headers’ -> ‘Header’ -> ‘Value’ to “attachment; filename=<file name at reception>” (for example ClientFile.txt) Receiving a file over HTTP The ‘Receive HTTP’ activity has to be configured with the following: . In the General tab, select an available HTTP Connection resource, or create a new one, and set the Output Style configuration option to ‘File’ . In the Advanced tab : — Check the ‘Write to File’ option — Set the Buffer Size to an integer value (in bytes — the default value is 1024) — Set the Directory to the name of the directory where received files are written — Optionally you can set the ‘Threshold Data’ option to a value (in bytes), when the value is zero files are always written to the defined target directory, when the value is greater than zero received files are written to disk only if they are greater than this value . Don’t forget to include a ‘Send HTTP Response’ activity after the ‘Receive HTTP’ activity

During performance or volume tests, or while working in the analysis of a complex issue, it is sometimes useful to view what is going on within an Appnode JVM to be able to identify bottlenecks and improve the Appnode or the BusinessWorks applications runtime configuration. This is also useful to compare the behavior of different Garbage Collectors or to evaluate different Garbage Collector configurations. This article is to explain how to monitor a BusinessWorks Appnode using JMX and the open source solution JVisualVM. Configure the appnode to enable JMX This can be done with the following: . Go to the target appnode ‘bin’ directory, this is in the following form: <TIBCO_HOME>/bw/6.X/domain/<DOMAIN_NAME>/appnodes/<APPSPACE_NAME>/<APPNODE_NAME>/bin . Edit the .tra file of the appnode . At the end of the file add the following lines java.property.com.sun.management.jmxremote=true java.property.com.sun.management.jmxremote.port=9614 java.property.com.sun.management.jmxremote.local.only=false java.property.com.sun.management.jmxremote.authenticate=false java.property.com.sun.management.jmxremote.ssl=false . Restart the appnode Note : if you need to monitor multiple appnodes you have to use a unique port number of each appnode Install JVIsualVM JVisualVM is an open source solution, it can be downloaded at the following URL: https://visualvm.github.io/download.html To install it you just have to unzip the downloaded package in the directory of your choice. JVisualVM needs a Java JDK 8 at minimum to run, if you don’t have a Java JDK 8 available in your environment you have install one (you can use OpenJDK 8 for example). If your JDK installation is included in your environment path you can use JVisualVM directly otherwise you have to update the default JVisualVM configuration: . Go in the JVisualVM configuration directory <JVISUALVM_HOME>/etc . Edit the file jvisualvm.conf . Uncomment the following line and add the path to your JDK change #visualvm_jdkhome=”/path/to/jdk” to visualvm_jdkhome=c:\tools\OJDK8 Monitor the appnode with JVisualVM Once JVisualVM is launched use the “File -> Open JMX connection” menu option, the following dialog open: Enter your target appnode hostname and JMX port and click OK: The target appnode now appears in the application tab: Right click on it and select ‘Connect’, then right click again and select ‘Open’, the Overview tab is showing up: You can select the Monitor tab to monitor the CPU usage, Heap size and usage, and Classes and threads related statistics: You can select the Threads tab to view Threads that are used by the Appnode: Finally you can use the ‘Heap Dump’ button to generate a ‘Heap Dump’ for further analysis: Additional elements for a memory leak analysis In the context of a memory leak analysis you can the use Eclipse Memory Analyser to check a Thread Dump generated by JVisualVM. This tool, from the Eclipse Fundation, can be downloaded at the following URL: https://projects.eclipse.org/projects/tools.mat/downloads Additional elements for BusinessWorks 5.X The same approach can be used with a BusinessWorks 5.X engine. You just have to update the .tra file of the target application to add the properties mentioned above. The .tra file of an application is located in the following directory: <DOMAIN_HOME>/application/<APPLICATION_NAME>

In BusinessWorks 6.X it is possible to deploy multiple applications in an appspace and then to have at run time multiple applications running in the same appnode. In the default configuration all the running applications log messages are going to the appnode log file ‘bwappnode.log’ located in the target appnode log directory (<TIBCO_HOME>/bw/6.X/domains/<DOMAIN_NAME>/appnodes/<APPSPACE_NAME>/<APPNODE_NAME>/log). In order to ease application trouble shooting it is possible in recent BusinessWorks releases, precisely since BusinessWorks 6.6.0, to have a separate log file for each application. This article is to explain how to set-up such configuration and the limitations to be considered. How to configure an appnode to have separate log files per application This can be done with the following: . Go to the target appnode directory <TIBCO_HOME>/bw/6.X/domains/<DOMAIN_NAME>/appnodes/<APPSPACE_NAME>/<APPNODE_NAME> . Edit the config.ini file to add the following property: bw.engine.separate.logs.by.app=true . Edit the logback.xml file to add the following tag in the root logger definition: <appender-ref ref=”APPLICATION-FILE”/> . Restart the appnode With this configuration application logfiles are written next to the bwappnode.log file in the target appnode log directory. The application log file names are in the form <application_name>.application.log. It is possible to add some loggers configured with the DEBUG level in the configuration above by including the following tag in their definition: <appender-ref ref=”APPLICATION-FILE”/> For example it is possible to add the DEBUG trace of the REST/JSON palette in the application log file using the following logger definition: It is also possible to control log messages destination at logger level, you can refer to the BusinessWorks documentation for more details. Limitations to be considered . Application start and stop messages (Starting, Started, Stopping, Stopped,...) remain in the appnode log file . Third party loggers, like for example the apache and jetty loggers, do not support logging in separate application log files. The related log messages remain in the appnode log file . When multiple versions of the same application are deployed in the same appspace the logs of the different versions of the application are going to the same file Since BusinessWorks 6.10 it is possible to have the full application version (major.minor.patch) included in the log by adding the following property in the appnode config.ini file: bw.frwk.version.format=true Reference elements BusinessWorks documentation: https://docs.tibco.com/pub/activematrix_businessworks/6.10.0/doc/html/Default.htm#administration/application-logging.htm Article explaining how to configure logging at activity level: https://community.tibco.com/articles/tibco-activematrix-businessworks/bw6x-bwce-how-to-enable-activity-level-logging-in-businessworks-6x-and-businessworks-container-edition-r3383/

While this is common in integration projects to have to manage the same integration scenario for different business objects this translate in having to implement the same flow multiple times but with different Schemas and Mappings in BusinessWorks. To help manage such requirements recent BusinessWorks versions support creating a template from a project and creating a new project using such template. This new blog article is to explain how to use this feature. Creation of a template Create an application skeleton in Studio having in mind this will become a template used to create a number of actual applications. For example you can create a template of an application processing JMS messages that would includes . A JMS connection resource . The properties needed to configure such resource . A process with a JMS Receive Message activity, logging activities, a call to a sub-process containing the business logic to implement in each variant and a default error handler Once your template application is created, you can create a template with the following: . Right click on the application you want to use to create a Template . Select Export -> Studio Projects as Template A panel similar to the example below appears: . Click on Select Dependencies and select a target folder to manage the templates . Click Next, , a panel similar to the example below appears Update the proposed Name and Version and add a Description as needed. . Click Finish . After 10 to 20 seconds you can check the template as been created in the specified template folder Note that a template file is in zip format and can be unzipped if needed. Creation of an application from a template You can create a new BusinessWorks project from a template with the following: . Right click in the Project Explorer area . Then select the menu New -> BusinessWorks Project from Template In the panel that appears, select the template project you want to use: . Click Next, a panel similar to the example below appears . Click Next , a panel similar to the example below appears You can update the Application Name and Module Name by selecting the existing name in the column on the left and entering the new name in the column on the right. . Click Finish You now have to add the elements needed to fully implement the new application instance, this would include the schema describing the message received over JMS, the resource describing the back-end service that need to be called and the sub process doing the needed mappings and calling the back-end. Reference elements BusinessWorks documentation https://docs.tibco.com/pub/activematrix_businessworks/6.10.0/doc/html/Default.htm#app-dev-guide/exporting-a-project-.htm?Highlight=Template https://docs.tibco.com/pub/activematrix_businessworks/6.10.0/doc/html/Default.htm#app-dev-guide/creating-a-project-f.htm?Highlight=Template

An interesting feature introduced by Hawk 6.X is the capability to invoke available Hawk methods using a generic REST API. In a BusinessWorks context this allows to easily collect KPI’s available in Hawk and integrate them into custom dashboards or reports. Note that you need to have a valid Hawk licence to be able to use the Hawk component exposing the REST API in both BusinessWorks 6.X and BusinessWorks 5.X environments. For BusinessWorks 5.X you have to use BusinessWorks 5.15 or higher while previous releases are not using the Hawk 6.X version. This new article explains how to use the Hawk REST API to invoke methods exposed by both the BusinessWorks 6.X and BusinessWorks 5.X microagents. Architecture The Hawk REST API is exposed by a new component introduced in Hawk 6.X that is the Hawk Console. To be able to use the Hawk REST API an instance of this component should be running on one of the server of the configuration. When a method of the Hawk REST API is called the Hawk Console forward the call to the target Hawk Agent that itself send it to the target micro-agent, once the micro-agent replies the Hawk Agent forward the reply to the Hawk Console that finally put it in a generic JSON format and returns it to the caller. Prerequisites to use the Hawk REST API You need to make sure there is an Hawk Console running in your target environment and you have the following elements: . The hostname and port to use to access the Hawk Console . A username and password allowing to connect to the Hawk Console By default the Hawk Console is available on the following URL: http://<host>:8083/HawkConsole For example: http://server1:8083/HawkConsole By default you can connect with the usual admin/admin. The Hawk Console should also be configured to access the target Hawk domain. If needed this can be done with the following: . Click the “+’ button on the right of the page (in the middle) . Enter the details for your target domain All details of the target Hawk domain have to be entered, you may need to scroll to see all parameters. . Click ‘Configure’ once all details have been entered. Checking the Hawk REST API The Hawk Console is managing a page in Swagger UI format where can be found the list of available Hawk REST API methods and details on the methods. It also possible to test the methods on line. By default this page is available on the following URL: http://<host>:8083/HawkConsole/v1/docs For example: http://server1:8083/HawkConsole/v1/docs The available REST methods are available in Swagger UI format: Calling the Hawk REST API — Getting needed details on the target domain This is generally useful to call the GET {domain}/agent API to get details about the target domain. This can be done from the Swagger UI page: . First select the GET /{domain}/agent method . Enter the name of the target domain (‘default’ in the example below) . Click ‘Try it Out’ Enter the username / password that you have to connect to the HawkConsole. . Check the output In the output we can see the value of the ‘dns’ parameter that is useful to do further calls. Calling the Hawk REST API — Listing available micro-agents for a given Hawk Agent . This can be done with the following method GET /{domain}/{dns}/{agent}/Microagent We have to use the domain, dns and agent name we got from the previous call. . Click ‘Try it Out’ . Check the target appnode Hawk micro-agent is present in the output For example: In the screen shot above we can see the microagent ‘name’ and ‘nameWithInstance’. Calling the Hawk REST API — Calling an Hawk method for a given BW 6.X Hawk micro-agent . This can be done with the following method POST /{domain}/{dns}/{agent}/invoke . Calling the method We have to use the domain, dns and agent name we got from the previous call. We also have to create a body for the call, for example to call the ‘GetApplicationDetails’ method of the BW 6.X Hawk microagent we have to create the following body (note that we have to use the microagent ‘nameWithInstance’ we got from the previous call): { “microagent”: “AS04-AN02-HMA:0”, “method”: “GetApplicationDetails”, “param”: { } } . Click ‘Try it Out’ . Check the output In a generic JSON format we have the list of deployed applications in the target appnode and details for each application including its name, version and state. Calling the Hawk REST API — Calling an Hawk method for a given BW 5.X Hawk micro-agent . This can be done with the following method POST /{domain}/{dns}/{agent}/invoke (as for BW 6.X) . Calling the method We have to use the domain, dns and agent name using the approach explained earlier. We also have to create a body for the call, for example to call the ‘GetExecInfo’ method of the BW 5.X Hawk microagent we have to create the following body (note that we have to use the microagent ‘nameWithInstance’ we got using the approach explained earlier): { “microagent”: “ COM.TIBCO.ADAPTER.bwengine.bw514.HelloWorld.HelloWorld:0”, “method”: “GetExecInfo”, “param”: { } } . Check the result The output of the Hawk method is available in a generic JSON format.

This article is to explain how to use the bwagent REST API in BusinessWorks 6.X. It is important to secure the bwagent REST API and this is explained in this other article: https://community.tibco.com/articles/tibco-activematrix-businessworks/bw6x-security-how-to-secure-the-bwagent-rest-api-r3417/ API documentation The API is documented in the form of an interactive Swagger UI. The Swagger UI can be used with the following: # Start the bwagent with the apiserver option . Note that this can be done even if the ‘real’ bwagent is running on the server . go to the <TIBCO_HOME>/bw/6.X/bin directory . Launch the bwagent with the ‘apiserver’ option, like this ./bwagent apiserver (Linux) bwagent apiserver (Windows) # Navigate to the Swagger page . By default it is available on the 5555 port http://localhost:5555/index.html Using the API The swagger UI doesn’t allow to directly use the API but it provide all details needed to call the API. For example in the Swagger UI it is possible to get details on the /browse/appnodes method and to try it: Note that the methods are not really called from the Swagger UI, but in the results section you get the URL to use to call this method: This URL then need to be updated to be able to call the ‘real’ API exposed by the bwagent: . The /api part should be replaced by /bw/v1/ . The hostname refer to the host where the target bwagent is running . By default bwagents expose the REST API on the 8079 port So to call the /browse/appnodes method on my ‘TESTEM’ domain I have to use the following URL: GET http://localhost:8079/bw/v1/browse/appnodes?domain=TESTEM Then this URL can be used in a tool like Postman: Note that the bwagent port used to expose the REST API can be configured by adjusting the following property in the bwagent.ini file: bw.agent.http.port Reference elements https://docs.tibco.com/pub/activematrix_businessworks/6.9.1/doc/html/Default.htm#administration/accessing-the-bwagen.htm

While supporting a BusinessWorks or a BusinessWorks Container Edition configuration one important point is to make sure that you are using TIBCO products versions that are supported. This article is to explain how to check a given product version is supported and if an end of support date is already defined. Messaging products General elements about Messaging products (TIBCO EMS, TIBCO FTL, and etc…) support are available here: https://support.tibco.com/s/article/TIBCO-Messaging-Products-Supported-Platforms-End-of-Support-Information Specifically the end of support dates for Messaging products are available in the form of a Google sheet available at the following URL: https://docs.google.com/spreadsheets/u/1/d/1Ibq9eNIFLmozmdRDiozd42IhPgnaL3X5x45k0ZWEoqc/htmlview From that page you just need to select the tab corresponding to the product you want to check. For example for TIBCO EMS you have to display the EMS tab. In the screen shot above you can see that EMS 8.4 is no longer supported. In this other example below you can see that EMS 8.6 will be supported under RHEL 8.X until end of December 2024. In the additional example below you can see that EMS 10.2, that is the current EMS version, has no end of support date announced for most of the supported platforms. This means it will be supported at the very least for an extra year from the date you are checking and this is very likely to be more. Integration products End of support dates for Integration products, and other products, are available in the form of a WEB Page available at the following URL: https://support.tibco.com/s/end-of-support Enter the name of the product you are looking for in the Search area, and then look for the version you are using. In the example below we can see that BusinessWorks 5.13, 5.13.1 and 5.13.2 will reach end of support at the end of January 2024. In this other example below you can see that BusinessWorks 6.6.0 and 6.6.1 are no longer supported since July 2023 but Extended support is available, you can also see that BusinessWorks 6.7.0 will be supported under December 2024 and extended support will be available. Extended support is available at an extra cost and it is generally for an extra year of support. Note also that on the example above we don’t see Business 6.8.x and 6.9.x which are current versions with no end of support announced. This means those versions will be supported at the very least for an extra year from the date you are checking and this is very likely to be even more. In the case you won’t find a product or a version that would be relatively old in the ‘end of support’ page I would suggest to contact a TIBCO representative. Reference elements Reference elements from TIBCO support about end of support dates: https://support.tibco.com/s/article/Tibco-KnowledgeArticle-RetirementNotice-40036 Elements about platform support policy: https://support.tibco.com/s/article/Platform-Support-Policy-for-TIBCO-Products General elements about TIBCO support: https://docs.tibco.com/pub/tibco-support-guide/html/Default.htm

While installing a BusinessWorks 6.X configuration an important task not to forget is to secure the bwagent REST API. This new article explains how to implement this configuration best practice. #1 Update the bwagent.tra file . Go to the <TIBCO_HOME>/bw/6.X/bin directory . Edit the bwagent.tra file . Uncomment the following line #java.property.java.security.auth.login.config=%BW_HOME%/config/jaas.login.conf The file pointed by the property is the default JAAS configuration file, it contains a reference to the default bwagent realm properties file. By default this file is <TIBCO_HOME>/bw/6.X/config/realm.properties #2 Update the default admin user password in the bwagent realm properties file . By default the file contains an admin user with a default password (‘admin’) The format of the file is the following: <username>: <PASSWORD FORMAT>:<PASSWORD>, <ROLE> The two default users admin and bwappnode have an ‘admin’ role and can use all methods of the bwagent REST API. Roles are pre-defined in the bwagent (and independent from the roles managed in the TEA), the available roles are the following: admin, operator & user. Roles definitions are the following: Users with ‘admin’ role can performs all Operations (Create Domains, Appspaces, Appnodes, Upload/Deploy EAR, Start and Stop and Delete) Users with ‘operator’ role can only read and do lifecycle operations (start/stop components) Users with ‘user’ role only have read access . Choose a new password (for example ‘Tibco123’) . Go to the <TIBCO_HOME>/bw/6.X/system/lib/tea folder . Use Java with the -cp option to call the Jetty password utility This can be done with the following: java -cp jetty-util-<version>.jar org.eclipse.jetty.util.security.Password <username> <password> For example (in BW 6.8.1 with TEA 2.4.1) : java -cp jetty-util-9.4.44.v20210927.jar org.eclipse.jetty.util.security.Password admin Tibco123 . Update the bwagent realm properties file with the new password (using the CRYPT format) For example: . Save the file and restart the bwagent (if you want to test the change) #3 Update the default bwappnode password in the bwagent realm properties file . By default the file contains a bwappnode user with a default password . Choose a new password (for example ‘AppNode123’) . Encrypt the new password as explained above for the admin user . Update the bwagent realm properties file with the new password (using the format of your choice but the CRYPT format is the most secure) For example: There is nothing more to do while this is the bwagent sharing the password to use with the appnode. . Save the file and restart the bwagent (if you want to test the change) #4 Create additional users (if needed) In case the bwagent REST API would be used for other purposes, like monitoring the configuration or doing basic administration tasks, additional users can be created and set to a role supporting the minimum needed access rights. To create a user with read only access to the bwagent REST API you can do the following: . Choose a name and a password (for example monitor and ‘Mon123’) . Encrypt the new password as explained above for the admin user . Add a line for the new user in the bwagent realm properties file For example: monitor: CRYPT: mo12/2gQkJ3v.,user . Save the file and restart the bwagent #5 Testing the configuration Example of the admin user calling the agent/refresh method: Example of the monitor user calling the browse/appspaces method: Additional elements The BusinessWorks MAVEN plugin must use a user with the ‘admin’ role. Additional configuration options are available to: . Use a Digest authentication instead of a Basic authentication . Connect the bwagent to an Enterprise Directory using LDAP or LDAPS . Configure the bwagent to expose its REST API over HTTPS All these options are detailled in the BusinessWorks documentation. Reference elements Reference elements about securing the bwagent REST API are available in the BusinessWorks administration guide in the ‘Securing the bwagent REST API’ section: https://docs.tibco.com/pub/activematrix_businessworks/6.10.0/doc/html/Default.htm#administration/securing-the-bwagent.htm

By default when a BusinessWorks application is started all its Process Starters, or Components, are started meanwhile in some use cases it is useful to disable a Process Starter at start-up and to enable it in a later stage either within the BusinessWorks application logic or from an external component. This article is to explain how to do this in different way: . Using the TEA . Using the bwagent REST API . Using a bwadmin command It is important to keep in mind that this configuration is persisted locally on the BusinessWorks server and disabling or re-enabling the automatic start for a Process Started will be in effect at the next application start-up even if the Process Starter is enabled or disabled while the application is running. How to configure a Process Starter or Component Auto Start using the TEA By default all Process Starters or Components of an application are configured to start when the application is started (‘Auto Start’ enabled). This can be updated using the ‘Applications’ panel of the TEA, selecting an application, opening the ‘Components’ tab, selecting a Process Starter or Component and then updating the ‘Auto Start’ option. Note that this configuration is managed at application level (for all appnodes). How to configure a Process Starter or Component Auto Start using the bwagent REST API A Process Starter or Component Auto Start can be disabled using the following bwagent REST API method: PUT /bw/v1/domains/<DOMAIN_NAME>/appspaces/<APPSPACE_NAME>/applications/<APPLICATION_NAME>/<VERSION>/component/autostart/disable?components=<COMPONENT_NAME> Example: PUT http://localhost:8079/bw/v1/bw/v1/domains/TESTEM/appspaces/AS04/applications/TestApp.application/1.0/component/autostart/disable?components=ComponentJMSReceiver A Process Starter or Component Auto Start can be re-enabled using the following bwagent REST API method: PUT /bw/v1/domains/<DOMAIN_NAME>/appspaces/<APPSPACE_NAME>/applications/<APPLICATION_NAME>/<VERSION>/component/autostart/enable?components=<COMPONENT_NAME> How to configure a Process Starter or Component auto start using bwadmin A Process Starter or Component Auto Start can be disabled using the following bwadmin command: disablecomponentautostart -d <DOMAIN_NAME> -a <APPSPACE_NAME> <COMPONENT_NAME> <APPLICATION_NAME> <VERSION> Example: disablecomponentautostart -d TESTEM -a AS04 ComponentJMSReceiver TestApp.Application 1.0 A Process Starter or Component Auto Start can be re-enabled using the following bwadmin command: enablecomponentautostart -d <DOMAIN_NAME> -a <APPSPACE_NAME> <COMPONENT_NAME> <APPLICATION_NAME> <VERSION> How to enable a Process Starter or Component at runtime within BusinessWorks A Process Starter or a Component disabled at start-up can be enabled at runtime within the BusinessWorks application logic using the ‘Engine Command’ activity configured with the ‘ResumeProcessStarter’ Command and the target Process definition name. This action is only for the current runtime environment and at the next application start-up this is the ‘Auto Start’ configuration of the Process Starter or Component that will apply. Similarly, a Process Starter or a Component can be disabled at runtime within the BusinessWorks application logic using the ‘Engine Command’ activity configured with the ‘SuspendProcessStarter’ Command. How to enable a Process Starter or Component at runtime using the bwagent REST API A Process Starter or a Component disabled at start-up can be enabled at runtime using the following bwagent REST API method: POST /bw/v1/domains/<DOMAIN_NAME>/appspaces/<APPSPACE_NAME>/applications/<APPLICATION_NAME>/<VERSION>component/<COMPONENT_NAME>/start This action is only for the current runtime environment and at the next application start-up this is the ‘Auto Start’ configuration of the Process Starter or Component that will apply. Example: http://localhost:8079/bw/v1/domains/TESTEM/appspaces/AS04/applications/TestApp.application/1.0/component/ComponentJMSReceiver/start Similarly, a Process Starter or a Component can be disabled at runtime within the BusinessWorks application logic using the following bwagent REST API method: POST /bw/v1/domains/<DOMAIN_NAME>/appspaces/<APPSPACE_NAME>/applications/<APPLICATION_NAME>/<VERSION>component/<COMPONENT_NAME>/stop

Security is more and more a concern in integration projects and this includes securing the connections to the enterprise email server. This article explains how to connect to an SMTP email server using TLS 1.2 from BusinessWorks and BusinessWorks Container Edition, this is illustrated in the article by the set-up of a connection to the Microsoft outlook.com email cloud service that is using TLSv1.2. Pre-requisites You need to have the public certificates of the target SMTP server in a common format (for example .crt or .cer files). You need to know the hostname and port used by the target email server. For outlook.com the host and port to use are the following: smtp-mail.outlook.com:587 Reference elements are available on the Microsoft support site: https://support.microsoft.com/fr-fr/office/param%C3%A8tres-pop-imap-et-smtp-pour-outlook-com-d088b986-291d-42b8-9564-9c414e2aa040 Downloading the outlook.com public certificates To do this you need to use opensll, the Windows version of this open source tool can be downloaded from the following URL: https://slproweb.com/products/Win32OpenSSL.html Once installed you have to use the following command to get the certificates: openssl s_client -starttls smtp -showcerts -connect smtp-mail.outlook.com:587 From the output of the command you can just copy / paste certificates to a text file using the .crt extension one by one (make sure to have one text file per certificate and to include the ‘BEGIN CERTIFICATE’ and ‘END CERTIFICATE’ tags as shown below). Keep the certificate files in a local folder on your machine. Example on how the certificates folder content should look like: Creating a keystore file This can be done with the Key Store Explorer tool available at the following URL: https://keystore-explorer.org/ With Key Store Explorer you have to do the following: . Import the certificates, this can be done with the ‘Examine -> Examine File’ menu . Once a file is opened the corresponding certificate can be imported, using the ‘Import’ button When asked to create a new KeyStore select the Key Store type and click OK Then accept the default certificate alias: . Once done with all the certificates save the KeyStore file You will have to set a password and enter the target file name. Keep the keystore file path and password for later use. Updating the application You have to do the following: . Create the properties needed to configure an SMTP Connection resource . Create properties needed to configure a Key Store Configuration resource . Create a Key Store Configuration resource The resource has to be configured with: The path to the target keystore file The type of the keystore file The password of the target keystore file . Create an SSL Client Configuration resource The resource has to be configured with: The reference to the Trust Store resource The target encryption protocol (it is generally recommended to use TLS 1.2 at a minimum) It is a good practice to use ciphers using at least 256 bit encryption. . Create an SMTP Connection shared resource The following configuration parameters can be set using the properties previously created: Machine Name Port Username Password When connecting to outlook.com or a Microsoft Exchange server make sure to check the ‘Enable STARTTLS’ option. Then check the ‘Confidentiality’ option and select the SSL Client Configuration resource previously created. . Then the ‘Send Mail’ activity must be configured with the following: In the ‘General’ tab select the SMTP Configuration resource previously created: In the ‘Input’ tab map the input fields as needed : Testing the application in the Debugger The application can then be tested in the Studio Debugger. In case of problems you can add the following property in the JVM Arguments: -Djavax.net.debug=ssl,handshake,plaintext,record This can be done in the ‘Arguments’ tab of the Run -> Debug Configuration panel : With this option the SSL/TLS negociation messages will be logged in the Designer Console Window. You may also have a look the following TIBCO support KB article: https://community.tibco.com/s/article/common-errors-tibco-activematrix-businessworkstm-related-ssl-communication Using the certificates in deployed mode You have to do the following: . Copy the certificate files to the target BusinessWorks servers . Set the application properties according to the target environment Integration with a Microsoft Exchange server With the elements above you should be able to connect to an on-premises Microsoft Exchange Server. In such configuration you need to use the public certificates of the target Microsoft Exchange Server.

This is quite common in integration projects to have to extract large volumes of data from a database or to have to insert large volumes of data in a database. A challenge with such use cases is that the number of rows to manage can be very high (tens of thousands and even hundreds of thousands) and in such case it is not possible to handle the whole data set in memory and it is necessary to process data by blocks of a limited size. This is something that BusinessWorks can do while doing SQL select and insert queries and this new blog article explains how to do it. It is recommended to use the BusinessWorks Memory Saving Mode with this pattern. Inserting data by blocks in a database To insert data by blocks you have to do the following: . Configure the ‘JDBC Update’ activity to do batch updates by just checking the ‘Batch Update’ option in the Advanced tab: . After doing this the ‘Record’ element in the Input tab is changed to be repeating: . Then you just have to map the input list in the ‘Record’ list using a for-each, like for example: Using this approach the records in the Input will be inserted in a single SQL statement and it is much faster than doing it record by record. Extracting data by blocks from a database To extract data by blocks you have to do the following: . Configure the ‘JDBC Query’ activity to do batch query by just checking the ‘Process in Subsets’ option in the Advanced tab: . After doing this the ‘Record’ element in the Output tab is changed to be repeating and a Boolean flag ‘lastSubset’ is added in the Output: . Also an integer field ‘subsetSize’ is added in the Input, this field has to be mapped to define the number of rows to be processed at each iteration (common values are between 100 and 1000 depending on the size of the rows): . It is important also to make sure the ‘Maximum rows’ property from the ‘General’ tab is set to 0 (zero) to read all the available rows: . Then include the ‘JDBC Query’ activity in a Repeat group and set the exit condition with the ‘lastSubset’ flag: Using this approach a batch of records are extracted at each iteration using a single SQL statement and it is much faster than doing it record by record. Additional elements It is possible to implement some kind of ETL (‘Extract Transform and Load’) scenarios using the technics described in this article combined with the mapping technics described in this previous article: https://community.tibco.com/articles/tibco-activematrix-businessworks/bw6x-bwce-complex-mapping-scenarios-in-businessworks-6x-and-businessworks-container-edition-r3382/ It is also possible to combine the technics described in this article with the large files processing technics described in this previous article: https://community.tibco.com/articles/tibco-activematrix-businessworks/bw6x-bwce-how-to-process-larges-files-in-businessworks-and-businessworks-container-edition-r3413/ Using those elements the following use case can be implemented: . Query a source database to extract data . Put the extracted data in a file . Transfer the file to a target location . Insert data from the file into a target database Example of a process reading data from a file by blocks and inserting the data blocks in the target database, each block is inserted using a single JDBC Insert activity and a single SQL statement: Example of a process extracting data from a database by blocks and writing the data blocks to a target file, each block is extracted using a single JDBC Query activity and a single SQL statement: Reference elements It is recommended to use the BusinessWorks Memory Saving Mode with this pattern. Details are available in the following article: https://community.tibco.com/articles/tibco-activematrix-businessworks/bw6x-bwce-bw5x-how-to-enable-engine-memory-saving-mode-in-businessworks-6x-and-businessworks-container-edition-r3359/ Additional elements You can refer to the attached demo project. LargeVolumeDBDemo.zip

While we are in the API age and nowadays everybody is talking about API Led Integration the truth is that in many companies files are still widely used to transfer large volumes of data. BusinessWorks has some rich native capabilities to access files (read, write, move…), parse / render different file formats (fixed format, delimited format, XML format…) and transform data. A common challenge with files is that they can be very large (hundreds of Megabytes and even multiple Gigabytes) and in such case it is not possible to handle the whole content of a file in memory and it is necessary to process files by blocks of a limited size. This is something that BusinessWorks can also do and this new blog article explains how to do it. It is recommended to use the BusinessWorks Memory Saving Mode with this pattern. # Files of fixed and delimited formats For such files it is possible to use the Parse palette that allows to read and write files by blocks of a limited size. The general approach for reading and parsing files by blocks is the following: . Use the Parse Data activity configured with Input Type = File and with a given number of Records defined in the Input tab . Include the Parse Data activity in a ‘Repeat’ group and configure the exit condition to be the ‘done’ flag available in the output of the Parse activity, this flag is set once the End of File is reached. The general approach for formatting and writing files by blocks is the following: . Use the Render Data activity with a list of records in Input . Use the Write File activity configured with the ‘Append’ option to write in the output file . Include those activities in a ‘Repeat’ group and exit once all input records have been processed The sample process below includes reading and parsing an input file fragment, doing a simple transformation and then rendering and writing the result in the output file. This Process also shows an error management approach where in case a line of the Input file cannot be parsed it is logged in an error file and processing continues. Sample process creation . First you need to create an XML schema defining the format of the input file . Then you need to create a DataFormat resource for the input file . Create an XML schema defining the format of the output file . Create a DataFormat resource for the output file . Add a ParseData activity in the process There is no specific option to set for processing by block at this level except the ‘Continue On Error’ option if you want to manage errors in the suggested approach: In the Input tab make sure to set the Number of Records to be read at each iteration (a good practice is to manage this using a property): Important : If you don’t specify the ‘Start Record’ the activity automatically continues to read the file from where it was left at the previous iteration. This is recommended to use this approach for optimal performances (instead of specifying the ‘Start Record’ number in the Input of the activity). . Include the ParseData activity in a RepeatLoop The repeat loop has to be configured with the exit condition set with the ‘done’ flag available in the output of the Parse Data activity. . Add in the process a RenderData activity There is no specific option to set for processing by block at this level: In the Input tab of the activity map the list of records to be formatted with the needed transformations (in the example Process this is using the output of the previous Parse Data activity): . Add in the Process a WriteFile activity The Write File activity has to be configured with the ‘Append’ option set. The Input tab of the Write File activity has to be configured with the output of the Render Data activity: Error management Parsing errors can be managed with the following approach: in case a line of the Input file cannot be parsed it is logged in an error file and processing continues. This can be done with the following: . In the Parse Data activity make sure the following option is checked: . In case there is at least an element in the ‘Error Rows’ list make a transition to a Write File activity that will write the problematic input lines to an error file Configuration of the Transition: Configuration of the Write File Input: Reference elements BusinessWorks Parse Data documentation: https://docs.tibco.com/pub/activematrix_businessworks/6.10.0/doc/html/Default.htm#binding-palette/parse-data.htm It is recommended to use the BusinessWorks Memory Saving Mode with this pattern. Details are available in the following article: https://community.tibco.com/articles/tibco-activematrix-businessworks/bw6x-bwce-bw5x-how-to-enable-engine-memory-saving-mode-in-businessworks-6x-and-businessworks-container-edition-r3359/ XML schema for the sample Input file <?xml version="1.0" encoding="UTF-8"?> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" targetNamespace="http://exemple.com/Data" xmlns:tns="http://exemple.com/Data" elementFormDefault="qualified"> <xs:element name="Data" type="tns:DataType"/> <xs:complexType name="DataType"> <xs:sequence> <xs:element name="LineNumber" type="xs:string"/> <xs:element name="Field1" type="xs:string"/> <xs:element name="Field2" type="xs:string"/> </xs:sequence> </xs:complexType> </xs:schema> XML schema for the sample Output file <?xml version="1.0" encoding="UTF-8"?> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" targetNamespace="http://exemple.com/Output" xmlns:tns="http://exemple.com/Output" elementFormDefault="qualified"> <xs:element name="Output" type="tns:OutputType"/> <xs:complexType name="OutputType"> <xs:sequence> <xs:element name="LineNumber" type="xs:string"/> <xs:element name="OutputField" type="xs:string"/> </xs:sequence> </xs:complexType> </xs:schema> # Files of IBM CopyBook format The ‘Parse Copy Book’ activity of the Data Conversion Plugin is able to process files in a similar way than the standard Parse palette. The options highlighted below have to be used: . Multiple Records . Input type= File Specify the number of Records to be read at each iteration: # Files of XML format The ‘Large XML’ Plugin provides activities to parse / render XML files without having to load the whole file contents in BusinessWorks memory. For example the ‘Get Fragment’ activity can be configured to read a number of given elements from the source XML file (say 100 ‘order’ elements) and can be included in a loop that will repeat until the end of the file. Additional elements While in many cases files are created from database extracts and databases are loaded with data coming from files you may also have a look to the following article explaining how to manage SQL queries handling large data volumes in BusinessWorks and BusinessWorks Container Edition. https://community.tibco.com/articles/tibco-activematrix-businessworks/bw6x-bwce-how-to-manage-sql-queries-handling-large-data-volumes-in-businessworks-and-businessworks-container-edition-r3414/ Additional elements You can refer to the attached project and sample data file. LargeFileProcessingDemo.zip MyFile.csv

Some integration scénarios requires to decode strings received in binary format or in the other way to encode strings in binary format. This article goal is to explain how to do this in BusinessWorks and BusinessWorks Container Edition. Decoding a string In such scénario BusinessWorks receives a byte string that contains an encoded character string, for example in UTF-8, and there is need to handle the character string as a String in BusinessWorks. In BusinessWorks a byte string is handled as a field of type Binary and internally managed as a base64 string. So what we need to do is simply to decode the base64 string with the encoding used by the sender application when creating the received byte string. This can be done using the following XPATH formula (if the source encoding is UTF-8): tib:base64-to-string(xsd:string($FilePoller/fileContent/binaryContent), “UTF8”) Note that internally BusinessWorks is using Unicode (UTF-16 encoding) to manage Strings. Encoding a string In such scénario BusinessWorks transforms a String in a byte string using a given encoding. In this case what we need to do is simply to encode the String in a base64 string with the needed encoding. This can be done using the following XPATH formula (in this example the target encoding is IBM297): xsd:base64Binary(tib:string-to-base64($Mapper/primitive, “IBM297”)) Useful elements The available encodings are the one supported by Java, the list is available here: https://docs.oracle.com/javase/8/docs/technotes/guides/intl/encoding.doc.html You can find more details on encoding in the following blog article from my colleague René Kiessling: https://medium.com/@rdkiessling/can-one-use-a-low-code-application-platform-for-data-exchange-with-legacy-systems-7f93aae716a3 Additional elements You can refer to the attached project. EncodeDecodeDemo.zip

While Oauth 2.0 is now the de facto industry standard for online authentication and authorization this is a very common requirement for BusinessWorks applications to have to use Oauth 2.0 tokens to call REST APIs. It is possible in BusinessWorks to call the standard Oauth 2.0 REST API to get and refresh a Token, store it in a Shared Variable and add it in the HTTP Authorization each time this is needed, but to make things more simple for developpers an ‘Oauth Configuration’ Shared Resource has been introduced with BusinessWorks 6.7.0 and BusinessWorks Container Edition 2.6.0. This article is to explain how to use this new resource. Things to know With BusinessWorks 6.7.0 and 6.8.x and BusinessWorks Container Edition 2.6.x and 2.7.x versions the ‘Oauth Configuration’ shared resource is only managed when using the ‘Invoke‘ activity with a REST Client binding. Starting from BusinessWorks 6.9.0 and BusinessWorks Container Edition 2.8.0 the ‘Oauth Configuration’ Shared Resource can be used with the ‘Receive mail’ activity. Starting from BusinessWorks 6.9.1 and BusinessWorks Container Edition 2.8.2 the ‘Oauth Configuration’ Shared Resource can be used with the ‘Invoke REST API’ and ‘HTTP Request’ activities. Creating an ‘Oauth Configuration’ Shared Resource It is recommended to first create properties to configure the ‘Oauth Configuration’ shared resource, this has to be done for the following fields: . Client ID of type String . Client Secret of type Password (which means the Client Secret is obfuscated in the BusinessWorks environment) . Token URL of type String . Environment of type String Then the resource has to be created and configured: . Set the configuration fields of the resource with the properties selected earlier . Set the Grant Type (Client Credentials or Resource Password) This is also generally needed to create an ‘SSL Client Configuration’ shared resource to access the Oauth 2.0 server and then configure the ‘Oauth Configuration’ shared resource to use it. The SSL Client Configuration’ shared resource can be created by following explanations available in that article: https://emarchiset.medium.com/how-to-configure-an-http-client-connection-to-access-a-rest-api-or-web-services-exposed-over-https-6b97dcfe1fb4 Once configured the ‘Oauth Configuration’ shared resource should look like this: The capability to get a Token can be tested using the Test Connection button: Using an ‘Oauth Configuration’ Shared Resource To use the created ‘Oauth Configuration’ shared resource you have to refer to it in an ‘HTTP Client’ shared resource by checking the ‘OAuth configuration‘ option and selecting the target ‘Oauth Configuration Provider’ in the Security section. There is nothing to do in the REST Client Binding once the HTTP Client resource has been configured. The Token refresh interval can be defined using the BUFFER_INTERVAL_FOR_REFRESH_TOKEN property (the value should be set in seconds). In Studio this can be set in the ‘Arguments’ tab of the ‘Debug Configuration’ dialog with the ‘-D’ option: In runtime this can be set with in the config.ini file of the target appnode, for example: BUFFER_INTERVAL_FOR_REFRESH_TOKEN=3600 Additional elements To debug issues with the Oauth Configuration Shared Resource you can add the following tags in the logback.xml file: <logger name=”com.tibco.bw.sharedresource.oauth”> <level value=”TRACE”/> <appender-ref ref=”STDOUT”/> </logger>

BusinessWorks 6.X and BusinessWorks Container Edition both come with bundled JDBC drivers supporting ORACLE, DB2, SQL Server, Postgres and MySQL. These drivers are also available in a BusinessWorks 5.X context after installing the Database Driver supplement, the BusinessWorks license includes access to those drivers for use with BusinessWorks and the TRA components. These drivers are bundled with the different BusinessWorks flavors in the scope of an EOM agreement with Progress Software that acquired the drivers from a company called MERANT Datadirect. Recent versions of BusinessWorks 6.X and BusinessWorks Container Edition are bundled with the Progress Datadirect drivers 5.1.4 release, this version is also included in the recent versions of the Database Driver supplement for BusinessWorks 5.X. The documentation of the drivers is accessible at the following URL: https://docs.progress.com/bundle/datadirect-connect-jdbc-51/page/DataDirect-Connect-Drivers.html The Database Driver supplement for use with BusinessWorks 5.X can be downloaded from the TIBCO edelivery site under the BusinessWorks section:

This article explains what to do to make the TEA response times stable in a BusinessWorks 6.X environment. The approach depends from the BusinessWorks version and the underlying Java version. If you are using MS SQL Server to manage the bwagents database there is also a JDBC driver option that can be used to improve performances. # BusinessWorks 6.4, 6.5, 6.6 and 6.7 (Java 😎 Configure the bwagent to use G1GC and possibly increase the Max Heap Size Edit the bwagent.tra file and, to remove the Java CMS garbage collector configuration options and enable the G1GC garbage collector, update the following line : java.extended.properties=-Xmx1024m -Xms256m -XX:+HeapDumpOnOutOfMemoryError -XX:SurvivorRatio=128 -XX:MaxTenuringThreshold=0 -XX:+UseTLAB -XX:+UseConcMarkSweepGC -XX:+CMSClassUnloadingEnabled with java.extended.properties=-Xmx1024m -Xms256m -XX:+HeapDumpOnOutOfMemoryError -XX:+UseG1GC In a large environment you may also increase the Java Heap Max Size with the following: java.extended.properties=-Xmx2048m -Xms256m -XX:+HeapDumpOnOutOfMemoryError -XX:+UseG1GC Configure the TEA to use G1GC and possibly increase the Max Heap Size Edit the tea.tra file and, to enable the G1GC garbage collector, update the following line : java.extended.properties=-Xms64m -Xmx512m -XX\:MaxPermSize=64m -XX:-HeapDumpOnOutOfMemoryError %TEA_START_PARAMS% with java.extended.properties=-Xms64m –Xmx512m -XX:+UseG1GC -XX:-HeapDumpOnOutOfMemoryError %TEA_START_PARAMS% In a large environment you may also increase the Java Heap Max Size with the following: java.extended.properties=-Xms64m -Xmx1024m -XX:+UseG1GC -XX:-HeapDumpOnOutOfMemoryError %TEA_START_PARAMS% # BusinessWorks 6.8 and 6.9 (Java 11) G1GC is the default garbage collector in Java 11. Edit the bwagent.tra file and, to remove the Java CMS garbage collector configuration options, update the following line : java.extended.properties=-Xmx1024m -Xms256m -XX:+HeapDumpOnOutOfMemoryError — illegal-access=deny — add-opens java.management/sun.management=ALL-UNNAMED — add-exports java.base/sun.reflect.generics.reflectiveObjects=ALL-UNNAMED — add-exports java.base/com.sun.net.ssl.internal.ssl=ALL-UNNAMED — add-exports java.base/com.sun.crypto.provider=ALL-UNNAMED -XX:SurvivorRatio=128 -XX:+UseTLAB -XX:+CMSClassUnloadingEnabled with java.extended.properties=-Xmx1024m -Xms256m -XX:+HeapDumpOnOutOfMemoryError — illegal-access=deny — add-opens java.management/sun.management=ALL-UNNAMED — add-exports java.base/sun.reflect.generics.reflectiveObjects=ALL-UNNAMED — add-exports java.base/com.sun.net.ssl.internal.ssl=ALL-UNNAMED — add-exports java.base/com.sun.crypto.provider=ALL-UNNAMED In a large environment you may also increase the Java Heap Max Size with the following: java.extended.properties=-Xmx2048m -Xms256m -XX:+HeapDumpOnOutOfMemoryError — illegal-access=deny — add-opens java.management/sun.management=ALL-UNNAMED — add-exports java.base/sun.reflect.generics.reflectiveObjects=ALL-UNNAMED — add-exports java.base/com.sun.net.ssl.internal.ssl=ALL-UNNAMED — add-exports java.base/com.sun.crypto.provider=ALL-UNNAMED Possibly increase the Max Heap Size of the TEA In a large environment you may increase the TEA Java Heap Max Size with the following: Edit the tea.tra file and update the following line: java.extended.properties=-Xms64m -Xmx512m -XX:-HeapDumpOnOutOfMemoryError — add-opens java.base/java.lang=ALL-UNNAMED %TEA_START_PARAMS% with java.extended.properties=-Xms64m -Xmx1024m -XX:-HeapDumpOnOutOfMemoryError — add-opens java.base/java.lang=ALL-UNNAMED %TEA_START_PARAMS% # Performances improvement when MS SQL Server is used to manage the bwagents database The property sendStringParametersAsUnicode managed by the Microsoft JDBC driver for MS SQL Server have an impact on bwagents performances when it is disabled. To implement this solution you have to update the bwagent.ini file on all machines of the target environment: . Edit the bwagent.ini file . Update the following line : bw.agent.technology.dbems.db.connectionURL=jdbc:sqlserver://esbserver1:1433;databaseName=BW681 with bw.agent.technology.dbems.db.connectionURL=jdbc:sqlserver:// esbserver1:1433;databaseName=BW681;sendStringParametersAsUnicode=false . Restart the bwagent Additional elements In a BusinessWorks 5.X environment you can also configure the TIBCO Administrator server and the Hawk agents to use the G1GC garbage collector (note that in a BW 5.15 environment Java 11 is used so G1GC is enabled by default).