Using the CLI scripts, you can upgrade existing JDBC drivers in the resource template of a runtime node or SystemNode. Executing the CLI scripts will update the driver across the entire AMX enterprise and also automatically install, sync, and restart the corresponding nodes. The default driver for the resource template is also updated in the ActiveMatrix Administrator database.

Notes: 
1. This procedure (CLI script) needs to be executed only once on the ActiveMatrix c, and no need to execute it on the remote runtime host machines. When executing it on the Administrator machine, it will automatically restart all the nodes (i.e., SystemNodes and runtime nodes on remote host machines) on which the JDBC driver version will be updated.
2. Currently the suggested steps provided in TIBCO ActiveMatrix® Service Grid 3.4.0  Administration document under Managing Resource Templates > Configuring Third-party Drivers > Upgrading a Third-party JDBC Driver Using the CLI is not accurate. Please follow instructions in the below procedure of this KB article.

All Supported OS Platforms. Note: This CLI script is a new feature of AMX version 3.4.0. If customer's environment is AMX 3.3.0, then this KB is not applicable, and the customer should follow the AMX 3.3.0 Documentation to perform JDBC driver upgrade.

Procedure:

1. Configure the new version third-party JDBC driver in TIBCO_HOME using the "Configure Third-Party Driver" option of the TIBCO Configuration Tool (TCT) wizard on SystemHost/SystemNode machine ONLY.  This step does not need to be performed on remote Host/Node machines or the SystemHostReplica/SystemNodeReplica machine.

2. Verify the 'updateJDBCDriver' target and action in the 'enterprise_build.xml' located in the folder <CONFIG_HOME>\admin\<enterprise>\samples\ .

<target name="updateJDBCDriver">
  <AMXAdminTask
   action="updateJDBCDriver"
   objectSelector="Enterprise"
   remote="true"
   propsFile="${instanceProperties}"
   dataFile="${dataFile}" 
   <!--
   options="dryRun"  
   -->
   failOnError="false"/>
 </target>
 
Note: You cannot set objectSelector to Environment/Node.
remote="true": Upgrades the features for remote nodes. (that is, nodes managed by remote hosts).
options="dryRun": If specified, features are not installed on the hosts or enabled on the nodes.

Note: Database operations are not performed when options="dryRun" is used. Hence, any log messages indicating that a feature has been removed or updated can be ignored. The logs are benign.

For more information on the other attributes, refer to the section Using Command-line Interface in TIBCO ActiveMatrix® Service Grid 3.4.0  Administration document.

3. Verify the following data in the enterprise_data.xml located in folder <CONFIG_HOME>\admin\<enterprise>\samples\ , and modify OldFeature and NewFeature versions if needed.

<OldFeature xsi:type="amxdata_base:FeatureID" componentID="com.tibco.tpcl.gen.oracle.jdbc.feature" version="11.2.100.001"/>
<NewFeature xsi:type="amxdata_base:FeatureID" componentID="com.tibco.tpcl.gen.oracle.jdbc.feature" version="19.3.0.001"/>

For example, to upgrade from "12.1.100.001" to "19.3.0.001" modify the entries as below:

<OldFeature xsi:type="amxdata_base:FeatureID" componentID="com.tibco.tpcl.gen.oracle.jdbc.feature" version="12.1.100.001"/>
<NewFeature xsi:type="amxdata_base:FeatureID" componentID="com.tibco.tpcl.gen.oracle.jdbc.feature" version="19.3.0.001"/>

4. Make sure all host instances (including SystemHost, SystemHostReplica (if applicable), and remote hosts) and nodes are up and running. If any hosts/nodes are down, try to bring them up. If there are some hosts/nodes that cannot be started up, then this CLI script execution will not upgrade the JDBC driver for those hosts/nodes, and users will need to manually upgrade drivers for those hosts/nodes via AMX Admin GUI. 

5. Invoke the command-line interface on the build file.
Note: Executing 'updateJDBCDriver' will automatically restart the corresponding nodes.

Sample Output

The following is a sample output of executing the updateJDBCDriver CLI target:

=====================================================================================================================
C:\ProgramData\TIBCO_HOME\tibco\data\admin\AMXBPM\samples>ant -f enterprise_build.xml updateJDBCDriver

