Skip to main content

Layout and jcm.yml

Every JCM component is a Jmix add-on: a functional module plus a Spring Boot starter, published as JARs. A component depends only on JCM-owned interfaces. Paid Jmix add-ons appear only as separate optional adapters.

This reference describes both framework internals and application configuration. Application Java may use only the exact types and members in Supported extension API. A public implementation service, event, registry, view or control described here is not an exported extension unless that manifest lists it. Internal implementation examples explain existing framework/legacy behavior; do not copy them into checked application production sources. Tests may use test-support/internal APIs. Application records and data roles come from model/role files; shell Java remains exact shipped content: a file of any shipped shell template set, moved to the current set by jcmUpgradeShell (see the extension reference).

Every configuration item of an app is one file under src/main/resources/jcm/: one folder per kind, one file per item, and the file name is the item's code. jcm/queues/q.appeal.my-work.yml holds exactly the queue q.appeal.my-work, its keys at the top of the file with no wrapper list around them. Add-on jars ship their own items the same way (jcm/refdata/ref.jcm.rooms.yml in jcm-calendar). One loader in jcm-core (com.jcm.core.config) finds and reads every file, and checks the layout, before the web server starts; each component checks its own items' keys, values and references as it starts using them, some after the web server has opened its port (see What stops startup).

