Installation Manual

Introduction

HaloCAD KPro is a Java-based component that is a proxy for HaloCORE for DMS Add-On and communicates with the HaloENGINE and HaloENGINE Service. 

About this Manual

This manual walks you through installing and configuring HaloCAD KPro and includes many references to other sources of related information. 

System Requirements

The following table lists the requirements for HaloCAD KPro.

Requirements

Installing the HaloCAD KPro Application

Setting up HaloCAD KPro involves installing the HaloCAD KPro application (which installs Tomcat, Java, and deploys the KPro war file) and adjusting the war properties via the command line.

Note:

1. If HaloCAD KPro is running on the same computer as the HaloENGINE, the HaloCAD KPro installer will use Tomcat and Java, which have already been set up by the HaloENGINE Server installer.

2. If HaloCAD KPro is installed on a different machine, Java and Tomcat will be installed by the HaloCAD KPro installer.

3. Tomcat must be restarted following any configuration or Tomcat certificate configuration.

Limitation

In previous versions, the KPro proxy supported the following scenarios.

1. Case 1: Operating HaloCAD KPro and HaloENGINE on the same machine.

2. Case 2: Running HaloCAD KPro and HaloENGINE on different machines

As of version 6.6, the KPro proxy only supports Case 1. However, the configuration tool will show Case 2 options as well. Case 2 will only be functionally available based on user demand.

HaloCAD KPro installed in different setups

Install the HaloCAD KPro using the GUI-based setup program provided in the installation package.

1. To begin the interactive installation, double-click the installer HaloCAD_KPro_Setup.exe file. Depending on your Windows security settings, you may get a warning such as "Do you want to allow the following program to make changes to this computer?". If you get this security warning, click the Yes button to continue the installation.

2. When the installer starts, you will see the startup dialog followed by the welcome dialog:

   

   Startup Dialog

   

   Welcome dialog

3. Click Next to continue the installation. The end-user license agreement dialog will appear:

   

   End-User License Agreement dialog

4. Read the End-User License Agreement. If you agree, select I accept the terms in the License Agreement and click Next. 

5. The Tomcat memory pool size configuration dialog will appear:

   

   Tomcat pool size configuration dialog

6. If you want to change the default values of the Initial Memory Pool and Total Memory Pool, enter the amount of memory you want to allocate. Note: Make sure that the Total Memory Pool should not exceed the available RAM on the System. Click Next. 

7. The destination folder selection dialog will appear:

   

   Destination folder dialog

8. By default, application files are stored in the program files directory (C:\Program Files\Secude\). If you would like to choose an alternate location, click the Browse button and select your location preference. When you are finished, click Next.

9. The installation begins and progress is shown in the dialog.

   

   Installing dialog

10. When the installation is completed, you will see a message confirming that the HaloCAD KPro has been successfully installed.

    

    Completing the HaloCAD KPro dialog

11. Click Close to close the installation wizard.  

What to do Next?

Configure HaloCAD KPro using the HaloENGINE Tool.

Silent Installation

Besides graphical mode, the HaloENGINE can be installed in silent mode, which does not require user involvement or display a user interface. Open a command prompt, navigate to the installer's folder, and enter HaloCAD_KPro_Setup.exe -help. Enter the required input and press Enter. The installation will be completed successfully.

Configuring the KPro Properties

Case 1: HaloCAD KPro and HaloENGINE on the Same Machine

Prerequisites

1. At this point, the HaloENGINE must be able to fetch MPIP labels.

2. The Server Keystore and a Client Keystore for KPro Proxy must be available in the HaloENGINE. For illustration purposes, the Client Keystore (for sample, ClientKey.jks) is used for communication between HaloCAD KPro and HaloENGINE.

3. For HTTPS Content Server only:

   1. Please note that HaloCAD KPro defaults to HTTPS = False. 

   2. To use HTTPS, you need to get the Content Server instance certificate and then add it to the Keystore (HaloENGINE Tomcat) using the HaloENGINE tool. 

Follow the steps to set up HaloCAD KPro: 

Step 1: Set the Environment Variable. 

1. Under System Variables, set the variable "JAVA_HOME" to the Secude JRE directory. For example, JAVA_HOME=C:\Program Files\Secude\secude-jre.

2. Under System Variables, edit the “Path” variable to add "JAVA_HOME" to it. For example, Path=%PATH%;%JAVA_HOME%\bin.

Step 2: Generate KPro configuration properties.

1. Extract the zipped folder.

2. To run the HaloENGINE tools:

   1. Copy halo-engine-tools<version>.zip file to the desktop and extract it.

   2. Open Command Prompt with administrator rights and change directory to halo-engine-tools-<version>\bin.

   3. Run the options one by one. For illustration purposes, a sample is given below.

Test the configuration

1. Restart the HaloENGINE Tomcat service. 

2. Enter the web service endpoint in a browser: http://<IPaddress or FQDN>:<port>/halocad-kpro/new-service?wsdl. For example, http://10.41.14.69:8383/halocad-kpro/new-service?wsdl

3. The endpoint must be resolved with no error.

How to Update?

This section describes how to update HaloCAD KPro from previous versions to the latest version. Please note that HaloCAD KPro 6.7 is only compatible with HaloENGINE 6.7.

Update from HALOCORE KPro to HaloCAD KPro

This section is for users who are using previous versions of HALOCORE KPro (for example, <6.6) and want to update to HaloCAD KPro.

Step 1: Backup files from earlier version of HALOCORE KPro.

1. Stop the Tomcat Service

2. Take a backup of the configuration and the Tomcat folders.

3. Uninstall the HALOCORE KPro version using the installer.

Step 2: Create files that are compatible with the new HaloENGINE.

