Your first case type
In this tutorial you build a small permit desk: a case type called Permit, with its data, its case screen and who may work on it. You will not write any view code. Allow about 30 minutes, most of it the first build.
You need jcm working and Docker running. Getting started covers both.
Create the application
Make a new application from the blank template and move into it.
jcm new permit-desk
cd permit-desk
You should see Created permit-desk.
The folder is a new Git repository. The template gives you a working application with one case type, Request, which
you can leave in place while you add your own.
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 asRequest.ymlorPermit.yml. The build generates entity classes from it.jcm changeloggenerates database changes and records the model and migration state inschema.jsonhere. - 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.
A case type needs three things in those folders: a model file for its data, a case-type file for its screen, and a
role that may work on it. Runtime configuration files use the item's code as their filename. The next step writes
the model under src/main/jcm/model/; the case-type and role files later go under src/main/resources/jcm/.
Describe the data
A model file describes one record. The build writes the entity class from it, so you do not write that Java yourself.
entity: Permit
instance-name: applicant
fields:
applicant: {type: text, length: 200, required: true}
site: {type: text, length: 200}
receivedOn: {type: date}
fee: {type: boolean, default: false, label: Fee paid}
instance-name is the field used wherever a record is named on screen. Every key is in
Data model and migrations.
Write the database change
A new model needs a table, so the next step writes a Liquibase changelog from the model file.
jcm changelog
You should see jcmChangelog wrote.
The first build downloads Gradle and the application's dependencies, which takes several minutes. Later builds reuse
them. The command wrote a new file under src/main/resources/ and recorded it in src/main/jcm/model/schema.json. Keep
them with the model file: jcm check fails while the three disagree.
Add the case type
The case-type file binds the entity to JCM. It gives each case a number and lays out the form.
code: case.permit
entity: Permit
label: Permit
number-format: "PRM-{year}-{seq}"
header:
title: "${record.applicant}"
fields: [receivedOn]
form:
- section: Application
fields:
- applicant
- site
- receivedOn: {default: today}
- fee
workspace:
overview: [timeline]
That is the whole screen: JCM serves the case screen, the list and the menu item from this file. Case types and Case screen and form rules list the rest.
Say who may work on it
The template's case-worker role can work on Request cases. Give it Permit too.
In src/main/resources/jcm/roles/case-worker.yml, change
Request: {actions: [all], modify: "*"}
to
Request: {actions: [all], modify: "*"}
Permit: {actions: [all], modify: "*"}
Whether a user sees a case type's screen and menu item follows from the entity's read permission, so this one line is all the role needs. See Data roles.
Test it
This test opens the case screen with no browser, fills in the form and saves. It proves the file you wrote gives a numbered case at the address you expect.
package com.example.permitdesk;
import com.example.permitdesk.entity.Permit;
import com.jcm.cases.CaseRecord;
import com.jcm.cases.CaseService;
import com.jcm.screen.view.CaseScreenView;
import com.vaadin.flow.component.HasValue;
import com.vaadin.flow.router.RouteParameters;
import io.jmix.flowui.ViewNavigators;
import io.jmix.flowui.testassist.FlowuiTestAssistConfiguration;
import io.jmix.flowui.testassist.UiTest;
import io.jmix.flowui.testassist.UiTestUtils;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.context.ActiveProfiles;
import java.util.Map;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertTrue;
@UiTest
@SpringBootTest(classes = {PermitdeskApplication.class, FlowuiTestAssistConfiguration.class})
@ActiveProfiles("test")
public class PermitCaseScreenUiTest {
@Autowired
ViewNavigators viewNavigators;
@Autowired
CaseService caseService;
@Test
@SuppressWarnings("unchecked")
void aNewPermitSavedOnItsScreenIsNumbered() {
viewNavigators.view(UiTestUtils.getCurrentView(), CaseScreenView.class)
.withRouteParameters(new RouteParameters(Map.of("type", "case-permit", "id", CaseScreenView.NEW)))
.navigate();
CaseScreenView view = UiTestUtils.getCurrentView();
HasValue<?, Object> applicant = (HasValue<?, Object>) view.getForm().field("applicant").orElseThrow();
applicant.setValue("Riverside Cafe");
view.save();
Permit saved = (Permit) view.getRecord();
CaseRecord record = caseService.find("case.permit", saved).orElseThrow();
assertTrue(record.getCaseNumber().startsWith("PRM-"), record.getCaseNumber());
assertEquals("cases/case-permit/" + saved.getId(), view.getAddress());
}
}
jcm check starts the application on an in-memory database, which is where a mistake in a configuration file stops
it with the file and line, and then runs the tests and the build's checks.
jcm check
You should see passed.
Each stage prints one line, and every line should say passed. The command stops with an error if one does not.
Run it
jcm run builds the application and starts it with PostgreSQL and a mail catcher, each in a container.
jcm run
You should see http://localhost:8080.
The application answers once it is ready. This curl line is for macOS, Linux and Git Bash; in PowerShell or the
Command Prompt, open http://localhost:8080/login in a browser instead and look for the sign-in page.
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8080/login
You should see 200.
Add a case
Open http://localhost:8080 and sign in as admin with the password admin. This is the template's local
administrator; production refuses it. You land on an empty Inbox, as no queues are set up yet. Open Permits in the menu, choose New permit, enter an applicant and
choose Save. The case takes the next number, such as PRM-2026-000001, and its activity list records what happened.
Stop the application when you are done. Its database is kept for next time.
jcm run --stop
What you built
You added a case type from three files, with a database change written for you and a test that proves it. The case has no workflow yet, so it has no states to move through. Add a workflow is next.