Implementation Instructions

Depending on your current version, see the following sections for upgrade steps:

Full Install

For detailed installation instructions, see Participant Data Replication Monitor GUI Installer Guide or Guide to Participant Data Replication Monitor.

To install pdrMonitor v1.3.1 as a new implementation, select the following file from the Data Interchange Software:

File

Filename

Benefit

Participant Data Replication Monitor GUI Installer v1.3.1

Participant Data Replication Monitor GUI Installer for <Database> v1.3.1.zip

Requires the minimum data entry for localisation.

All implementation steps are automatic.

A manual installation is possible by exiting the installer and using a text editor to set the configuration properties

Upgrading from pdrMonitor v1.2.0 to v1.3.1

A successful upgrade involves understanding the changes between the versions. See Improvements.

 

The release of pdrMonitor v1.3.1 introduces new configurations in the XML configuration file (summarised below, see Page 1)

Configuration file updates

For help configuring the application properties, see Guide to Participant Data Replication Monitor.

Property

Detail

/Database/DbHandler

Refactoring of database handler classes to a new package structure au.com.aemo.Common.Database.*

/Authentication/IdentityProvider

Refactoring of authentication handler classes to a new package structure au.com.aemo.Common.Authentication.*

/CertificateStore/KeyStoreFile

The filename for the java keystore file

/CertificateStore/KeyStoreType

The keystore type. Defaults to PKCS12

/CertificateStore/StorePassword

The store password. Defaults to encryption key stored in pdr_key.properties

/CertificateStore/KeyPassword

The key password. Defaults to encryption key stored in pdr_key.properties

/CertificateStore/Protocol

The protocol. Defaults to TLS

Configuration file deletions

There are no properties made obsolete for v1.3.1.

GUI installation process

The GUI installation process is a simple way to upgrade. Alternatively, you can use the Implementation Instructions.

To upgrade an existing Participant Data Replication Monitor Software v1.2.0 to v1.3.1 installation:

  1. Validate the JRE installation is Open JDK 21 by running the following in a command prompt:

    java -version

    The response should be similar to:

    openjdk version "21" 2023-09-19
    OpenJDK Runtime Environment (build 21+35-2513)
    OpenJDK 64-Bit Server VM (build 21+35-2513, mixed mode, sharing)

  2. If a different Java version is detected, refer to the documentation to install the certified JRE version.
  3. Validate the .JAR file signature. From the command line prompt, run the following command:

    jarsigner -verify "Participant Data Replication Monitor GUI Installer v1.3.1.jar"

    For more information, see https://docs.oracle.com/en/java/javase/21/docs/specs/man/jarsigner.html

  4. Start the GUI installer using one of the following methods:

    • Double-click the JAR file in a Windows environment, if *.jar files are associated with a Java Runtime Environment (JRE).
    • Run the installer from the command line:

      • Open a command prompt.
      • Navigate to the folder where the installer is stored.
      • Run:

        • java -jar <insert installer name here>.jar

    • For headless environments, such as Linux, run the installer in a terminal session using the -console flag:

      • java -jar <insert installer name here>.jar -console

      Provides the same capabilities as the GUI installer but runs entirely in text mode.

  5. Install the pdrMonitor v1.3.1 to the current installation directory (for example, C:\Pdr\Monitor).
    The current installation is backed up to a folder alongside the current installation with a timestamp appended to the folder name.
  6. If running as a Windows service, ensure the Windows service name entered in the GUI installer matches the existing service name.
  7. Check the pdrMonitor.xml file changes and re-apply any customised configurations. See Configuration file updates and deletions.
  8. Run the pdrMonitor.bat or the Windows service and check the pdr.log in the Log folder for any errors.
  9. You must validate any existing batcher or loader connections using the upgraded secure API services in the Connections menu. Double click on each application, trust the certificate that is being used to secure the API services, press “Test Connection” and then Save.

Manual installation process

