Add a field to a model
Add an optional tracking code to an existing record without editing generated Java or an old database changelog.
Use this procedure in an application whose model, schema.json and existing migrations already agree.
For a disposable example, start with jcm new field-desk and enter field-desk. The blank template has a Request
model. If you are changing another application, keep its existing fields and use its own entity and package names.
Add the fieldโ
Edit src/main/jcm/model/Request.yml and add trackingCode under fields. The resulting blank-template model is:
entity: Request
instance-name: title
fields:
title: {type: text, length: 200, required: true}
receivedOn: {type: date}
urgent: {type: boolean, default: false}
urgencyReason: {type: text, length: 1000, label: Why it is urgent}
trackingCode: {type: text, length: 80}
Leaving out required: true makes this field nullable. Existing records can therefore have no tracking code after
the migration. A new required text field is refused because existing rows have no value: add it nullable, backfill
through an application-specific reviewed migration, then make it required with changed: true. A generated
changelog does not invent the business value for those rows.
Model files belong under src/main/jcm/model/, not src/main/resources/jcm/. Do not edit the generated entity class.
The model reference lists supported field types and names.
Generate and inspect the migrationโ
From the application root, run:
jcm changelog
git diff -- src/main/jcm/model src/main/resources
git status --short
The command reports jcmChangelog wrote, creates the next numbered XML changelog and updates schema.json.
Inspect the new XML as well as the diff: an untracked file does not appear in an ordinary git diff.
Expect an added nullable TRACKING_CODE column with text length 80. The number and folder follow your project's
existing migrations; do not copy a filename from another app. Generating the file does not apply it to a running
database. Liquibase applies it when the application starts.
Run jcm changelog again without further edits. It should say the model and schema.json agree and write no new
migration. Do not use --baseline to hide a missing migration: that option records a schema without creating it.
Expose and verify the fieldโ
If people need to edit the tracking code, add trackingCode to the intended section in
src/main/resources/jcm/case-types/case.request.yml. Keep the existing sections and form rules. Review the data
role's field permissions too; the blank template's wildcard is not a reason to widen an existing application's role.
See Case screen and form rules and
Data roles.
jcm check
All four stages should pass. Add a persistence test that saves an invented tracking code, reloads the record and checks its value; also test a record with no tracking code. If you exposed it on screen, verify a permitted user's save/reload and a restricted user's refusal. A passing build alone does not prove the field's access policy.
Commit the model, new XML changelog, updated schema.json, affected configuration and tests together. Before an
upgrade, rehearse on a disposable copy of the prior schema using the intended database family and invented data;
confirm existing records remain and the new column is empty until populated. A clean-database test cannot establish
upgrade behavior for a populated database. Never edit a changelog that has already run.