Add a workflow
In this tutorial you give the Permit case type from Your first case type a workflow: the states a permit moves through, the moves between them, and who may make each move. Then you look at its diagram in the studio. Allow about 20 minutes.
Start in the permit-desk folder as that tutorial left it.
Write the workflow
A workflow is one file. Its name carries its version, and binding names the case type it belongs to.
code: wf.permit
binding: case.permit
version: 1
initial: RECEIVED
states:
- {code: RECEIVED, name: Received}
- {code: IN_REVIEW, name: In review}
- {code: APPROVED, name: Approved, final: true}
- {code: REFUSED, name: Refused, final: true}
transitions:
- {code: start-review, name: Start review, from: [RECEIVED], to: IN_REVIEW, roles: [case-worker, system-full-access]}
- {code: approve, name: Approve, from: [IN_REVIEW], to: APPROVED, roles: [permit-lead, system-full-access]}
- {code: refuse, name: Refuse, from: [IN_REVIEW], to: REFUSED, roles: [permit-lead, system-full-access],
require-comment: true, confirm: "A refused permit cannot be reopened."}
Each move lists the roles that may make it. roles is the whole gate: a full-access role can make only the moves that
list it, so system-full-access is here for the admin user you will try this with. Take it out of the moves once your
application has real users.
require-comment makes the user say why, and confirm asks first. A move from a final state stops startup, as does
any typing mistake in a key. Workflows lists every key.
Add the role
Case workers start the review, and only a lead decides. permit-lead is a new role, in a file of its own.
code: permit-lead
name: Permit lead
description: Decides permits
includes: [case-worker]
Test who may move
The test signs in as a case worker and as a lead, and asks what each may do with a permit under review. It also walks a permit along the workflow.
package com.example.permitdesk;
import com.example.permitdesk.entity.Permit;
import com.jcm.testsupport.E2eUsers;
import com.jcm.testsupport.UserSeeder;
import com.jcm.workflow.TransitionDef;
import com.jcm.workflow.WorkflowService;
import io.jmix.core.UnconstrainedDataManager;
import io.jmix.core.security.SystemAuthenticator;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.context.ApplicationContext;
import org.springframework.test.context.ActiveProfiles;
import java.util.List;
import static org.junit.jupiter.api.Assertions.assertEquals;
@SpringBootTest
@ActiveProfiles("test")
public class PermitWorkflowTest {
static final String BINDING = "case.permit";
@Autowired
UnconstrainedDataManager dataManager;
@Autowired
WorkflowService workflow;
@Autowired
SystemAuthenticator authenticator;
@Autowired
ApplicationContext context;
Permit underReview() {
Permit permit = dataManager.create(Permit.class);
permit.setApplicant("Riverside Cafe");
Permit saved = dataManager.save(permit);
authenticator.runWithSystem(() -> workflow.transition(BINDING, saved, "start-review", null));
return saved;
}
List<String> movesFor(String username, Permit permit) {
return authenticator.withUser(username, () -> workflow.availableTransitions(BINDING, permit)).stream()
.map(TransitionDef::code).sorted().toList();
}
@Test
void aNewPermitStartsReceivedAndIsApproved() {
Permit permit = underReview();
assertEquals("IN_REVIEW", workflow.currentState(BINDING, permit).orElseThrow());
authenticator.runWithSystem(() -> workflow.transition(BINDING, permit, "approve", null));
assertEquals("APPROVED", workflow.currentState(BINDING, permit).orElseThrow());
}
@Test
void onlyALeadDecides() {
UserSeeder.seed(context,
UserSeeder.SeedUser.withRoles(E2eUsers.WORKER_A, E2eUsers.PASSWORD, "case-worker"),
UserSeeder.SeedUser.withRoles(E2eUsers.WORKER_B, E2eUsers.PASSWORD, "permit-lead"));
Permit permit = underReview();
assertEquals(List.of(), movesFor(E2eUsers.WORKER_A, permit));
assertEquals(List.of("approve", "refuse"), movesFor(E2eUsers.WORKER_B, permit));
}
}
jcm check
You should see passed.
Every stage should say passed.
See it run
jcm run
You should see http://localhost:8080.
A case that was saved before the workflow existed has no state, and it stays that way. A workflow starts when a record is created.
Open http://localhost:8080 and sign in as admin with the password admin. Under Permits, choose New permit,
enter an applicant and save. The case shows its state, Received, and a Start review button. Choose it. The case is
now In review, with Approve beside More. Open More and choose Refuse: a dialog shows the confirmation
text and asks for a comment before the case moves.
See the diagram
The studio draws every workflow from its file.
Open Configuration studio under Case administration in the menu, or go to http://localhost:8080/jcm/studio, and choose Workflows. The diagram shows the four states and the moves between them, drawn from your file. Further down the page, the tables list each state, each move and who may make it.
jcm run --stop
What you built
A permit now moves through four states, each move is limited to the roles you named, and a test proves it. To change a workflow that has records on it, add a new version rather than editing this file: records stay on the version they started on. Workflows explains how.
Next, Distribute work adds a shared queue and a personal work list to the permit desk.