Skip to content

MxD-js/addon-dev-script

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

28 Commits
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Add-On Development Script for WebCTRL

WebCTRL is a trademark of Automated Logic Corporation. Any other trademarks mentioned herein are the property of their respective owners.

This script may be used to automate certain aspects of WebCTRL add-on development on Windows operating systems. WebCTRL SDK dependencies are automatically collected from a local WebCTRL installation. Commands are provided for add-on compilation and packaging. Keystore management is automatic, so you don't have to worry about manually signing your .addon file.

Setup Instructions

  1. Install WebCTRL7.0 or later.

  2. Install JDK 16 or later.

  3. Install Visual Studio Code and the following extensions:

  4. Clone this repository to your local machine.

    • Edit LICENSE to match your specifications. This license file is copied to the new projects created by the script.
  5. Launch Utility.bat

    • You will be prompted to enter the location of the JDK bin.

    • If the script cannot locate a WebCTRL installation folder under %SystemDrive%, you will be prompted to specify an installation path.

    • You will be prompted to enter a keystore password and a few other parameters for creating a new keystore. Refer to Keystore Management for more details.

    • You will be prompted to enter a project folder for initialization.

      • It is recommended to use the naming convention lowercase-with-hyphens in accordance with common GitHub repository names.

      • Newly created project folders are placed alongside your local clone of this repository, but they can be moved anywhere after creation.

      • You may also enter the absolute path of a project folder. Any name which contains a colon is treated as an absolute path.

      • You can initialize preexisting project folders. For example, you could clone a remote repository to your local machine, and then initialize it with the script to generate missing files.

  6. Review documentation at ALCshare.

Command Reference

The following commands may be used to automate add-on compilation and packaging.

Command Description
help Displays a help message listing these commands with brief descriptions.
cls Clears the terminal.
init [--new] Reinitializes the current project if no parameters are given. Prompts you to initialize a new project if the --new flag is given.
build [args] Compiles source code. The last modified timestamp for each .java file is recorded to avoid unnecessary recompilation. Arguments are passed to the javac compilation command. Arguments are stored for future invokation, so you only have to type them once. The default compilation flag is --release 11.
pack Packages all relevant files into a newly created .addon archive.
make [args] Calls build and pack. Arguments are passed to build.
sign Signs the .addon archive.
forge [args] Calls build, pack, and sign. Arguments are passed to build.
deploy Copies the .addon archive and authenticator certificate to the bound WebCTRL installation.
exec [args] Calls build, pack, sign, and deploy. Arguments are passed to build.
git [args] All Git commands are executed literally.

Extensions

Custom project-specific commands can be created to extend the functionality of this script. For examples, refer to https://github.com/automatic-controls/centralizer-for-webctrl/tree/main/ext. Any batch file placed in ./ext is treated as an extension. The name of each batch file is used as the command name (case-insensitive). It is expected that each extension prints help information to the terminal when passed the --help parameter. Help information is appended to the help menu shown in the terminal. The default commands shown in the previous section can be overridden by extensions. For instance, https://github.com/automatic-controls/centralizer-for-webctrl/blob/main/ext/pack.bat overrides the default pack command.

Generated Project Structure

File Description
./.vscode/settings.json Tells Visual Studio Code where dependencies are located.
./.gitignore Tells Git what to ignore when committing files.
./Utility.bat Script to automate builds.
./README.md User-friendly information about the project.
./DEPENDENCIES Record all compile-time dependencies.
./LICENSE License file for the project.
./config.txt Specifies additional compilation flags.
./src Contains all source code.
./classes Contains and indexes compiled .class files.
./classes/index.txt Records last modified timestamps for source code to avoid unnecessary recompilation.
./root Root directory packaged into the .addon archive.
./root/info.xml Contains basic information.
./root/webapp Static resources (e.g, files and folders including html, css, js, jsp, and png).
./root/webapp/WEB-INF/web.xml Deployment descriptor (e.g, servlet, filter, and listener mappings).
./root/webapp/WEB-INF/classes Contains compiled .class files.
./root/webapp/WEB-INF/lib Contains dependencies not provided by WebCTRL at runtime.
./lib Contains project-specific dependencies provided by WebCTRL at runtime.
./ext Contains extensions that provide additional commands.

Manual Deployment

  1. Place the authentication certificate (look for a file with the .cer extension in your local clone of this repository) into the ./addons directory of the target WebCTRL installation.

  2. Use the WebCTRL interface to install the .addon archive of your project.

Dependency Collection

Runtime dependencies are located in ./lib relative to your local clone of this repository. These dependencies do not need to be packaged into your .addon file because they are provided by WebCTRL at runtime. Other external dependencies should be placed in ./root/webapp/WEB-INF/lib relative to your project folder. The following runtime dependencies are collected from your WebCTRL installation:

Dependency Location Relative to WebCTRL8.0
tomcat-embed-core ./webserver/lib
addonsupport-api-addon ./modules/addonsupport
alarmmanager-api-addon ./modules/alarmmanager
bacnet-api-addon ./bin/lib
directaccess-api-addon ./modules/directaccess
webaccess-api-addon ./modules/webaccess
xdatabase-api-addon ./modules/xdatabase

If you change the WebCTRL installation by manually editing ./config.txt (relative to your local clone of this repository), then you should delete ./lib to force dependency recollection. Feel free to browse your WebCTRL installation for dependencies that give access to other internal APIs if these defaults are insufficient. If you would like to add a WebCTRL API to one project folder without affecting any other projects, the .jar file should be placed in ./lib relative to your project folder.

Keystore Management

The generated 2048-bit RSA key-pair is valid for 100 years, uses SHA512 as the signature algorithm, and is stored under the alias addon_dev in ./keystore.jks. You can also use a preexisting key-pair under the same alias. An obfuscation of the keystore password is stored in ./config.txt. The obfuscation algorithm reverses the ordering and XORs each character code with 4. THE KEYSTORE PASSWORD IS NOT ENCRYPTED; IT IS ONLY OBFUSCATED.

Remark: WebCTRL uses the same obfuscation algorithm in a few places I've found. Anyone can inspect the JavaScript in a WebCTRL login page to discover that operator passwords are obfuscated in this way before being sent to the server (of course, this is not a substitute for encrypting traffic with HTTPS). The webserver.keystorepassword entry from ./resources/properties/settings.properties (relative to WebCTRL) is also obfuscated using the same algorithm.

Compatibility Notes

WebCTRL may complain if your add-on name includes spaces. You should use the build flag --release 11 for WebCTRL8.0 and --release 8 for WebCTRL7.0. These flags indicate the JVM version to use for compilation. You can determine the appropriate JVM version by invoking "[WebCTRL]\bin\java\jre\bin\java.exe" -version from command prompt (after replacing [WebCTRL] with the path to your WebCTRL installation directory).

About

Script to manage development of WebCTRL add-ons.

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • Batchfile 100.0%