FolderHoldsFile nameComponent
case-types/case types (Case screen, below)<code>.ymljcm-core
refdata/reference lists, and additions to one (Reference data)<code>.yml; an addition any namejcm-refdata
workflows/one version of a workflow (Workflow)<code>.v<version>.ymljcm-workflow
queues/queues (Queues and inbox)<code>.ymljcm-queues
seed/demo data: users and records (Seed data)<code>.yml, its files in <code>/jcm-seed
tasks/task templates (Tasks)<code>.ymljcm-tasks
deadlines/deadline policies (Deadlines and SLA)<code>.ymljcm-deadlines
calendars/business calendars (Calendars and hours)<code>.ymljcm-deadlines
schedules/availability schedules (Resource availability)<code>.yml, the code starting sch.jcm-calendar
letters/letter templates (Correspondence); a template's own PDFs in letters/<code>/<code>.ymljcm-correspondence
letterheads/letterheads shared by templates, each with its PDF in letterheads/<code>/<code>.ymljcm-correspondence
print-batches/print batches: which prepared pieces a run picks and how its files are split and named (Print batches)<code>.ymljcm-correspondence
rules/validation rules (Validation rules)<code>.ymljcm-validation
questionnaires/questionnaires (Questionnaires and wizard)<code>.ymljcm-forms
duplicates/the duplicate rule of one case type (Duplicate detection)<binding>.ymljcm-duplicates
job-roles/job roles (Job roles)<code>.ymljcm-roles
assignment-rules/assignment rules (Assignment rules)<code>.ymljcm-roles
dashboards/dashboards (Dashboards and alerts)<code>.ymljcm-dashboards
jobs/scheduled jobs (Scheduled jobs)<code>.yml, the code starting jb.jcm-jobs
roles/data resource roles, fixed when the app is built (Data roles)<code>.ymljcm-security
audit/hand-written entities whose field changes are kept, fixed when the app is built (Field history)<Entity>.yml, keyed by entity:jcm-audit
shared-forms/forms of shared records, fixed when the app is built (Shared records)<Entity>.yml, keyed by entity:jcm-workspace
  • A workflow's file holds one version: wf.appeal.v1.yml holds code: wf.appeal and version: 1, written without a leading zero (v01 is refused).
  • A duplicate rule has no code of its own; its key is the case type it is for, so duplicates/case.appeal.yml holds binding: case.appeal.
  • A reference list another file defines (an add-on's document types, link types, rooms or holidays) is extended by a file of the app's own, named as it likes, holding extends: <list> and items: and nothing else. It only adds items: an item code the list already has stops startup. See Reference data.
  • A kind may let an item keep a folder of files beside its file (ConfigKind.withDataFolders()): seed/ does, so seed/seed.hearings.yml keeps the documents its records attach in seed/seed.hearings/, at any depth and of any name. They are read as bytes and never parsed (ConfigFiles.data(item)). The folder belongs to the item file of its name under the same root; a folder without that file stops startup (a folder of files belongs to seed/<name>.yml, which is missing). An override item brings its own folder. In every other kind's folder a folder is refused, as below.
  • Only .yml files are read as configuration. Files and folders whose name starts with a dot (.DS_Store, an editor's history) are skipped.

Date formats​

One rule writes every date: queue cells and queue exports, the case header, details and print summaries, date fields, the timeline, notifications, and a letter's ${record.<date>}. DateFormats gives it, and puts it in Jmix's format strings, so whatever Jmix formats follows it.

${today} is the exception: it is always the locale's long date, November 6, 2026 in English, in letters, other correspondence and any other file text, whatever dates says. A formal document dates itself in full; screens are compact.

  • Default. The locale's medium date and short time: Nov 6, 2026 and Nov 6, 2026, 3:30 PM in English, US English among them, 6 Nov 2026 in British English. Jmix's own default, day-first 06/11/2026, is never used.

  • One setting per application. dates in jcm.yml replaces the rule for every locale:

    dates:
    date: d MMM yyyy # left out, the locale decides
    date-time: d MMM yyyy HH:mm # left out, the date then HH:mm, or the locale when no date is set
    entry: month-first # how a typed numeric date reads; left out, the locale's order
  • What a format may hold. y or yyyy, M to MMMM, d or dd, EEE or EEEE; in date-time also H, HH, h, hh, m, mm, s, ss and a. Other words go in single quotes. date must show the year, month and day and no time; date-time also the hour and minute, and a with a 12-hour time. A two-digit year, any other letter, an open quote, an entry other than month-first, day-first or year-first, an entry that contradicts a numeric date, or any other key under dates stops startup and is refused on publish, naming jcm.yml and the line. A numeric format such as dd/MM/yyyy is allowed when written; nothing gives one by default.

  • Date fields. A generated or XML date field shows the date format. Typed, it takes that format, yyyy-MM-dd, and a numeric date in one order, and shows the date format after. The order is the entry setting, else the user's locale: under US English 11/06/2026 is Nov 6, under British English 11 June. A numeric date format states the order itself, so no second order is tried. No order is ever tried after another, so a date is never read across locales. The time part of a date-time field is on the clock the date-time format writes: a 24-hour HH:mm shows and takes 14:00, a format with a shows and takes 2:00 PM, whatever the person's locale (a browser's time field knows clocks by locale only, so it is given the person's locale where its clock is that one, else British English for 24 hours or US English for AM and PM; seconds and other words of the format are not carried into the field). With no dates setting the date-time format is the locale's own (its medium date and short time), so the time field keeps the person's locale and its clock, as before; dates: {date: ...} written alone gives that date then HH:mm, so it puts every person on the 24-hour clock. Month names in a date field are English whatever the locale, as the browser field offers no other.

  • In Java. DateFormats.forUser() gives the patterns in force for the person signed in; date(value), dateTime(value) and time(value) write with them, fieldFormats() is what a date field shows and takes, and clock() the locale a time field is given. A field built with new DatePicker or new DateTimePicker goes through DateFields.formatted. A record control has dateField(label), date(day) and moment(at).

  • Left as they are. Year-less short dates (Mon 6 Nov on My day and Next up), the exact stamps of the audit and jobs admin pages and the studio's publish history (2026-11-06 15:30:00), and the studio queue editor's start and end dates, which follow the browser's locale.

  • The studio shows and edits it with the rest of jcm.yml, behind jcm.studio.edit.app.

jcm.yml (app-wide)​

jcm/jcm.yml holds only what is app-wide: the order of things that would otherwise have none. JCM reads it itself, with the other files; it is not a Spring file (no spring.config.import). The sample's:

# The app-wide settings. The job roles in the order the job switcher offers them; any role not listed follows by code.
job-roles: [job.case-worker, job.refdata-admin]
# The inbox: its tabs in order, and the queues each shows, in order. A queue not listed here is not in the inbox.
inbox:
tabs:
- name: My work
queues: [q.appeal.my-work, q.appeal.team]
- name: Intake
queues: [q.appeal.unassigned, q.appeal.in-review]
# The dashboards in the order a user offered several sees them; any dashboard not listed follows by code.
dashboards: [db.appeal.worker]
  • inbox: {tabs: [{name, queues}]} (jcm-queues): the inbox's tabs in order, each with the queues it shows in order. A queue no tab lists is not in the inbox, but is still a queue: a dashboard tile may show it to whoever may use it (QueueService.mayUse). A queue listed twice or with no file, or two tabs with one name, stops startup.
  • email: {ad-hoc-per-user-per-hour: 50} (jcm-email): how many ad hoc emails from cases one user may send in an hour, a whole number from 1 to 1000; checked at startup and on every publish (EmailSettings). A component that owns a jcm.yml key but no folder registers ConfigKind.appWideOnly(key, label, error).
  • tenant: {id, control-plane-url, report-every-minutes} (jcm-tenant): which tenant a hosted application is; see Tenant plan and usage. Left out, the application contacts nobody.
  • dashboards: [codes] (jcm-dashboards) and job-roles: [codes] (jcm-roles): the listed items first, in that order, then every other one by code. A code listed twice or with no file stops startup. dashboards may instead be a mapping, {order: [codes], ageing-bands: [7, 30, 90], max-pass-rows: 100000}: order as the list, ageing-bands the Ageing view's bands (ascending whole days, 1 to 8 of them; default 7, 30, 90), max-pass-rows the most rows one pass over a queue may read for a chart, Workload or Ageing (1 to 1000000, default 100000); out of bounds, or any other key, stops startup and is refused on publish, naming jcm.yml and the line. The list form keeps the defaults.
  • reports: {max-seconds: 60, max-rows: 10000} (jcm-reports): the report run limits (see Reports): max-seconds 1 to 600, default 60; max-rows 1 to 1000000, default 10000. A value out of bounds or an unknown key stops startup and is refused on publish, naming jcm.yml and the line. The kind's folder reports/ holds the report files (Reports: Report files), which are fixed at build; the limits still publish.
  • dates: {date: d MMM yyyy, date-time: d MMM yyyy HH:mm} (jcm-core): how the whole application writes a date and a date-time; see Date formats. Left out, the locale decides.
  • login: {links: [{label: Privacy notice, url: "https://example.org/privacy"}, {label: Terms of use, url: /terms}]} (jcm-core reads it, jcm-ui shows it): informational links in a small row below the sign-in form, on the shipped login view and the break-glass form alike, with no change to the shell or any Jmix view. A url is an https:// address or a site-relative path starting with /; at most 6 links; a label is 1 to 60 characters of plain text (markup shows as text). Each link opens in a new tab (rel="noopener noreferrer"), is an ordinary anchor reached by Tab, and the row wraps at phone width. They are links only: following one accepts nothing and records nothing. Left out, nothing is shown. An http:// or scheme-less address, a javascript: or data: address, an address with a space, an empty label, a label over 60 characters, more than 6 links, or any other key under login or a link stops startup and is refused on publish, naming jcm.yml and the line. The OIDC provider's own page is not JCM's, so it shows none; labels are not translated (one set per application).
  • A key is allowed only when its component is installed: inbox with jcm-queues, and so on. An app has one jcm.yml; an empty one, or none, means no inbox tabs and every order by code. A scaffolded app with jcm-queues starts with inbox: {tabs: []}.

Where files are read from​

  • jcm.config.locations (comma-separated resource roots, default classpath*:jcm/): every root is scanned, the app's own resources and each jar's alike. A test may add a root of fixtures.

  • classpath*:jcm-jobs/ is a further normal root, read only while jcm-jobs is installed (ConfigKind.shippedUnder). It is where a jar whose component does not need jobs keeps its job files, as jcm-attachments does: such a file in the jar's jcm/jobs/ would stop an application without jobs. An application's own job files stay in jcm/jobs/, and one there with no jobs starter is refused like any folder nothing reads.

  • jcm.config.overrides (comma-separated roots, default empty): a file under an override root replaces the file of the same kind and code (and version) from the normal roots, or adds one; a jcm.yml there replaces the app's. A replacement whose text differs from the file it replaces is logged at INFO naming both files; one whose text is identical is not. After the scan, one INFO line per override root says what it did to the application's files: <root>: <n> files identical to the application's, <m> changed, <k> added, <r> removed. This is how a test or profile uses a variant: the sample's test profile sets jcm.config.overrides=classpath*:jcm-test/. Two override files for one code are still refused, except that the studio's folder (next but one) replaces another override root's file of the same identity, and its jcm.yml another override root's jcm.yml, as an override replaces the application's: the studio's folder holds the edits made over everything the app read, and the replaced file is named under Replaces. A publish's candidate is built with the replacements and summary line logged at DEBUG, not INFO, so a check does not read as a start. A root that cannot be scanned (a folder that does not exist) is an empty root, not a refusal.

  • A delete marker is an empty file <folder>/<code>.removed (for a versioned kind <folder>/<code>.v<n>.removed, one version) under an override root: the item of that kind, code and version (letter case ignored) is left out as if its normal-root file were not there, so files(kind) and every registry go without it and a reference to it is refused as for a missing file. Its text is never read. Refused, naming the marker at line 1 with the kind's exception: one with nothing to remove (<marker>:1: removes queue 'q.x' but no file defines it; delete the marker; ... removes workflow 'wf.a' version 2 ... for a version), which is how a marker left behind after the file was deleted shows; one beside an override file of the same item in any override root (<marker>:1: queue 'q.a' is both removed by <marker> and defined by <file>); one under a normal root (a .removed marker belongs in an override root, not here; delete the marker (a build copies one left in the studio folder)); a versioned kind's marker without a version (a workflow marker is named <code>.v<version>.removed; name the version it removes); a second marker for an item already removed, in another override root or in another letter case (<second>:1: queue 'q.a' is removed twice: by <first> and <second>; keep one); and jcm.yml.removed (jcm.yml cannot be removed). A marker removes an item, not an extension file. Markers count as removed in the root's summary line. ConfigFiles.removedBy(LoadedFile) gives the ConfigFile a marker removed, as read (empty for any other entry), so its name can still be shown.

  • A kind can be fixed when the application is built (ConfigKind.fixedAtBuild(); isFixedAtBuild() asks): the entity model (model/, see Data model) and the data roles (roles/, see Data roles) are. Their files count only from the classpath roots (classpath:, classpath*:), where the build puts them: one under a disk folder jcm.config.locations names is refused, <file>:1: entity model files are read only from the application's classpath, where the build puts them; <root> is not on it. Remove the file, or the root from jcm.config.locations. Any file under its folder in an override root (a replacement, an addition, a copy identical to the application's, a file further down, or a .removed marker), in the studio's folder as in any root jcm.config.overrides names, is refused at line 1 with the kind's exception: <file>:1: entity model files are fixed when the application is built and cannot be replaced or removed by an override folder; change the application's file and rebuild (role files ... for a role file). ConfigFiles.withRoot and withRootBytes refuse the same in a candidate for an override root, and refuse a normal root given again unless it holds the fixed kind's files exactly as scanned: one changed, left out or added is refused with that sentence, naming the file. Nothing changes the model or a role file while the application runs: the studio stages such a change for the next build (see Configuration studio, "Staged editing"), and its candidate reads the fixed kinds as that build would copy them: ConfigFiles.asRebuilt(Map<String, byte[]> fixedFiles) replaces the normal roots' files of every fixed kind by the map (a path under a root, model/Party.yml, roles/reader.yml, access.yml; a file the map does not name is left out, as a build without it leaves it out), keeps a library's file of such a kind (read from a jar; and, where the studio folder is the source folder of a project, <project>/src/main/..., a file on disk outside that project, as a sibling module's resources folder an IDE puts on the classpath; with no such project every file on disk counts as the application's own build output), sets aside the studio folder's source copies of those kinds (jcm.studio.files-are-source), keeps every other file as found, runs every check the scan runs, and refuses a path no fixed kind owns (IllegalArgumentException). A replaced file keeps the name messages gave it; an added one is named under the same root.

  • jcm.studio.files (the studio's folder, see Configuration studio), when set, is the first override root, before any root jcm.config.overrides names: file:<absolute path>/, resolved against the working directory (ConfigFiles.fileRoot(Path) makes that string; ConfigFiles.studioRoot() returns it, null when unset). What the studio writes there replaces the application's files at the next scan, so a published change is what the loader reads at the next start too. ConfigFiles.roots() lists every root as configured, normal then override. With explicit jcm.studio.files-are-source=true (the local dev profile), an identical fixed model/role source copy is acknowledged but the built classpath file remains authoritative. A differing, newly added or deleted fixed source input during publishing requires rebuilding. Ordinary override folders cannot replace fixed files, even with identical contents; the source exception applies only to the configured Studio source folder.

  • ConfigFiles.loaded() lists what was read, as LoadedFiles: jcm.yml first when there is one, then each registered folder's files in registration order (ConfigFiles.folders()), each folder's by code and version as files(kind) gives them. Each names its folder (empty for jcm.yml), kind label, code (null for jcm.yml and an extension), version, extension, relative (the path under its root: workflows/wf.appeal.v1.yml, jcm.yml), root (the root as configured, classpath*:jcm/), jar, overriding, replaces (the display of the normal file an override file replaced, else null), display, text (the file as read), node and removal. A replaced file is not listed; data files are not listed. A file a marker removed is not listed either: the marker is, after its folder's files, as LoadedFile(removal = true) with the removed item's code and version, relative and display the marker's own (queues/q.appeal.team.removed), overriding true, replaces the removed file's display, text empty and node null; whoever walks loaded() for values skips removals. ConfigNode.scalars() walks every scalar value under a node in the order written (keys are not values; a value left empty or YAML null is left out), each a Scalar(value, line, key, owners): key is the nearest mapping key (null for an item of a top-level list), and owners each enclosing list item that names itself by code, else name, else label, else username (a seed's user), as Owner(listKey, id), outermost first.

  • Both are read from the Spring environment, so they go in application.properties or a profile's properties. Operational settings, such as jcm.attachments.max-bytes, stay ordinary Spring properties there too; they are not configuration items.

Values as written​

Every value is read as it is written in the file, not as YAML would type it:

  • Where text is expected, a value YAML would type stays text: 007, NO, ON, 1.50 and 2030-01-01 are those characters. Where text is required (a code, a reference list item's parent), a value YAML would read as a number, a flag or a date must be quoted (code: "007", parent: "NO", a holiday's code: "2026-12-25"), or startup stops saying to quote it.
  • Flags are only true or false; yes, no, on and off are refused.
  • A key written ~ or left empty (description:) is as if it were left out, so an optional key may be left empty and a required one may not. Leaving a rule key out altogether is fine: a field with no shown-when is always shown, a validation rule with no when always applies. Conditions are the one exception to "empty is left out": a condition key written with nothing after it (shown-when: or shown-when: ~, if: with nothing in it, an any: []) is refused, never read as "always". The same holds for the keys whose absence means "no restriction": a queue's roles, states and condition, a dashboard's roles, a workflow transition's roles and a question's show-if, written but empty (roles: [], roles:, condition: {}), are refused at their line, never read as "every role" or "every record"; leave the key out for that.

Upgrading an app written before this layout​

Work through the files first; startup names every one it refuses, except the inbox (step 7), which goes quiet.

  1. Remove spring.config.import=optional:classpath:jcm/jcm.yml (or any import of it) from application.properties.
  2. Move each entry of jcm.case-types out of jcm.yml into jcm/case-types/<code>.yml, its keys at the top of the file. Move any app switches of your own that lived in jcm.yml (as the sample's jcm.sample.*) to application.properties.
  3. Split every file that held a wrapper list (queues:, tasks:, deadlines:, letters:, rules:, questionnaires:, job-roles:, dashboards:, lists:, workflows:, duplicates:) into one file per item, each named by its code.
  4. Name each workflow version jcm/workflows/<code>.v<version>.yml, one version per file, no leading zero.
  5. Name each duplicate rule jcm/duplicates/<binding>.yml.
  6. Where the app added items to a list an add-on defines (document types, link types, rooms, holidays) by writing the same list code again, write instead a file of its own holding extends: <list> and items: only, without name or parent-list.
  7. List the queues in jcm.yml: inbox.tabs, each tab with its name and its queues in order, and drop tab: from every queue file (it is refused). This is the change startup does not catch: a queue no tab lists is silently left out of the inbox (it still works on a dashboard), so an app that only splits its files boots with an empty inbox.
  8. Put the order of dashboards and job roles in jcm.yml (dashboards: [...], job-roles: [...]); otherwise they are offered by code, which may change the default job role a user starts in.
  9. Move test and profile variants (a test jcm.yml, a case type differing under a profile) to an override root of their own, such as src/test/resources/jcm-test/, set jcm.config.overrides=classpath*:jcm-test/ in that profile's properties, and write each variant as the whole file it replaces. A list in a profile file no longer merges into or replaces a list; the file replaces the file.
  10. Rename .yaml files to .yml.

Then the values, read as written instead of through YAML 1.1's coercions:

  • required: yes and other flags written yes, no, on or off are refused: write true or false.
  • A condition value is the text written: equals: yes compares the text "yes", in: [NO] the text "NO".
  • A code YAML would type (code: 007, parent: NO, a holiday code: 2026-12-25) is refused until quoted.
  • A reference list's or item's name that YAML used to type (name: NO, once stored as "false") is now stored as written. Its entry's hash changes with it, so that entry is applied again once at the next start, over an administrator's rename of it.
  • A letter whose subject or body held a value YAML used to coerce gets a new hash in the same way and is applied again once, over an administrator's edit.
  • Unknown keys in reference list files, once ignored, are refused.