Skip to main content

Distribute work

Give the permit desk two queues: permits waiting for someone to take them, and permits assigned to the person signed in. Put both in one Inbox tab, then use Get next to take a permit. Allow about 20 minutes after the builds.

Start in the permit-desk folder from Add a workflow. Its Permit model, workflow and case-worker role are prerequisites. The examples use only invented applicants.

List the unassigned permits​

A queue names a case type, filters its records and chooses the columns and order. Write this file:

src/main/resources/jcm/queues/q.permit.unassigned.yml
code: q.permit.unassigned
name: Unassigned permits
binding: case.permit
roles: [case-worker, system-full-access]
assigned: unassigned
states: [RECEIVED, IN_REVIEW]
columns: [case-number, applicant, receivedOn, workflow-state]
sort: receivedOn
next: {assign: true}

assigned: unassigned leaves out permits someone already holds. states leaves out approved and refused permits. sort puts earlier received dates first. Give the permits dates when creating them; this example does not define which of two permits with the same date comes first.

next: {assign: true} adds Get next. It claims an available record, assigns it to the current user and opens it. The user must be allowed to update the case. A queue's roles controls its audience; it does not grant permission to read or change Permit records. The role from the earlier tutorial supplies those permissions.

The local administrator is included so you can follow the manual steps. For your own application, name the worker roles that should see this queue. Queues and inbox describes the checks and claim lifetime.

List your own permits​

The second queue uses the same binding but asks for the current user's assignments.

src/main/resources/jcm/queues/q.permit.my-work.yml
code: q.permit.my-work
name: My permits
binding: case.permit
roles: [case-worker, system-full-access]
assigned: me
states: [RECEIVED, IN_REVIEW]
columns: [case-number, applicant, receivedOn, workflow-state]
sort: receivedOn

There is no Get next here: these records are already yours. Assignment and workflow state are separate. Taking a permit assigns it; Start review changes its state. Once approved or refused, it leaves both queues because of the state filter, even if its assignment remains.

Put the queues in the Inbox​

A queue file alone does not add an Inbox entry. Edit the empty tabs list left by the blank template:

In src/main/resources/jcm/jcm.yml, change

tabs: []

to

tabs:
- name: Permits
queues: [q.permit.my-work, q.permit.unassigned]

The order in this list is the order in the tab. The template's case-worker role already includes Inbox access. If you have changed this file since the first tutorial, add the Permits tab to your existing list instead of replacing other tabs.

Test taking work​

This test creates a permit, then proves that taking the first permit in queue order moves it from the unassigned queue to the current user's queue. The test runs as the template's local administrator without a browser sign-in.

src/test/java/com/example/permitdesk/PermitQueueTest.java
package com.example.permitdesk;

import com.example.permitdesk.entity.Permit;
import com.jcm.queues.QueueService;
import com.jcm.queues.next.QueueNext;
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.test.context.ActiveProfiles;

import java.time.LocalDate;

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertTrue;

@SpringBootTest
@ActiveProfiles("test")
public class PermitQueueTest {
@Autowired UnconstrainedDataManager dataManager;
@Autowired SystemAuthenticator authenticator;
@Autowired QueueService queues;
@Autowired QueueNext next;

@Test
void takingAPermitMovesItIntoMyWork() {
authenticator.withUser("admin", () -> {
Permit permit = dataManager.create(Permit.class);
permit.setApplicant("Willow Workshop");
permit.setReceivedOn(LocalDate.of(2000, 1, 1));
Permit saved = dataManager.save(permit);

assertTrue(queues.holds("q.permit.unassigned", saved));
assertFalse(queues.holds("q.permit.my-work", saved));
Permit first = (Permit) queues.items("q.permit.unassigned", 0, 1).getFirst();
Permit taken = (Permit) next.takeNext("q.permit.unassigned").orElseThrow();
assertEquals(first.getId(), taken.getId());
assertFalse(queues.holds("q.permit.unassigned", taken));
assertTrue(queues.holds("q.permit.my-work", taken));
return null;
});
}
}
jcm check

You should see passed.

This proves the queue and assignment behavior for one user. It does not test two people pressing Get next at once, or prove that a worker with restricted permissions has the intended access.

Take a permit in the Inbox​

jcm run

You should see http://localhost:8080.

Open http://localhost:8080 and sign in as the local administrator described in the application's README. Under Permits, create a permit for Willow Workshop with a received date and save. Return to Inbox, open the Permits tab and select Unassigned permits. Find the new permit. Press Get next: a permit opens, chosen by received date rather than by the row you selected. Return to the Inbox. That permit has left Unassigned permits and appears in My permits. Open it and choose Start review; it remains in My permits. Approve it and return to the Inbox; it no longer appears in either queue.

If older permits are already waiting, Get next can take one of those first. If nothing is free for you to take, the button says so and creates no assignment. A permit saved before you added the workflow has no workflow state and does not match these queues; create a new one.

jcm run --stop

You now have a shared pool of work and a personal list. Both come from queue files; the Inbox layout comes from jcm.yml. The queue reference also covers filters, boards and work buttons.

For a separate prepared-sample exercise showing how the active job affects the menu and Inbox access, continue with Work as a job role.