Skip to main content

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:

docs/examples/model-fields/Request-added.yml
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.