Skip to main content

Getting started

JCM is a case-management framework: you describe case types, workflows, queues and roles in files, and it serves the screens, and checks every file when the application starts. It runs on Jmix, Vaadin and Spring Boot with Java 21.

This page takes you from nothing to a running application. The jcm command does its work in a tools image that holds the JDK, Gradle and a browser for tests. Once JCM is released, Docker will be the only thing to install.

Install​

You need Docker running Linux containers. Install lists what is supported.

JCM is not released yet, so neither the launcher nor the tools image is published. Until they are, you need access to the JCM repository, Git and bash, as well as Docker. Clone the repository, using the address that came with your access, and build the image once:

git clone https://example.invalid/jcm.git
cd jcm
bash cli/build-image.sh

The build compiles JCM inside Docker and takes about six minutes on a four-core machine with nothing cached; later builds reuse most of it. Give Docker at least 8 GB of memory and 10 GB of free disk: jcm check alone uses more than 4 GB.

Leave the checkout, since your applications do not belong inside it, and put the launcher on your path so that jcm is a command wherever you are. On macOS and Linux:

cd ..
export PATH="$PWD/jcm/cli:$PATH"

That lasts for this terminal. To keep it, add the same line to your shell's profile (~/.zshrc or ~/.bashrc), with the folder written out in full. On Windows, use jcm\cli\jcm.cmd from this folder.

Create an application​

jcm new my-app
cd my-app

You should see Created my-app.

The blank template gives you a working application with one case type, Request. There are others: Commands describes them.

Check it​

jcm check

You should see passed.

The command builds and starts the application on an in-memory database, runs its tests, and checks its use of the extension API and Jmix. All four stages should say passed. A refused configuration names the file and problem; fix it before running the application interactively. This check does not leave a running application or a database of sample cases. Add --browser when you also want the generated browser tests.

The first build downloads dependencies; later builds reuse them. A successful check proves the tested application at this revision, not every setting or a production deployment.

Open it in an IDE​

For an IDE or a direct ./gradlew build, install a JDK 21 on your machine. The Docker-based jcm commands include their own JDK and do not require a host installation.

In IntelliJ IDEA, open the generated application folder and select JDK 21 as the Project SDK. Under Settings → Build, Execution, Deployment → Build Tools → Gradle, use the project's Gradle wrapper and select JDK 21 for Gradle JVM. Reload the Gradle project after changing these settings.

Generated applications include gradle/gradle-daemon-jvm.properties with toolchainVersion=21, so the wrapper selects an installed JDK 21 even when the shell's JAVA_HOME points to Java 17. The build also selects Java 21 for compilation. Keep this file in version control; it contains no machine-specific paths. It does not download a missing JDK: install JDK 21 before importing the project.

Find the model and configuration folders​

These are separate folders under src/main/. The model folder is not inside resources/jcm/.

  • Data model — src/main/jcm/model/: Data-model YAML, such as Request.yml or Permit.yml. The build generates entity classes from it. jcm changelog generates database changes and records the model and migration state in schema.json here.
  • Runtime configuration — src/main/resources/jcm/: Configuration grouped by kind: case-types/, workflows/, queues/, roles/, calendars/ and other configured features.

Keep the model files, schema.json and generated database changelogs together in version control.

Run it​

jcm run

You should see http://localhost:8080.

The first build downloads Gradle, Node and the application's dependencies, about 1 GB, which takes several minutes. If you ran the check above, this run reuses those cached dependencies. The command prints the address once the application is ready, with PostgreSQL and a mail catcher running beside it. The mail catcher is at http://localhost:8025.

Sign in​

Open http://localhost:8080 and sign in as admin with the password admin. This is the template's local administrator, for your own machine only; production refuses it. You land on an empty Inbox that says no queues are set up for you, which is right for a new application. The menu on the left lists Requests, the template's case type.

When you have looked around, stop it. The database is kept for next time.

jcm run --stop

If something goes wrong, see Troubleshooting.

What is not available yet​

Hosted environments are not available. jcm publish, jcm promote and the commands around them exist, but there is no hosted service for them to reach yet. Hosted environments says what is planned.