Skip to main content

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 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.

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.

src/main/jcm/model/Permit.yml
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.

src/main/resources/jcm/case-types/case.permit.yml
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.

src/test/java/com/example/permitdesk/PermitCaseScreenUiTest.java
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.