1. If the Halo Core Server is installed, please migrate with the appropriate batch file for HaloENGINE compatibility and upgrade to HaloENGINE 6.7.x.x.

2. At this point, make sure both HaloENGINE Service and HaloENGINE are installed.

Step 3: Run the batch file.

1. Create a system variable JAVA_HOME and copy the HaloENGINE_HOME value. For example, JAVA_HOME = D:\test\SECUDE\secude-jre

2. Open a command prompt and navigate to the folder where makeNewKProConfig.bat is available in the product package.

3. Execute the batch file as shown below:

   CODE

   makeNewKProConfig.bat <path to the old config file> <a backup folder name>
   For example:
   makeNewKProConfig.bat D:\Office\Test_zip_files\config  D:\Office\Test_zip_files\config_backup

4. If the script (.bat) is executed without issues, the backup folder will be automatically deleted. Ensure that the backup folder is free of any other files as it will be deleted.

5. The folder that contains the older "config" will be replaced with the new 6.7 compatible "config".

Step 4: Install HaloCAD KPro version

1. Install HaloCAD KPro using the installer.

2. Stop the Tomcat service.

3. Create a config folder in the HaloCAD KPro installation folder.

4. Copy the files from the D:\Office\Test_zip_files\config to the HaloCAD KPro\config folder.

5. Execute halo-engine-tools.bat to generate the log folder.

6. Start configuring using the tool, as described in Case 1 (1 to 5). Note: To use the previous versions (<6.6) of the server certificate HalocoreServer.cer, simply rename it to HaloENGINE.cer.

Update of HaloCAD KPro from Version 6.6.x.x to 6.7.x.x

This section is for those who have already installed HaloCAD KPro 6.6 and want to update to the latest 6.7 version. It is recommended to make a backup of the configuration properties file.

Navigate to the directory in which the HaloCAD KPro installation package is located and double-click the HaloCAD_KPro_Setup.exe.

1. The installation begins with the following dialog:

   

   Update screen #1

2. If you choose to remove the component, choose Uninstall; otherwise, select Update and proceed to Step 4. To remove, follow the steps outlined below.

3. Uninstall: If you wish to uninstall the KPro component, select Uninstall and click Next.

   1. To the question, "You are about to uninstall the HaloCAD Kpro. Are you sure you want to uninstall the application?", answer Yes.

   2. To the question, "Do you want to keep the HaloCAD Kpro configuration files?", answer Yes. It is only possible to keep the Tomcat folder, and the only way to obtain the configuration files is to manually create a backup. If you select No, no files are taken as a back up.

   3. After completing the uninstallation process, click Close to close the wizard.

4. Update: The update will begin, and once finished, you will see the completion dialog.

5. Click Close to close the update wizard.

6. Use the HaloENGINE tool to adjust the configuration. Note: To use the previous versions (<6.6) of the server certificate HalocoreServer.cer, simply rename it to HaloENGINE.cer.

Permission

1. After completing the configuration, there will be kpro_config.properties file created at C:\Program Files\Secude\HaloCAD KPro\config.

2. If you don't specify a location for the error log and local audit log, the directory defaults to C:\Program Files\Secude\HaloCAD KPro\logs\. You must ensure that these directories allow accessing them in your system. To do so, assign folder permissions to "ALL APPLICATION PACKAGES".

Auto Clearance of Session Files

HaloCAD KPro comprises two Schedulers to delete old files based on file expiration criteria. As a default behavior during a file upload/download, a folder is created with a unique session ID. When the session ends, a JSON file will be created in Tomcat's temp directory, which contains session details.

For example: [{"expiration":"yyyymmddhhmmss","sessionId":"ebabc39a-5c10-478b-b61c-9e292ce1fe9b"}]

1. Scheduler ECTR—Here, the actual expiry for a session is calculated from 3 hours after the session ID's end session function is triggered. Thus, the files are maintained in the same folder and remain valid for another 3 hours. However, the scheduler runs (sessiondetails.json) every 2 hours on session IDs, examines and deletes the files which had reached their expiration.

2. Scheduler KPro—Here, the actual expiry for a session is calculated 1 hour after the session ID's end session function is triggered. The scheduler runs (kprosessiondetails.json) every 3 hours on session IDs, examines and deletes the files which had reached their expiration.

Appendix

This section provides supplemental information.

Open-source Software

Third-party software/code is included or bundled with Secude's products according to its appropriate license. Secude conducts testing to make sure the third-party products are compatible with and perform as intended with Secude applications.

The third-party libraries and dependencies used by HaloCAD KPro are shown in the table below.

Open-source software

Uninstalling the HaloCAD KPro Component

Method #1 

When you no longer use the service, you may uninstall the application. Uninstalling removes all files and registry settings that were added to your computer during the initial installation.

Follow the below steps to uninstall:

1. Click Start menu > go to Control Panel > Programs > Programs and Features > Uninstall a Program > select HaloCAD KPro application from the list > right-click and select Uninstall option or double-click on the installer HaloCAD_KPro_Setup.exe. 

2. Depending on your Windows security settings, you may get a security warning as "Do you want to allow the following program to make changes to this computer?". If you get this security warning, click the Yes button to confirm that you want to uninstall the application.

3. The following confirmation message will appear:

   

   Uninstall message #1

4. Click Yes to confirm that you want to remove it from the computer. 

5. You will be prompted to save a backup of the configuration files.

   

   Uninstall message #2

6. Click Yes. It is only possible to keep the Tomcat folder, and the only way to obtain the configuration files is to manually create a backup. If you select No, no files are taken as a backup.

   

   Uninstall message #3

7. Click OK to close the message.