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).
| Folder | Holds | File name | Component |
|---|---|---|---|
case-types/ | case types (Case screen, below) | <code>.yml | jcm-core |
refdata/ | reference lists, and additions to one (Reference data) | <code>.yml; an addition any name | jcm-refdata |
workflows/ | one version of a workflow (Workflow) | <code>.v<version>.yml | jcm-workflow |
queues/ | queues (Queues and inbox) | <code>.yml | jcm-queues |
seed/ | demo data: users and records (Seed data) | <code>.yml, its files in <code>/ | jcm-seed |
tasks/ | task templates (Tasks) | <code>.yml | jcm-tasks |
deadlines/ | deadline policies (Deadlines and SLA) | <code>.yml | jcm-deadlines |
calendars/ | business calendars (Calendars and hours) | <code>.yml | jcm-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>.yml | jcm-correspondence |
letterheads/ | letterheads shared by templates, each with its PDF in letterheads/<code>/ | <code>.yml | jcm-correspondence |
print-batches/ | print batches: which prepared pieces a run picks and how its files are split and named (Print batches) | <code>.yml | jcm-correspondence |
rules/ | validation rules (Validation rules) | <code>.yml | jcm-validation |
questionnaires/ | questionnaires (Questionnaires and wizard) | <code>.yml | jcm-forms |
duplicates/ | the duplicate rule of one case type (Duplicate detection) | <binding>.yml | jcm-duplicates |
job-roles/ | job roles (Job roles) | <code>.yml | jcm-roles |
assignment-rules/ | assignment rules (Assignment rules) | <code>.yml | jcm-roles |
dashboards/ | dashboards (Dashboards and alerts) | <code>.yml | jcm-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>.yml | jcm-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.ymlholdscode: wf.appealandversion: 1, written without a leading zero (v01is refused). - A duplicate rule has no code of its own; its key is the case type it is for, so
duplicates/case.appeal.ymlholdsbinding: 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>anditems: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, soseed/seed.hearings.ymlkeeps the documents its records attach inseed/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
.ymlfiles 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, 2026andNov 6, 2026, 3:30 PMin English, US English among them,6 Nov 2026in British English. Jmix's own default, day-first06/11/2026, is never used. -
One setting per application.
datesinjcm.ymlreplaces the rule for every locale:dates:date: d MMM yyyy # left out, the locale decidesdate-time: d MMM yyyy HH:mm # left out, the date then HH:mm, or the locale when no date is setentry: month-first # how a typed numeric date reads; left out, the locale's order -
What a format may hold.
yoryyyy,MtoMMMM,dordd,EEEorEEEE; indate-timealsoH,HH,h,hh,m,mm,s,ssanda. Other words go in single quotes.datemust show the year, month and day and no time;date-timealso the hour and minute, andawith a 12-hour time. A two-digit year, any other letter, an open quote, anentryother thanmonth-first,day-firstoryear-first, anentrythat contradicts a numericdate, or any other key underdatesstops startup and is refused on publish, namingjcm.ymland the line. A numeric format such asdd/MM/yyyyis 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 theentrysetting, else the user's locale: under US English11/06/2026is Nov 6, under British English 11 June. A numericdateformat 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-hourHH:mmshows and takes14:00, a format withashows and takes2: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 nodatessetting 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 thenHH: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)andtime(value)write with them,fieldFormats()is what a date field shows and takes, andclock()the locale a time field is given. A field built withnew DatePickerornew DateTimePickergoes throughDateFields.formatted. A record control hasdateField(label),date(day)andmoment(at). -
Left as they are. Year-less short dates (
Mon 6 Novon 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, behindjcm.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 ajcm.ymlkey but no folder registersConfigKind.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) andjob-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.dashboardsmay instead be a mapping,{order: [codes], ageing-bands: [7, 30, 90], max-pass-rows: 100000}:orderas the list,ageing-bandsthe Ageing view's bands (ascending whole days, 1 to 8 of them; default 7, 30, 90),max-pass-rowsthe 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, namingjcm.ymland the line. The list form keeps the defaults.reports: {max-seconds: 60, max-rows: 10000}(jcm-reports): the report run limits (see Reports):max-seconds1 to 600, default 60;max-rows1 to 1000000, default 10000. A value out of bounds or an unknown key stops startup and is refused on publish, namingjcm.ymland the line. The kind's folderreports/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-corereads it,jcm-uishows 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. Aurlis anhttps://address or a site-relative path starting with/; at most 6 links; alabelis 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. Anhttp://or scheme-less address, ajavascript:ordata:address, an address with a space, an empty label, a label over 60 characters, more than 6 links, or any other key underloginor a link stops startup and is refused on publish, namingjcm.ymland 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:
inboxwithjcm-queues, and so on. An app has onejcm.yml; an empty one, or none, means no inbox tabs and every order by code. A scaffolded app withjcm-queuesstarts withinbox: {tabs: []}.
Where files are read from
-
jcm.config.locations(comma-separated resource roots, defaultclasspath*: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 whilejcm-jobsis installed (ConfigKind.shippedUnder). It is where a jar whose component does not need jobs keeps its job files, asjcm-attachmentsdoes: such a file in the jar'sjcm/jobs/would stop an application without jobs. An application's own job files stay injcm/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; ajcm.ymlthere 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 setsjcm.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 itsjcm.ymlanother override root'sjcm.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, sofiles(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); andjcm.yml.removed(jcm.yml cannot be removed). A marker removes an item, not an extension file. Markers count asremovedin the root's summary line.ConfigFiles.removedBy(LoadedFile)gives theConfigFilea 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 folderjcm.config.locationsnames 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.removedmarker), in the studio's folder as in any rootjcm.config.overridesnames, 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.withRootandwithRootBytesrefuse 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 rootjcm.config.overridesnames: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 explicitjcm.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, asLoadedFiles:jcm.ymlfirst when there is one, then each registered folder's files in registration order (ConfigFiles.folders()), each folder's by code and version asfiles(kind)gives them. Each names itsfolder(empty forjcm.yml), kindlabel,code(null forjcm.ymland 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),nodeandremoval. 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, asLoadedFile(removal = true)with the removed item'scodeandversion,relativeanddisplaythe marker's own (queues/q.appeal.team.removed),overridingtrue,replacesthe removed file's display,textempty andnodenull; whoever walksloaded()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 aScalar(value, line, key, owners):keyis the nearest mapping key (null for an item of a top-level list), andownerseach enclosing list item that names itself bycode, elsename, elselabel, elseusername(a seed's user), asOwner(listKey, id), outermost first. -
Both are read from the Spring environment, so they go in
application.propertiesor a profile's properties. Operational settings, such asjcm.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.50and2030-01-01are those characters. Where text is required (a code, a reference list item'sparent), a value YAML would read as a number, a flag or a date must be quoted (code: "007",parent: "NO", a holiday'scode: "2026-12-25"), or startup stops saying to quote it. - Flags are only
trueorfalse;yes,no,onandoffare 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 noshown-whenis always shown, a validation rule with nowhenalways applies. Conditions are the one exception to "empty is left out": a condition key written with nothing after it (shown-when:orshown-when: ~,if:with nothing in it, anany: []) is refused, never read as "always". The same holds for the keys whose absence means "no restriction": a queue'sroles,statesandcondition, a dashboard'sroles, a workflow transition'srolesand a question'sshow-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.
- Remove
spring.config.import=optional:classpath:jcm/jcm.yml(or any import of it) fromapplication.properties. - Move each entry of
jcm.case-typesout ofjcm.ymlintojcm/case-types/<code>.yml, its keys at the top of the file. Move any app switches of your own that lived injcm.yml(as the sample'sjcm.sample.*) toapplication.properties. - 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. - Name each workflow version
jcm/workflows/<code>.v<version>.yml, one version per file, no leading zero. - Name each duplicate rule
jcm/duplicates/<binding>.yml. - 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>anditems:only, withoutnameorparent-list. - List the queues in
jcm.yml:inbox.tabs, each tab with itsnameand itsqueuesin order, and droptab: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. - 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. - Move test and profile variants (a test
jcm.yml, a case type differing under a profile) to an override root of their own, such assrc/test/resources/jcm-test/, setjcm.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. - Rename
.yamlfiles to.yml.
Then the values, read as written instead of through YAML 1.1's coercions:
required: yesand other flags writtenyes,no,onoroffare refused: writetrueorfalse.- A condition value is the text written:
equals: yescompares the text "yes",in: [NO]the text "NO". - A code YAML would type (
code: 007,parent: NO, a holidaycode: 2026-12-25) is refused until quoted. - A reference list's or item's
namethat 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.