Unable to locate tools.jar. Expected to find it in C:\Program Files\Java\jre1.8.0_261\lib\tools.jar
Buildfile: C:\ProgramData\TIBCO_HOME\tibco\data\admin\AMXBPM\samples\enterprise_build.xml
updateJDBCDriver:
[AMXAdminTask] 28 May 2021 09:58:14  INFO - Initializing JSSE's crypto provider class com.sun.net.ssl.internal.ssl.Provider in default mode
[AMXAdminTask] 28 May 2021 09:58:15  INFO - Connecting to AMX Admin server at 'https://W2K8Oracle:8120' as user 'root'.
[AMXAdminTask] 28 May 2021 09:58:15  INFO - Executing action 'updateJDBCDriver' for 1 objects from data file 'C:\ProgramData\TIBCO_HOME\tibco\data\admin\AMXBPM\samples\enterprise_data.xml'
[AMXAdminTask] 28 May 2021 09:58:16  INFO - TIBCO-AMX-CLI-000962: Getting entrprise information before executing action 'updateJDBCDriver'
[AMXAdminTask] 28 May 2021 09:58:16  INFO - ---------------------------------------------------------------------------------
[AMXAdminTask] 28 May 2021 09:58:19  INFO - Admin Info:
[AMXAdminTask] 28 May 2021 09:58:19  INFO -     Time for which Admin is up: 0 days, 0 hours, 3 minutes, 33 seconds
[AMXAdminTask] 28 May 2021 09:58:19  INFO -     Time taken for Admin to start up: 01 minutes, 04 seconds
[AMXAdminTask] 28 May 2021 09:58:19  INFO -     Time taken to ping the Database: 0.022 seconds
[AMXAdminTask] 28 May 2021 09:58:19  INFO -     Time taken to ping Qin Notification Server: 17ms
[AMXAdminTask] 28 May 2021 09:58:19  INFO -     Admin suspend state: Unsuspended
[AMXAdminTask] 28 May 2021 09:58:19  INFO -     Admin readOnly state: Write
[AMXAdminTask] 28 May 2021 09:58:19  INFO -     Admin suspend/readOnly description:
[AMXAdminTask] 28 May 2021 09:58:19  INFO -     Is this Admin Qin Notification Group leader: N/A
[AMXAdminTask] 28 May 2021 09:58:19  INFO -     Number of Notifications processed by Admin: 1857
[AMXAdminTask] 28 May 2021 09:58:19  INFO -     Number of Runtime Artifacts in Admin Staging Area: 5 (RDA files: 1, ZIP files: 4)
[AMXAdminTask] 28 May 2021 09:58:19  INFO -     Admin Entities:
[AMXAdminTask] 28 May 2021 09:58:19  INFO -                Entities          Total    Last Modified/Deployed On
[AMXAdminTask] 28 May 2021 09:58:19  INFO -                  Environments        2     11 Feb 2021 16:05:43,291
[AMXAdminTask] 28 May 2021 09:58:19  INFO -                         Hosts        1     11 Feb 2021 16:03:48,834
[AMXAdminTask] 28 May 2021 09:58:19  INFO -                         Nodes        2     27 May 2021 14:52:42,165
[AMXAdminTask] 28 May 2021 09:58:19  INFO -                  Applications        8     27 May 2021 14:48:53,293
[AMXAdminTask] 28 May 2021 09:58:19  INFO -            Resource Templates       39     27 May 2021 14:47:31,610
[AMXAdminTask] 28 May 2021 09:58:19  INFO -            Resource Instances       73                          N/A
[AMXAdminTask] 28 May 2021 09:58:19  INFO -         Application Templates        0
[AMXAdminTask] 28 May 2021 09:58:19  INFO -
[AMXAdminTask] 28 May 2021 09:58:19  INFO - Enterprise [AMXBPM] summary :
[AMXAdminTask] 28 May 2021 09:58:19  INFO -     Number of Nodes: 2 [2 Running, 0 Not Running]
[AMXAdminTask] 28 May 2021 09:58:19  INFO -     Number of Hosts: 1 [1 Running, 0 Not Running]
[AMXAdminTask] 28 May 2021 09:58:19  INFO -     Number of Applications: 8 [8 Running, 0 Not Running, 0 Not Deployed]
[AMXAdminTask] 28 May 2021 09:58:19  INFO -     Number of ActiveMatrix Environments: 2
[AMXAdminTask] 28 May 2021 09:58:19  INFO -     Most amount of applications deployed on Node [SystemNode] ( managed by [ SystemHost]): 4
[AMXAdminTask] 28 May 2021 09:58:19  INFO -     Most amount of applications deployed in Environment [BPMEnvironment]: 4
[AMXAdminTask] 28 May 2021 09:58:19  INFO -     Most amount of Nodes managed by Host [SystemHost]: 2
[AMXAdminTask] 28 May 2021 09:58:19  INFO -     Most amount of Host running on Machine [192.168.0.78]: 1
[AMXAdminTask] 28 May 2021 09:58:19  INFO -     Most amount of Node running on Machine [192.168.0.78]: 2
[AMXAdminTask] 28 May 2021 09:58:19  INFO -     Most amount of applications deployed on Machines [192.168.0.78]: 8
[AMXAdminTask] 28 May 2021 09:58:19  INFO -     CPU and Memory are not collected.
[AMXAdminTask] 28 May 2021 09:58:19  INFO -
[AMXAdminTask] 28 May 2021 09:58:19  INFO - ---------------------------------------------------------------------------------
[AMXAdminTask] 28 May 2021 09:58:19  INFO - Updating JDBC Driver...
[AMXAdminTask] 28 May 2021 09:58:20  INFO - Installing Node 'BPMNode' in background
[AMXAdminTask] 28 May 2021 09:58:20  INFO - Installing Node 'SystemNode' in background
[AMXAdminTask] 28 May 2021 09:58:20  INFO - JDBC Driver 'com.tibco.tpcl.gen.oracle.jdbc.feature' has been updated from '12.1.100.001' to '19.3.0.001' successfully.
[AMXAdminTask] 28 May 2021 09:58:20  INFO - Action finished at 5/28/21 9:58 AM in 4.507 seconds
BUILD SUCCESSFUL