The generic steps are:

  1. Backup your v1.2.0 pdrMonitor installation folder.
  2. Remove the pdrMonitor v1.2.0 Windows service by running:

    pdrServiceUninstall.bat <insert_Windows_service_name_here>.

  3. Remove all existing jar files from the Lib folder
  4. Copy the following content from the pdrMonitor v1.3.1 installation media into your Lib folder
    • All jar files
    • New scripts:
      • pdrServiceInstall.bat
      • pdrCertificateManager.*
      • pdrMonitorSourceCycleKey.*
  5. Run the following command, after unzipping the command line prompt in the Lib folder:

    jarsigner -verify "AppPdrMonitor.jar"

  6. Update script pdrEnvironment.* and align CLASSPATH environment variable definition to match the v1.3.1 definition
  7. Copy the following content from the pdrMonitor v1.3.1 installation media into your Website folder
    • All folders under Website
  8. Adjust the value of the following configurations to
  9. If not already, install JRE 21 and update the JRE path variable in:
    • pdrEnvironment.bat
    • pdrServiceInstall.bat
    • WinRun4J.ini files
  10. Adjust configuration of the following elements in pdrMonitor.xml:
    • /Database/DbHandler

      au.com.nemmco.Util becomes au.com.aemo.Common.Database

    • /Authentication/IdentityProvider

      au.com.nemmco.Util becomes au.com.aemo.Common.Authentication

  11. Apply the database update scripts applicable to your database platform in the following order:
    • <database_platform>_alter_pdr.sql
    • populate_monitor_config_metadata_delta.sql
    • commit
  12. Install a new Windows service by running:

    pdrServiceInstall.bat <insert_Windows_service_name_here>.

  13. Check the database password is correctly encrypted before running the service by running the following command to avoid any password lockout:

    pdrConnectionTest.bat

  14. Run pdrMonitor.bat or the Windows service and check the pdr.log in the Log directory for any errors.
  15. Test upgrade by loging to pdrMonitor Web url as Admin. If login cannot be completed using previous password, try resetting password using pdrMonitorPasswordReset.bat. Restart pdrMonitor service.
  16. API keys defined within pdrMonitor source connections to pdrBatcher and pdrLoader need to match with respective keys defined within pdrBatcher and pdrLoader (pdr_key.properties). If these are changed during pdrBatcher/pdrLoader upgrades, please align the values and re-test pdrMonitor.

Upgrading from v1.3.0 to v1.3.1 (Linux only)

These fixes are for Linux environments only.

If you are on Windows installation for 1.3.0, you do not have to upgrade to 1.3.1.

The v1.3.1 release of pdrMonitor fixes the following issues:

  • The shebang line of supplied shell scripts which causes scripts to fail unless “.” is in the PATH environment variable.
  • Creating self-signed certificates using pdrCertificateManager.sh. This defect only surfaces if you attempt to use a self-signed certificate to secure monitor web services. To implement security best practice, AEMO recommends you should deploy a certificate signed by a trusted signing authority for SSL encryption of monitor web services.

For any existing v1.3.0 installations on Linux please complete the upgrade to v1.3.1 with the following steps:

  1. Stop pdrMonitor service.
  2. Backup Lib folder from the installation directory.
  3. Extract the contents of the CLI release Participant Data Replication Monitor v1.3.1.zip to a working folder.
  4. Update Lib/AppPdrMonitor.jar in the installation folder with equivalent file from the new release.
  5. Update Lib/*.sh in the installation folder with equivalent file from the new release except pdrEnvironment.sh.
  6. To ensure the updated shell scripts are executable, execute the following commands in a terminal session in the Lib folder:
    • dos2unix *.sh
    • chmod + *.sh
  7. Restart pdrMonitor service.
  8. Review application logs and confirm correct version installed and service is operating correctly.

The upgrade in the v1.3.1 GUI installer is delivered as an increment on a v1.2.0 base and should not be used to complete this upgrade from a v1.3.0 base.