Skip to main content

Configuration and Java extensions

JCM separates the description of an application from the framework that runs it. A workflow file names states, transitions and the roles allowed to make each move. The workflow component reads that description and performs the move. Application Java supplies behavior through the supported extension API when the configured actions cannot express the requirement.

This separation makes routine changes visible as application decisions. A reviewer can see which role gained a transition or which queue changed its filter without tracing a custom screen controller. It also gives the framework enough information to check references between files before accepting a configuration.

A file describes one item​

Runtime configuration lives under src/main/resources/jcm/, with one folder per kind and one file per item. The filename normally matches the item's code; the reference describes exceptions such as versioned workflows. Installed components contribute their own kinds and files. A folder with no installed reader is refused, so adding a folder does not install a feature.

Names are connections between those items. A queue names a case type; a workflow names states and transitions; a transition names roles. A misspelled name therefore changes more than presentation. JCM checks file layout, keys, value shapes and references, and reports refusals with the relevant file and, where meaningful, line. Unknown keys are refused rather than silently becoming settings that do nothing.

Use the layout reference for the accepted folders, filenames, overrides and startup checks. File placement is part of the contract, not a convention an application may freely replace.

YAML does not determine when a change takes effect​

Two files can use the same syntax and have different lifecycles. Decide how to deliver a change by what it changes:

ChangeHow it reaches the application
Supported runtime configurationThe studio can check and publish a candidate for the kinds it supports; some staged changes still need a restart
Entity model or a kind fixed at buildGenerate the required artifacts, rebuild and restart; a database shape change also needs its migration
Application Java or a dependencyCompile, test and deploy a new application build

A studio publication prepares and checks candidate configuration before making a new configuration generation current. This lets related reloadable registries use the files and states from one generation. A refused candidate does not become the current generation. That mechanism does not replace Java classes, run model generation or promise that every open browser view redraws immediately.

Some configuration is read only at startup, and some is fixed at build. The studio and the reference identify those boundaries. In particular, changing an entity model requires the build and migration workflow even when the model was edited as YAML. Read the studio overview before treating a successful publication as completion of a deployment.

Validation has several jobs​

Configuration checks establish that the application description is acceptable to the installed components. Build checks also check the model and the supported application API boundary. Application tests establish that the configured behavior does what its users need: for example, the intended user can make a transition and a user without that role is refused.

These checks complement each other. A valid workflow can still express the wrong business policy. A test that only signs in as an administrator does not establish the ordinary user's permissions. A successful build does not show that a release has reached a running environment or preserved its existing records.

Startup validation also happens in several phases. Some checks run before the web port opens; others run as components finish initialization and can still stop startup. An open port alone is therefore not evidence that the application is ready. Use the application's readiness checks and the testing guidance alongside the build result.

Java has an explicit application boundary​

When configured actions cannot express a requirement, use an extension point listed in the supported extension API. A workflow effect, for example, runs in the transition's transaction. Its purpose and failure behavior belong in application tests just as a configured transition does.

The exported manifest names exact supported types and members. A public Java class mentioned in framework implementation documentation is not automatically part of that API. Application records and data roles come from model and role files, and the generated shell remains shipped content. The build's API checks enforce those distinctions; copying a framework service into application code does not make that service supported.

The extension boundary is a compatibility and development constraint, not a sandbox for hostile code. Java extensions are application code and need review, dependency control and tests. Consult the boundary rules for the precise allowed dependencies and source rules.

Start by checking whether a configured action already expresses the requirement. If it does, keep the decision in configuration where the framework can validate it. If it does not, choose a supported extension point and test the added behavior. If neither exists, the missing capability needs a framework change rather than an application dependency on an internal implementation.