Module Filesystem And Structure

Module Root Directory

A module’s entire filesystem is stored in subdirectories under a root directory named after the module. This is then placed in an appropriate config level (customer, site, etc.) under the top-level modules/ directory.

For example, a module named Foo, distributed customer-wide, would be located in the directory modules/customer/Foo/ under the Partner System installation root directory.

Module Data Directory

Working data written and read by the module should generally be stored in a subdirectory of data/ named after the module. For example, data/Foo.

Module Config Directory

Configuration for the module should be stored in the config/ hierarchy, under the appropriate config level, according to the scheme config/CONFIG_LEVEL/modules/MODULE_NAME/.

For example, config/customer/modules/Foo/

Required Files

Modules must have the following two files, under the module root directory, or they will not be loaded at all:

  • info/version.txt
  • info/depends.txt

info/version.txt

The file info/version.txt must have a version number in MAJOR.MINOR.RELEASE format, e.g. 4.14.2.

info/depends.txt

The file info/depends.txt can be blank, but must still be present. If this module depends on other modules, they should be listed, one per line, thusly:

Bar
Baz

And if this module depends on specific versions of the other module, they should include the version as well, as specifically as needed with the three-part version format. Let’s expand our example:

Bar:4.12
Baz:4.14.2

Info Files

Other than version.txt and depends.txt, these files are also found in the info/ directory:

  • build.txt - build information useful to developers and troubleshooting

System Files

The system/ subdirectory of the module root allows extension of many things controlled by the top-level system/ directory.

These include:

  • system/apps/ - app scripts, which should generally be prefixed with the module name, e.g. system/apps/Foo-BarApp
  • system/jars/ - Java libraries, in JAR format

Control Files

Module lifecycle events are handled via scripts in control/ directories. The subdirectory control/startup/, for example, contains scripts that should be run during module startup.

OS-specific files

OS-specific files should be stored under os/OS, e.g. os\windows\ contains Windows-specific files.

These include:

  • os/OS/lib/ - .dll and other library files
  • os/OS/jars/ - OS-specific Java libraries
  • os/OS/programs/ - executables files that launch programs in the OS
  • os/OS/applications/ - larger applications that are OS-specific
  • os/OS/tools/ - executables, generally for maintenance and not general use

Templates

Modules can use templates, generally in StringTemplate (.st) format. These are stored in the templates directory.

Event Scripts

The module event system allows modules to add event listeners by placing scripts in appropriate subdirectories of the module.

The path format is events/MODULE/EVENT where MODULE is the module emitting the event and EVENT is the name of the event.

For example, a script that should be run during Hub startup should go in events/Hub/startup, and a script that should be run during shutdown should go in events/Hub/shutdown.