Skip to main content

Write a letter

Give the permit desk an acknowledgement letter. Its template takes the applicant and case number from the permit; generation keeps the filled text and a PDF on that record. Allow about 20 minutes after the builds.

Start in the permit-desk folder from Distribute work. Use invented applicants throughout.

Add the template​

Write a template for the Permit binding:

src/main/resources/jcm/letters/lt.permit.acknowledgement.yml
code: lt.permit.acknowledgement
name: Application acknowledgement
binding: case.permit
subject: We received permit application ${case.number}
body: |
Dear ${record.applicant},

We received your permit application, reference ${case.number}.
We will contact you when the review is complete.

binding restricts the template to permits. ${record.applicant} reads the Permit field; ${case.number} reads the case number. These placeholders are checked at startup. A misspelled field stops the application instead of leaving a broken letter for someone to find later. The correspondence reference lists the supported placeholders and template options.

This is a plain text template rendered into a PDF. Its built-in font covers Western European text; use a separately verified document template when your letters need other scripts or more elaborate layouts.

Show letters on the case​

The Permit workspace currently names only the timeline. Add the letters control so the case offers Add → Letter and a place to reopen generated letters. Defining a letter template alone does not add that menu entry.

In src/main/resources/jcm/case-types/case.permit.yml, change

overview: [timeline]

to

overview: [timeline]
tabs: [letters]

If you have already added workspace tabs, add letters to that list instead of replacing it.

Test preview, generation and the kept copy​

Preview fills the template without storing a letter. Generate stores a letter and its PDF. This test checks both, then edits the applicant and verifies that the earlier letter still contains the original name.

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

import com.example.permitdesk.entity.Permit;
import com.jcm.correspondence.Letter;
import com.jcm.correspondence.LetterService;
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.io.IOException;
import java.io.UncheckedIOException;
import java.nio.charset.StandardCharsets;

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

@SpringBootTest
@ActiveProfiles("test")
public class PermitLetterTest {
static final String BINDING = "case.permit";
static final String TEMPLATE = "lt.permit.acknowledgement";

@Autowired UnconstrainedDataManager dataManager;
@Autowired SystemAuthenticator authenticator;
@Autowired LetterService letters;

@Test
void previewStoresNothingAndTheGeneratedLetterKeepsItsText() {
authenticator.withUser("admin", () -> {
Permit permit = dataManager.create(Permit.class);
permit.setApplicant("Willow Workshop");
Permit saved = dataManager.save(permit);

Letter preview = letters.preview(TEMPLATE, BINDING, saved);
assertTrue(preview.getBody().contains("Dear Willow Workshop,"));
assertTrue(letters.letters(BINDING, saved).isEmpty());

Letter written = letters.generate(TEMPLATE, BINDING, saved);
assertEquals(preview.getBody(), written.getBody());
assertEquals(1, letters.letters(BINDING, saved).size());
try (var pdf = letters.openPdf(written)) {
assertEquals("%PDF-", new String(pdf.readNBytes(5), StandardCharsets.US_ASCII));
} catch (IOException failure) {
throw new UncheckedIOException(failure);
}

saved.setApplicant("Willow Workshop Limited");
Permit updated = dataManager.save(saved);
assertTrue(letters.preview(TEMPLATE, BINDING, updated).getBody()
.contains("Dear Willow Workshop Limited,"));
Letter kept = letters.letters(BINDING, updated).stream()
.filter(letter -> letter.getId().equals(written.getId())).findFirst().orElseThrow();
assertEquals(written.getBody(), kept.getBody());
assertTrue(kept.getBody().contains("Dear Willow Workshop,"));
return null;
});
}
}
jcm check

You should see passed.

Every stage should pass. This test uses the local administrator to exercise letter behavior. It does not verify a restricted worker's access or the PDF's visual layout. Reading and previewing need read access to the record; generating needs update access, including row restrictions.

Write the letter on a permit​

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 and save a permit for Willow Workshop. Open Add, choose Letter, and select Application acknowledgement. Choose Preview and check the applicant and case number. Choose Generate. Find the letter on the permit's timeline and open its PDF. Check that the text fits and the case number matches the permit. Change and save the applicant name, then reopen the earlier letter: it still has the original name.

Generation keeps the letter on the case. It does not email, print or mail it. A generated PDF alone is not evidence that anyone received it. Keep delivery configuration and delivery evidence separate from this tutorial.

jcm run --stop

You now have a reusable letter template and a test for its stored output. The correspondence reference covers Word templates and more advanced letters.