Total time: 7 seconds
=====================================================================================================================


Verification:

Please verify the following steps to make sure the JDBC driver has been upgraded successfully:

1. CLI output indicates BUILD SUCCESSFUL.

2. ALL the nodes would be restarted successfully after this CLI command. It will remove the old jdbc feature and install the new jdbc feature. You may check each nodes with the result from the following two ways:

Administrator GUI->Infrastructure->Node->Configuration->feature->make sure there is only one JDBC driver feature which points to the new version, and status is Installed.

Or you may run command below to check result:

./tibcohost describeEnabledProductFeatures -nodeName <nodeName>

Make sure there is only the new version JDBC feature listed in the output.

Note: For large scale environment which contains thousands of nodes, do string search or pattern matching for the following log entries in the log file of each host instances:

==============
Example: The SystemHost instance manages the SystemNode and a BPMNode:

27 May 2021 15:22:57,956 [Job_Executor13] [INFO ] com.tibco.amx.hpa.Host - TIBCO-AMX-HPA-000145: [root:Node-Change features:21101]: TIBCO ActiveMatrix host SystemHost installed com.tibco.tpcl.gen.oracle.jdbc.feature:19.3.0.001

27 May 2021 15:22:58,179 [Job_Executor14] [DEBUG] com.tibco.amx.hpa.Host - [root:Node-Change features:21101]: TIBCO ActiveMatrix host SystemHost enabling product feature com.tibco.tpcl.gen.oracle.jdbc.feature:19.3.0.001 on node SystemNode (refresh mode)

27 May 2021 15:22:58,179 [Job_Executor14] [DEBUG] com.tibco.amx.hpa.Host - [root:Node-Change features:21101]: TIBCO ActiveMatrix host SystemHost disabling product feature com.tibco.tpcl.gen.oracle.jdbc.feature:11.2.100.001 on node SystemNode (refresh mode)

27 May 2021 15:36:20,736 [Job_Executor14] [INFO ] com.tibco.amx.hpa.Host - TIBCO-AMX-HPA-000169: [root:Node-Change features:21101]: TIBCO ActiveMatrix host SystemHost enabled product feature com.tibco.tpcl.gen.oracle.jdbc.feature:19.3.0.001 on node SystemNode (com.tibco.tpcl.gen.oracle.jdbc.feature:19.3.0.001 mode)

27 May 2021 15:36:20,736 [Job_Executor14] [INFO ] com.tibco.amx.hpa.Host - TIBCO-AMX-HPA-000165: [root:Node-Change features:21101]: TIBCO ActiveMatrix host SystemHost disabled product feature com.tibco.tpcl.gen.oracle.jdbc.feature:11.2.100.001 on node SystemNode (refresh mode)

27 May 2021 15:38:39,366 [Job_Executor15] [DEBUG] com.tibco.amx.hpa.Host - [root:Node-Change features:21101]: TIBCO ActiveMatrix host SystemHost uninstalling product feature com.tibco.tpcl.gen.oracle.jdbc.feature:11.2.100.001

27 May 2021 15:38:39,376 [Job_Executor15] [INFO ] com.tibco.amx.hpa.Host - TIBCO-AMX-HPA-000229: [root:Node-Change features:21101]: TIBCO ActiveMatrix host SystemHost uninstalled product feature com.tibco.tpcl.gen.oracle.jdbc.feature:11.2.100.001
==============

3. Make sure all applications are Running and In Sync or at the same status before upgrade.

If verification fails, please contact TIBCO AMX platform support for further help.

Note: For some BPM 4.3 environments with AMX 3.4.0 pas platform, when executing the 'updateJDBCDriver' CLI script to upgrade the JDBC driver to Oracle 19.3, the stopping of SystemNode may hang there and therefore the SystemNode and other runtime nodes cannot get the driver upgraded. Please refer to the following KB for more details and solutions.

  KB 000045567: SystemNode restart hungs upon 'updateJDBCDriver' CLI execution (AMX-18316)

Steps below are for upgrading a third-party JDBC driver used in AMX Administrator enterprise using admin CLI.

TAP-16109/TAP-16377

TAP-16025/TAP-16186

TAP-16396

KB 000045567: SystemNode restart hungs upon 'updateJDBCDriver' CLI execution (AMX-18316)