Skip to main content

Case screen and form rules

Case screen​

jcm-screen (needs jcm-ui and jcm-validation, whose save enforcement its form rules share) serves one screen for every case type in jcm/case-types/, with no view class or XML in the app: jcm_CaseScreen at cases/{type}/{id}, where {type} is the case code with dots as dashes (case.appeal is case-appeal; CaseScreenRoutes.slug(code), read back with CaseScreenRoutes.layoutOf(slug, layouts) by matching the declared codes, since a code may contain dashes; startup refuses two codes that would share an address, naming both files) and {id} is new for a case being created. A new case shows the header band ("New appeal") and the Details form alone, full width, with Save and Cancel; saving opens the case and starts its workflow (as every new record's save does, see Registry and services), puts the record's address in the browser and replaces the form with the full screen, whose header shows the new number, the stage line and the first transition without a reload:

  • When configuration changes (a studio publish), an open case screen shows the notification configurationChanged ("Configuration changed: <what>. Reload to see it.", Reload and Dismiss) and draws nothing again; see Configuration studio, "What open sessions see".
  • Header band: the case header (number, state, title, header fields, assignees) with, when the workspace names deadlines, the nearest running deadline in words ("Decision due in 4 days"; jcm-warn within 7 days, jcm-danger once overdue; CaseHeader.setShowDeadline(true), off on hand-built screens), the Add menu (#caseAddSlot, see below), the transitions (the first allowed one as the primary button, the rest in a More menu: TransitionBar.setMenu(true)), "Email parties" for a user who may write ad hoc email from the case (#caseEmail, see Email: Ad hoc email from a case), the queue buttons marked on-record (#caseQueueButtons, see Queues: On the record), and the stage track as a thin line: the case's path along its stages (see Workflow: stages), passed, skipped, current and ahead, or where it ended.
  • Tabs: Overview, each child type in workspace.tabs with its count (none for a child type the user may not read; the count the tab's list found when it drew, counted again only for a replaced tab whose list stands for its caption alone), Documents and Letters when the workspace names attachments / letters, then other controls listed in tabs (CaseOverview.tabItems(layout)).
  • Overview (CaseOverview): Next up (NextUp: open tasks, running deadlines and upcoming hearings by date, each only when tasks, deadlines, hearings is in workspace.overview; "Nothing due. Add a task or schedule a hearing." when empty) and Activity (the timeline, note box first) in the main column; in the rail Details (DetailsSummary: read-only until Edit, then the generated form in place with Save and Cancel), a short list of each children: entry of workspace.overview in order with View all, related cases, possible duplicates and reports when workspace.overview names them, and each questionnaire of the type while not submitted. A rail section with nothing to show is left out (RecordControl.setLeftOutWhenEmpty, class jcm-nothing). Under 960px it is one column: Next up, Details, Activity, the rest.
  • Add menu (AddMenu, #addMenu; the button #caseAdd, entries add-{code}): Note, Task, Hearing, Document, Letter, Related case, then each top-level child type by its entity's name ("Party", "Decision"). An entry is there only when its control is named in the workspace (timeline, tasks, hearings, attachments, letters, related-cases; leaving out hearings removes Hearing) and the user may add that kind of record (Note, Task, Letter: the update right on the record), and for a child type when the user may create it and change the case. screen.add in the case-type file lists the entries in order (note, task, hearing, document, letter, related-case and child codes) and leaves out the rest; an unknown or repeated entry stops startup. A control entry opens the control's form in the side panel (vaadin-dialog .jcm-side-panel, #addPanel, titled "Add task"); saving closes it, redraws the screen's controls (RecordControl.refreshAll, which reaches the controls of every tab of a tab sheet, not only the open one), announces what was added and leaves focus on the Add button. A refused save keeps the panel open with the reason on the field. A child entry opens a new record where ChildOpener does (panel or page, per open). On the generated screen the controls draw no add-form of their own; the timeline keeps its note box wherever it is placed (it ignores setInlineForm; notes="false" hides it), for someone who may add a note; anyone else sees the history with nothing in the box's place. Hand-built screens are unchanged. A refused upload shows its reason on the form (#attachmentError), inline and in the panel.
  • Overrides: two supported application levels; neither copies the screen into the app. (1) the case-type file's settings (form, header, workspace, screen.add). (2) A replaced section: a Spring bean implementing com.jcm.screen.CaseScreenSection names a case type (caseType()), a section (section()) and makes the component that stands there (create(CaseScreenContext)), each time the screen draws it; the rest of the screen stays generated. Sections: header-actions (the band's actions, in place of the Add menu and the transitions; on a new case too), details (Details in the rail of a saved case; a new case keeps its generated form, which creates it), next-up and activity (the overview's main column, shown whatever the workspace names), rail (the rail below Details), or a top-level child type's code (the content of its tab, which keeps its caption and count and is left out as before for a user who may not read the type). Build sections from listed Vaadin types, not internal JCM controls. CaseScreenContext gives binding() (the case type's code), record(), isSaved(), hasChanges(), removable onRecordChange/onSaved callbacks, refresh(), which redraws the screen's controls, child lists and counts, and addMenu() and transitions(), the screen's own header parts. Raw layout/container/dataContext access is internal. A section that throws while being made shows "This part of the case could not be shown." and the cause is logged. CaseOverrides (jcm_CaseOverrides) reads the beans once the context's beans are made: an unknown case type or section, a grandchild's code, or two beans for one case type and section stops startup naming the beans. Framework/legacy custom detail views remain described under Opening a case, but are outside the supported application API. Field hooks under Form rules are also framework/legacy only. A replaced header-actions stands in for the Add menu and the transitions; to keep them, place the context's addMenu() (the #caseAddSlot slot, empty while the case is new and given the menu once it is saved) and transitions() (the band's TransitionBar: menu style, with the fields a transition's form rules ask for), never a menu or bar built by the app. A context without them (made by other code) throws IllegalStateException. Wherever a section places them, the band draws its actions in one order: the primary move, then the record's other actions (declared, link, create, email and queue buttons) while they fit, at most --jcm-band-actions-visible, then the Add menu, and last one More holding the record's other moves and every action that did not fit. The moves' own menu is always folded into that More, so nothing is drawn after More. The sample's AppealPrintSummary (sample_AppealPrintSummary) puts a Print summary button (a printable page of the saved appeal's fields the user may view, refused while the screen has unsaved changes) beside the two.
  • Record controls and the Add menu: a control offers its form through RecordControl.getAddEntry() (an AddEntry(label, form), the form made for a callback it runs once saved; override addEntry()), and draws it inline unless setInlineForm(false) (default true; CaseWorkspace.setInlineForms(false) for the controls it places). bindForAdding(binding, container, context) binds a control that is not on the page only to offer its form. CaseScreenUserRole (jcm-case-screen-user) grants the screen itself to a user; whether they may open a given case type is its entity's read permission, and a user without it is told "You may not see appeals" (the type's label-plural, in lower case). The screen is a StandardDetailView of the type the address names, so detail-view behaviour applies: unsaved changes are confirmed before leaving, and validation rules are checked on save, their messages beside the generated field (field-<attribute>) when it is shown, in a notification otherwise. A record someone else changed since the screen loaded it is not saved over, on the Details form, a child's page or panel, or a transition's dialog: the save fails, the user is told "Someone else changed this record at the same time, so nothing was saved. Reload it and try again." (StaleRecord.MESSAGE, jcm-ui) and keeps their edits on screen; a stale save that reaches the screen another way (a control's button, a save resumed after a warning) is shown in the same words by jcm_StaleRecordUiExceptionHandler, never as the generic error. Its title, in the app bar, is the case type's label ("Appeal"). CaseScreenView.getRecord(), getDataContainer(), getDataContext(), getForm() and getAddress() are for the parts that build on it and for tests.

jcm_CaseList at cases/{type} is the case search opened on that type, titled with the type's label-plural, with no switch to other types and a New button (New appeal) for users who may create its cases. The main menu gets one item per case type, ahead of the app's own items: id jcm_cases_{type}, titled with label-plural, opening the list. An item is shown to whoever may read the case type's entity; JCM grants no menu permission of its own, and CaseScreenUserRole grants both views, and the child views below.

Row rules in role files​

Which rows a role's actions reach is written in the role file, under the entity, as rows (jcm-security, beans jcm_RowRules, jcm_FileRowPolicies, jcm_RowRuleCheck). The rule is a condition in the condition language, compiled once at startup into query text and added to every secured read; writes are decided by the same text, asked of the stored row. Nothing is kept per person and nothing passes between servers.

# jcm/roles/appeals-worker.yml
entities:
Appeal:
actions: [read, update]
view: "*"
modify: [summary, outcome]
rows:
read: {assigned: me}
update: "state != CLOSED" # narrows read for update; never widens
Party: {actions: [read, update], view: "*"} # a child: carries the appeal's rule
Office: {actions: [read], view: "*", rows: {follows: [Party.office]}}
WrittenMeaning
rows: allThe role's actions on the entity reach every row.
rows: <condition>Short for rows: {read: <condition>}: a mapping, a list (all of them) or filter text.
rows: {read: c, update: c2, delete: c3}read is required. update and delete are each ANDed with read.
rows: {follows: [Entity.reference, ...]}A row is read where a row of that entity the same role reads refers to it through that to-one reference. It is updated only where the same role gives update on that entity and may update the referring row. It is deleted only where every row that refers to it through a listed reference is one the role may delete (so none where the role gives that entity no delete and a row refers to it): a shared row is not removed from under a record outside the role's reach. Reading the row followed from lends neither. One step: the entity followed from carries a rule of its own in the same role.
no rowsSee "What no rows means".

Conditions. Field leaves, state, count, exists, user, all, any, not, and two leaves of their own: {assigned: me | anyone | nobody} (jcm-assignments: a current assignment of the record names the person, anyone, nobody) and {org: owner | unit | unit-and-below} (jcm-security: the record's organisation scope has the person as owner, a unit they are a member of, or a unit at or under one of theirs). Both are asked of a case, the entity of a case type, and are leaves of the condition language everywhere a condition runs in a query, a queue's where included. {assigned: my-groups} is not built. role, transition, mode, a fact and a module's leaf with no row-rule form (documents, the filter language's case number and assignee) are refused in rows: a rule's text is fixed at startup and folds in nothing of the person. state is the state of a case type's own workflow; its name is not checked against the workflow, and one no workflow has matches no row.

No value is written into a rule. A constant from the file is a query parameter jcm_rowc_<n>; the person is jcm_user_username, the person substituted under substitution; a user leaf and a date counted from today are worked out when the query runs (jcm_RowRuleParams). With nobody asking, a rule holds nowhere.

Children. A composition descendant of an entity a role gives rows carries that rule with nothing written, at any depth: it is read where its parent is, updated and deleted where its parent may be updated, and created only under a parent that may be updated (a parent created in the same save passes with it). An update that names another parent needs that parent to pass too. A record that belongs to two ruled parents by composition is reached only where every one of them that it names reaches it, and it must name one at least; it is created or moved only where each parent it names passes. Each role is asked alone: one role's reach to the stored child is never joined with another's reach to the parent. A parent the role has no rule on is still asked for: a child is created or moved only under parents the person reads, so a role with rows on the child alone plants nothing under a record kept from them. rows written on a child narrows it further; rows: all there is refused while the role narrows the parent. The role file still lists the child with its actions: a rule reaches only what the same file grants.

Each role scopes its own actions. The roles counted are those of the authentication (the active job's, with the roles they include). Read is the OR of the rules of the held roles that read the entity; update is the OR over the held roles that give update, each by its own rule, and likewise delete and a child's create. A role that reads widely never lends its reach to another role's update.

Reach is one role file's alone. A grant is joined only to the rows of the role file that writes it: assigning is by the file that grants jcm_Assignment, where that file's own rows reach; a move is by a role its transition names, where that role's file, or the file of one role it includes taken by itself, reads the record. The rows of a role beside it, held apart or included by the same role, are never added to its grant.

The role that grants an action must itself reach the row. Some changes are granted by something other than the entity's update action, and for those the rule asked is the granting role's own, never the union of what the person reads:

  • A workflow move is granted by the roles its transition names. On a record whose entity a rule narrows for the person, it is made only where a role the transition names, which they hold, reads the stored record by its own rows (its own file's, or those of one role it includes, each asked alone). Their rule for update reaching the record through another role is not enough, and neither is another role that reads more widely. So a reviewer whose role is [read] with rows and is named in a transition makes that move on the records that role reads, and on no others; and a transition that names only roles with no rows (a role written in Java) is made by nobody but full access and system work on a managed entity: name the role files in the workflow. A transition that names no role is anyone's, and is made where the person's rule for update reaches. The moves offered (offers, availableTransitions, the transition bar, a board) are narrowed by the same question, so nothing is offered and then refused.
  • Assigning and unassigning are granted by create or update on jcm_Assignment. On a narrowed record the held role file that itself writes that grant must read the record by its own rows; the rule for update reaching it is not a grant of assigning, and neither is what a role included beside the granting one reads.
  • whyNot and whyNotOfMove answer "You may not change this record" for a move the rows would refuse.

Startup warns, by file and line, of what this leaves nobody able to do: a transition of a managed case type none of whose named roles is a role file that gives the entity rows, and a case type read by assigned while no role file grants create or update on jcm_Assignment. Neither stops startup.

  • A record's organisation unit and owner (OrgScopeService.assign, assignOwner and their by-id forms) decide who reads it under {org: ...}, so outside system work they are set only where the rule for update reaches the record. The scope a creation writes for its own new record asks nothing.

Roles are those of the session. A role given or taken away counts from the person's next sign-in, as it does for every permission: a revoked role keeps its rows until the session ends. A job switch counts at once, and so does every change of the data a rule reads (an assignment, a unit, a membership, a field).

What no rows means. An entity is managed when a role file writes rows on it, when jcm/access.yml lists it under default-deny, or when it is a composition descendant of one of those or followed to. A composition descendant of a default-deny entity is default-deny too.

Held roles that read the entityUnmanagedManaged, not default-denyDefault-deny
none writes rowsevery row, as beforeevery row, as beforenone
some write rowsn/athe OR of those; a role that reads it with no rows adds nothingthe same
one writes rows: alln/aevery rowevery row
full access (system-full-access), system workevery rowevery rowevery row
nobody asking (the anonymous session)as beforenonenone

A role written in Java or kept in the database carries no rows, so on a managed entity it adds nothing once a held role writes them, and on a default-deny entity it grants nothing at all; startup logs every role that reads a managed entity with no rows. An application whose role files write no rows and whose access file lists no default-deny is untouched: no policy, no query, no check is added anywhere.

Create. A new record of a case type cannot be placed by a rule that reads its companion rows, so creating one is the entity's create action alone, and what lets its creator read it back is the rule's own data.

  • Read by {org: ...}: a person who creates a record becomes its owner and it stands in their unit (OrgScopeCreateListener; an ambiguous unit refuses the save, as for the generated roles). The exported RecordOperations.save and RecordMoves.saveStartingIn have this written inside the save, before they read the record back.
  • Read by {assigned: me} alone: something must assign it. An assign action on a state a new record starts in (the workflow's initial state, or a state written entry: true for saveStartingIn), run as system, does it in the save that creates it. An automation, on record.created or any other event, or an assignment rule, runs later: a plain save stores the record and its creator reads it once the assignment has run, and the exported RecordOperations.save refuses meanwhile, since it has no record to hand back. A hook that assigns as the person is refused, since assigning is a change of a record they do not yet read; a Java hook that assigns as system work does it, and startup cannot see it.
  • Intake that stays open to everyone until it is taken needs none of that: rows: {read: {any: [{assigned: me}, {assigned: nobody}]}} reads a new, unassigned record by its second branch, and assigning it to one person takes it from the others at their next query.
  • A shared record read by follows is created before anything refers to it and is invisible to its creator until a row they read does, so create it in the save that refers to it or as system. A generated form does so with nothing written: New under a shared-record field stores such a record with the record that refers to it (Shared records, "A new record stored with the case").

Startup asks whether those who create a record read it back. People hold roles together, so the question is asked of each job role: where one of its roles (with the roles it includes) gives create on a managed case type's entity, the read rules of its roles are evaluated against a record as it stands when created, each with three answers, and joined by or. A role that reads the entity with rows: all makes it true; a role with no rows on it adds nothing, whatever it grants. Known at creation:

  • it is in a state a new record may start in: the initial state of the latest version of each workflow of the case type, or a state written entry: true. state is true only if it holds for every one, false if for none;
  • a move action on one of those states may take it elsewhere before it is read back, and then no state leaf can be told;
  • it is assigned to nobody at the instant of the save, so {assigned: nobody} holds and {assigned: anyone} does not, unless an assign action stands on one of those states (then no assigned leaf can be told). Where an automation for the case type lists assign or an assignment rule is written for it, {assigned: me}, {assigned: anyone} and {not: {assigned: nobody}} cannot be told either: the record becomes somebody's soon after, perhaps its creator's;
  • its creator is its owner where a rule reads the case type by org; their unit is not known;
  • a run action on one of those states is code in the save, which may assign or move the record: no state and no assigned leaf can be told then;
  • its fields, its children and the person are not known. A Java hook is not seen at all: a lifecycle hook or an EntityChangedEvent listener of the application's that assigns a new record to someone else takes it from a creator who reads by {assigned: nobody}, and the startup check cannot see it.
The job role's rules, for a new recordDefault-deny entityManaged, not default-deny
certainly holdstartsstarts
certainly do not, a rule being heldrefused, at the job role's resource-roles linewarning
the job role creates and holds no rows at allwarningstarts
cannot be toldwarningwarning

Startup is refused by this check only where a rule that is held is certainly false for the creator: {assigned: me} with nothing that assigns, a state no new record starts in. A job role that creates through a role with no rows (a role written in Java, say) and holds none starts, with a warning that nobody working as it reads a new record. {assigned: me} with an automation or an assignment rule starts, with a warning that the creator does not read the record until the assignment has run and that RecordOperations.save refuses meanwhile. Intake by any: [{assigned: me}, {assigned: nobody}] starts with no warning, an assignment rule or not; that such a record leaves its creator's reach once it is assigned to someone else is logged once at INFO.

A role file that gives a case type rows and belongs to no job role that creates the entity is held beside roles the files do not name. It is judged alone and never refused: where its rule is not certainly true for a new record and some role creates the entity, startup warns at the role file's line. Put the roles people hold together in a job role to have them judged together. The warnings are logged at startup and shown beside the result of a publish.

And at run time, whatever startup said:

  • A new record its creator could not read once saved: a plain save through the data manager (a generated screen, an import) stores it, and it is invisible to them until the rule's data lets them read it; RecordOperations.save, which hands the record back as its caller reads it, refuses with "You may save <Entity>, but you could not read it once saved; nothing was saved." and stores nothing.
  • A change that takes a record out of its saver's own reach is stored: writes are decided by the stored row, which the saver was allowed to change. RecordOperations.save then has no record to hand back and throws com.jcm.core.RecordSavedOutOfReach (part of the exported extension API), a plain message ("Saved. It is now outside what you can open.") and not a refusal: nothing is rolled back by it within that save, though a transaction of the caller's own around it ends as the caller lets the exception end it. A generated screen shows the same sentence and closes.
  • Thrown by an effect of a workflow move, it is caught by the move, which goes on: the effect's save was allowed and is kept with the move. An effect that lets it pass through a @Transactional method of its own has marked the transaction to be rolled back, and the move is refused at once with nothing saved. Anywhere else that it ends a larger change (a hook, an action's handler, code of the host's inside its own transaction), that change is rolled back as for any exception, and the transition bar and the queue's row actions then say "Nothing was saved: a step of this change saved a record that is now outside what you can open, and the change could not go on after it." (RecordHandOffs.NOT_SAVED), never "Saved.", whether it reaches them bare, as from a lifecycle hook, or wrapped. Catch it around the save to go on.
  • The exported save writes the scope of a new record only where a role file reads its case type by org; on any other entity it runs the statements it ran before row rules, which a test pins per database.
  • Either way a person's save that leaves a record outside what they can open is logged at WARN with the entity, the id and the username (jcm_SavedOutOfReachLog). The log looks at a run of fifty saved records on a thread and at five a second after that, so an import of many is not slowed by it and a long run is logged in part.
  • A record's address opened by a person who cannot be shown it (a case taken from them since, a bookmark, a typed address) shows "This record is not available to you" in the page, under the browser title "Not available": the case screen (caseRefusal), a child record's page and a child's panel opened from a row drawn earlier (childRefusal). The words are the same for a record outside what they can open, one that does not exist, text that is no id, and a child under another parent, with row rules or without, and name no type, id or record, so an address cannot be used to find out which records exist; the address itself stays as it was typed, and the page shows the record again once it is entered with the record back in reach. Every refusal of the case screen and of a child's page has a way on under it, "You may not see appeals" and "There is no such record on this case" included: a link to the person's home (refusalHome) on a page, Close (closeButton) in a panel. The log says which it was, with the username: WARN <Entity> <id> was asked for by <username> and is outside what they can open, INFO ... and there is no such record, ... and is no id of it (with the cause) or ... at the address of a record it is not under; text of an address is written without control characters and cut to 64 characters. Any other screen's loader that finds no readable record, as an application's own detail view at its address, gets the same sentence as a warning notification (jcm_RecordUnavailableUiExceptionHandler) in place of the generic error, and the exception goes to the log at WARN with its stack; there the address goes on to its first segment, as Jmix's error page does. Only a loader's own failure while loading is taken so: the same exception thrown by application code, or inside a save, keeps the generic error.

Handing a record on is supported by three routes: the assignment service (reassignUser, by a role that grants assigning and reaches the record), a workflow move (by a role the transition names that reaches it), and a field the rule reads, saved by someone the rule let change the stored row. A hand-off's destination is constrained only by attribute permission and update reach on the stored row: a rule does not say to whom a record may be handed.

What the services do. Every read through the secured data manager carries the rule: open by id, search, quick find, queues and their counts, dashboards, exports, reference pickers. Beside that, on a managed entity: WorkflowService.move (the transition bar, a board, RecordMoves.move) refuses a record the person does not read before anything of it is told, then asks the rule role by role as above, and currentState, current, offers, whyNot, history and path answer as for a record with no workflow; AssignmentService assigns and unassigns as above, lists who holds a record only to those who read it, and assignedTo leaves out ids they do not read; RecordDocuments.mayRead and mayOpen by document id ask the rule of the document's record; CaseReportService.runForRecord refuses a record the rule keeps; DeadlineService.overdue leaves out deadlines of such records, and the delivery ledger of a communication leaves out events of such records; an unread alert of a record since lost reads "A record you can no longer open" and no longer leads to it; the Removed records screen lists an entity's removed records only to a person no rule keeps any of its rows from, since a removed row can be asked nothing. System work is outside all of this by design: an action or an automation written as: system is the application's stated way round, and SystemWorkBoundaryTest lists every component file that reads an application record round the rules, with its gate or reason.

Limits, stated plainly.

  • Not yet, and not to be relied on:
    • A related move or an on-enter move made with system authority moves records the person who started it cannot reach: it is the workflow file's move, run as system work.
    • A direct save of a jcm_Assignment or jcm_OrgScope row by an application's own code is not gated; only AssignmentService and OrgScopeService ask the rules.
    • follows delete looks only at referrers through the references the role lists, and not at rows removed softly: a row referred to through another reference, or by a softly removed row, may still be removed.
    • There is no group assignment: {assigned: my-groups} is refused.
    • Query plans at 50,000 rows and above are not measured; RowRulePlanTest is not written.
    • state names in rows are not checked against the workflow.
  • References to records a person cannot open. A record the person reads may refer to a row of a ruled entity they do not read. Every entity load made for a person is judged after it is read: each loaded reference into an entity their rows narrow is asked for by value with the rule's own text, and one they may not read is erased, so the attribute reads null and the hidden identity is kept on the record, on the server (HiddenReferences). A lazy reference is judged as it loads, and so is what a save reads back. Nothing of the hidden record, name, id or field, is in the record a screen holds. Full access and system work are not judged, and an application whose role files write no rows pays nothing.
    • What is shown. A generated reference field over a hidden reference is read-only, shows A record you cannot open and says This holds a record you may not see, so it cannot be changed here. (#field-<attribute>-hidden); the header, the details summary, the queue record panel and search results show the same words (AttributeAccess.RECORD_YOU_CANNOT_OPEN, asked by AttributeAccess.hiddenAt(record, path)). A reference that is not set shows as before. The lock is part of saving: a locked field is not validated, so a required reference that is hidden does not stop an unrelated save. A picker whose options follow another field (filtered-by) offers nothing and is disabled with its hint while that field holds a hidden record, and asks the database for no options, so the option list never tells which record it is.
    • What a save keeps, and refuses (ReferenceGuard, by the stored row, on every save through any data manager). A copy the person's own load erased a reference from is marked. A marked copy left alone is saved and keeps the stored reference; a null on it is the erasure, so a hidden reference cannot be cleared by someone who cannot see it. Any value set on a marked reference is refused (Party.office holds a record you may not read, so it cannot be changed), the hidden record's own identity among them. A reference set to a record the person cannot read is refused with one sentence whether that record is hidden or does not exist, and whether or not it is the stored one (You may not set Party.office to a record you cannot read), on a new record too, and on a copy loaded before the record was hidden even if untouched: reload, and the edit stands. A copy with no mark that changes or clears a reference whose stored record is hidden is refused with the first sentence. What a marked copy keeps must still be what is stored, whoever saves, full access and system work included: otherwise the save is refused as a stale record (Someone else changed this record at the same time, so nothing was saved. Reload it and try again.), and so is a marked copy on which full access or system work set the erased reference. On a copy with no mark, full access and system work set and clear any reference as before. A stored record of a narrowed entity that the person does not read is refused first, whatever it holds (You may not change this record).
    • How a refusal is told. These refusals are com.jcm.core.access.ReferenceRefused, a SecurityException whose message is the sentence for the person (a PlainMessage). A generated screen shows it as a warning, as it shows a stale record; where the copy on screen no longer shows what the person may see (the two sentences about a record they cannot read), it reads the record again, the field then shows the fixed words, and the change is made again and saves. Reading it again drops everything the person had typed on that screen, and the warning says so after the sentence (Your changes were not saved and the record was read again; make them again). A save held for a warning and resumed by "Save anyway" is told and read again the same way (HiddenReferenceDetailShellTest.aSaveResumedAfterAWarningThatIsRefusedReloadsAsADirectOneDoesAndThenSaves). A refusal that reaches the screen any other way, as from a control's button, is shown as the same warning (ReferenceRefusals) and the screen is left as it is; every one of these paths writes the refusal to the log as a warning naming the person (A save by <username> was refused: <sentence>). A queue's bulk action reports the sentence for the row it refused. A bulk set of a reference to nothing on a row whose reference is hidden reports the row as done and clears nothing: a null on a marked copy is the erasure itself.
    • Lists (to-many, no composition, the owner's side). Hidden members are left out of what is loaded and kept on the record. A member the person cannot read is not added, to a new record or a stored one. The hidden members a copy keeps must be those the stored list holds now, or the save is refused (stale for a marked copy; ... holds a record you may not read, so it cannot be changed for one with no mark). While the stored list holds a hidden member, the members the person reads must be left as they are. Two things differ from a single reference and are not guarded: a hidden member that becomes readable after the load makes the next save of that copy stale, where a single reference is saved; and the order of a list around a hidden member, and duplicates in it, are not compared.
    • Which rule applies when. In an application whose role files write no rows and whose access file lists no default-deny entity, SharedRecordGuard and the check of RecordOperations.save answer alone, as they always did: a shared-record reference left alone may stay on a record the person cannot read. Where rows are in force, ReferenceGuard answers for every reference into an entity the person's rows narrow, marked shared-record or not, and SharedRecordGuard leaves such a reference to it, so the person gets one refusal in the sentences above whichever is heard first: a reference left alone on a record they cannot read is then refused too until the copy is loaded again and holds the mark of the erasure, and a marked copy whose kept record is no longer the stored one is refused as a stale record. RecordOperations.save asks its own check before the store hears of the save, so a marked copy that was set, or whose kept record is no longer the stored one, is refused there in that check's one sentence for both (Party.office held a record you may not read when it was loaded, so it cannot be changed or saved through this copy); every other refusal of a reference is made inside the save.
    • What must not be done. A person's save may not carry the jmix.skipEntitySavingEvent hint for a record with references into a narrowed entity (Party cannot be saved with the saving event skipped: ...). A person's load that joins a transaction and would erase on a record the transaction still manages is refused and the transaction rolls back (... cannot be loaded here: it is being changed in this transaction and holds a record you cannot open. Read it by value. Nothing was saved.): read by value inside a save (storedValue). System work never receives a record loaded for a person: a lazy reference of such a record that fires under system work into a ruled entity is refused (A record loaded for a person was read under system work; reload it by id), and thrown inside a transaction that refusal ends it.
    • The read-back of a save has its references judged as a load's are; the record itself is not judged by it, so a save that hands the record on out of its saver's reach still returns it (the hand-off rule above). A screen's read-back judges the record too, as before.
    • Cost. For a person whose rows narrow what a reference names, a save of a record sends, beyond the save itself: one value query for the stored identities of its loaded single references into narrowed entities; one for which of those and of the held ones the person reads, for each entity named; one more where the record's own entity is narrowed (reach is asked first); and for each list the record holds on its own side, one for its stored members and one for which of them and of the held ones the person reads, the second not sent where there is none to ask about. So a record with one such reference sends two, three where its own entity is narrowed; one with such a reference and a list sends four; and its read-back one for each entity named (HiddenReferenceCostTest). A marked copy saved by full access or system work sends one value query, and one more for each marked list. A load sends one for each narrowed entity among what it loaded, whatever the number of rows, and one more for each further 1,000 identities; a lazy list on a narrowed owner sends two. An application with no rows sends nothing.
    • Who an action runs as. A transition's action list, an on-enter list and an automation run as the system: they read and write the whole record, hidden references included, and are not held to these rules, so a set or a copy there that reads a field through a ruled reference writes it where the worker reads it; startup does not yet warn of that. A declared action (actions: in a case type) runs as the person who calls it unless it says as: system: it loads the record as a load of theirs would, so a set of another field keeps a hidden reference, and a set of the hidden reference itself to nothing leaves it stored, a null on that copy being the erasure. A set writes a reference only from another field of the same record or from a code a ReferenceCodes bean resolves, never from an identity, and the platform's two resolve a reference list's item code and a username. So neither authority lets a person name a record of a ruled entity by a value they give, or learn from the answer whether one exists. An application that adds a ReferenceCodes of its own for an entity whose rows are ruled would open both, since a code is resolved with no rule asked: do not add one. A queue has no button that runs a declared action; its set button is the bulk action above. Code that runs under system work and is handed the record a person's move held (a code audience, a hook) must reload it by id: a reference that copy has not loaded refuses the read, and one erased from it reads as not set.
    • What a clock tells. A clock whose calendar is chosen by a reference (calendar: {by: ...}) carries the chosen calendar's code and the due date counted on it. Someone who reads the record and its clock, and not the record the reference names, can tell from those which case that record falls in. That is the policy's own outcome, as a rule's is: do not choose a calendar by a field whose value is confidential.
    • Limits. A hand-written entity that holds a reference into a ruled entity must carry a @Version attribute, as a model entity does: the rules above keep the reference itself from being lost, and only the version keeps the record's other fields from a save over someone else's. A reference-list field (a ref type, shown by the reference-list picker) is not locked over an item its reader may not open, so rows on jcm_RefItem, or jcm_RefItem under default-deny, stop startup (the table below). A header alert whose condition reads a field through a ruled reference tells that field's truth, as a form rule does, and startup warns of it as of one. A reference held by an embeddable, or not stored, cannot be secured, and startup refuses it (the table below; RowRuleCheckTest.aReferenceIntoARuledEntityThatIsNotStoredOrIsHeldByAnEmbeddableStopsStartup), so nothing is done for it at run time. Where the saver holds a read rule asked in memory (a Java row-level role, a script policy) on the entity being saved, which startup allows only on an entity no role file rules, that save's read-back is given no constraints, since the rule would be asked of the record itself, and loads and judges every single reference of the record. What it leads to further on would afterwards be read with no rule asked, so an entity that carries such a rule and leads to a ruled entity by stored references of any length, to one or to many, or to an entity any read rule of a row-level role narrows, is refused at startup (the table below), and that cannot arise. A rule's own outcome (a required-when on a field of the hidden record) still tells that field's truth. Sorting and filtering through a reference on an application's own grids, and a value query that selects a reference, are not yet held to these rules.
  • A query through a reference into a managed entity (a queue cell, a filter, a sort on appeal.title from a child) applies the rule in its subquery, as for any JPQL row rule; a queue's order by such a path is masked (below), and a child list's order by one is refused.
  • Sort and filter through a reference a person's rows narrow. A filter or an order by a field of a record a person may not read answers for that record even where the record itself is kept from them: the rows left by "office name starts with S", their count, or the place a row takes in a list ordered by that name. So on the platform's lists a path that passes through, or ends at, a reference into an entity whose rows are narrowed for the person at work is neither offered to them nor taken from them (ReferenceOffers, bean jcm_ReferenceOffers):
    • What a cell says. Where a row refers to a record the person may not read, a queue cell that shows the reference or a field through it, the queue's CSV export and a child list's text say A record you cannot open, always in those words; a row that refers to nothing stays empty.
    • The queue grid. The column still shows, and its header sorts, but the value it sorts on is masked in the query: where a step of the path enters a record the person may not read, the row sorts as if it had no value, after every value in both directions and in id order among such rows. So a row's place says no more than its cell, which reads A record you cannot open (ParentSortTest.aHiddenParentsValueDoesNotMoveAnyRow). A step whose rule a query cannot apply leaves the header unsorted, and a sort on it kept in settings or asked for anyway is dropped, the rows then in the queue's own order. The Filter panel does not offer the field. A condition on such a path that arrives all the same (in a filter configuration kept or given, or by a request the screen never offered) is taken off before a row or a count is read: the panel returns to empty, the configuration is no longer offered there, and the person is told This filter uses a field of a record type your access narrows. A condition written as query text is not taken from a person any of whose rows are narrowed.
    • A child list's sort (a case type's children: sort) through such a reference is not applied for that person: they get the list in the order it has with no sort. Sort a child list by a field of the child itself. A queue's own sort is a direct attribute already.
    • A create-case button's copy whose path passes through a reference that is hidden on the row is refused, This row holds a record you cannot open, so it cannot be copied., and no case is made. It is asked for the person at hand each time a list is built or read: someone whose rows on the referred entity are all keeps every sort and filter, as do full access and system work, and nothing is withheld in an application whose role files write no rows. Still open, not to be relied on: application grids and filters through a reference (an application's own view with a genericFilter or a sortable column on such a path), and a value query that selects a reference.
  • The entity inspector is withheld where rows are ruled. Jmix's entity inspector (Data management: datatl_entityInspectorListView, its record view and the menu entry) lists the records of any entity with every reference they hold, and no rule of a role file can leave part of it out. In an application where a role file writes rows or the access file lists a default-deny entity it is shown only to full access and the system role, whatever view permission another role gives, by menu, by address and as a dialog (InspectorAccess, bean jcm_InspectorAccess). The data model view beside it, which shows entities and attributes and no record, is as it was, and so is the inspector in an application with no rows.
  • Raw JPQL an application writes itself from an unmanaged entity through a reference into a managed one (select n from Note n where n.appeal.title like ...) is not rule-checked: the framework applies a row rule to a query's main entity only. The platform's own queries through references apply it; an application's own must start from the managed entity, or go through RecordOperations.
  • Rows may not be mixed with a generated organisation-scope role on one case type: a job role naming jcm-scope-<binding>-<level> while a role file writes rows on that case type's entity stops startup. Write the scope as rows: {org: ...}.
  • An Access scope (a database row-level role) on a managed entity is ANDed with the rule: it can narrow, never widen. Its read rule there must be query text with no join (below).
  • ALL_RECORDS reports read as system and are not yet refused over a default-deny entity; grant them by role.
  • A record's direct read of a companion entity (jcm_Attachment, jcm_Assignment, notes, tasks, letters) through a role's entity permission carries no generated rule yet; the platform's own screens read them behind the record's gate.
  • Each update or delete, and each child create, costs one query on the stored row.

Refused at startup, by file and line (roles/appeals-worker.yml:9: ...), and by a publish where what a rule is held against reloads: rows with an unknown key, update or delete without read, all beside a condition, follows beside another part; a condition the condition language refuses, one with no query form, or a leaf that cannot stand in a row rule; assigned or org on an entity of no case type; follows of an unknown entity or reference, of a reference to another entity or to many, from an entity the role does not read or gives no rows, of more than one step, or in a cycle; rows on an entity the role gives no read; rows: all on a child whose parent the role narrows; a default-deny entity no role file gives rows on; a role file whose includes reaches a Java or component role that reads a default-deny entity or every entity; a job role naming a generated scope role beside rows on the same case type; a job role that creates a default-deny case type which, as created, the read rules held in it certainly do not reach (above); and a rule whose text the database does not run, each compiled text being run once.

References into a managed entity: what startup refuses and warns of. A person who reads a record may not read a record it refers to; that holds only where nothing else carries the hidden record's fields to them. With rows or default-deny in force, RowRuleCheck also checks, at startup and at a publish, every reference into a managed entity (one with rows, one under default-deny, or a record that belongs to either by composition). An application with no rows and no default-deny is asked none of it.

What the application writesVerdictWrite instead
An entity whose instance-name (or @InstanceName, or the properties its name pattern depends on) is a reference into a managed entity. jcm/model/Appeal.yml:2: the name of Appeal reads Party, whose rows are ruled; ...RefusedName the entity by fields of its own: a record's name is stored in history and alerts, where no rule is asked.
A reference into a managed entity that is not a stored attribute of its entity (a transient or computed @JmixProperty), or that an embeddable holds. ...: Appeal.lead is not a stored reference the platform can secure: ...RefusedA stored to-one reference of an entity, or take it out. Records made in memory (not JPA entities) are not judged.
A child list's sort on a path through a reference into a managed entity, or on the reference itself (which orders by the name of what it names). case-types/case.appeal.yml:9: a child list cannot be ordered by a field of Party, whose rows are ruled; ... A queue's sort on such a path starts: its order is masked (Queues, the queue grid).RefusedOrder by a field of the listed entity itself.
A read rule on a managed entity that is a predicate or has a join clause, in a row-level role written in Java (@PredicateRowLevelPolicy, or @JpqlRowLevelPolicy with join) or in an Access scope. Row-level role <code> (<class>): a rule on Party must be query text with no join; ..., Access scope <code>: ...Refused at startup and at a publish whether or not anyone holds the role; an Access scope is also refused when it is saved (AccessPolicyGuard). A rule written on a parent class or a mapped superclass of a managed entity is applied to that entity by Jmix and is refused the same way (a rule on Person, which is applied to every Party, must be ...), and so is a rule written on a class under a managed entity, which is read by that entity's rows and so is ruled itselfThe rule as rows in a role file; or a where clause over {E} with a subquery in place of the join; or leave the entity unmanaged (no rows on it, out of default-deny). Rules for update and delete may stay predicates.
A read rule that is a predicate (@PredicateRowLevelPolicy with READ, or an Access scope's predicate) on an entity that holds a stored list of records of a managed entity, composition or not, whether or not the holder is managed itself; a rule on a parent class counts for every entity under it. Row-level role <code> (<class>): a rule on Folder may not be a predicate while Folder.members is a list of Party, whose rows are ruled; ...Refused at startup and at a publish; an Access scope also when it is savedThe rule as rows on the holder in a role file, or as a where clause over {E}; or take the list out. A saved record is read back for whoever saved it, and a rule kept in memory lets no query judge its list, so hidden members would be handed to them.
A reference declared of an entity no rule names that has a managed entity under it (a subclass). com.acme.entity.Shelf.thing: Shelf.thing is declared of Thing, whose rows no rule names, and can hold a SealedThing, whose rows are ruled; a reference is judged by the entity it is declared of. Declare it of SealedThing, or write rows on ThingRefused: a reference is judged by its declared entity as it loads lazily, as a save is read back and when it is saved, so this one would carry a ruled record past its rule. The same where the declared entity is ruled and a class under it has rows of its own (... and can hold a SealedThing, which has rows of its own; ...)
A read rule kept in memory (a predicate, of a row-level role written in Java, an Access scope or a policy contributor) on an entity that leads to a managed entity, or to one a read rule of a row-level role narrows, by stored references of any length. Row-level role <code> (<class>): a rule on Badge may not be a predicate while Badge.docket.venue leads to Venue, whose rows are ruled; ...Refused: a saved record of that entity is read back for its saver with no rule a query could ask of what it leads to
jmix.eclipselink.wrap-excessively-loaded-properties=falseRefused: a record loaded beyond a fetch plan would then read its references with no rule asked
rows on jcm_RefItem in a role file, or jcm_RefItem under default-deny. roles/clerk.yml:12: rows may not be written on jcm_RefItem: a reference-list field is not locked over an item its reader may not open, so a hidden item would show as an empty field. ...Refused: narrow what a list offers by the list's own means
The entity cache on for an entity that refers to a managed entity. com.acme.entity.Venue.office: Venue is cached and names Office, whose rows are ruled; ... (the model file and line where the entity has one)Refused, at startup and at a publishLeave the cache off for that entity (Jmix's default).
jmix.core.entity-serialization-token-required=true with no jmix.core.entity-serialization-token-encryption-key of the application's own (unset, blank, or Jmix's default KEY)RefusedSet the key to a secret, or switch the token off: the token of a record's JSON holds the identity of each record hidden from its reader.
A stored list of records of a managed entity that is not a composition (@ManyToMany, or @OneToMany with no @Composition). ...: Appeal.witnesses is a list of Party; hidden members are left out and the list cannot be changed while it holds oneWarningNothing, if that is meant.
A form rule (shown-when, required-when, read-only-when, in a case type, a child's form, shared-forms/ or extension-forms/), a header alert's when (header.alerts of a case type) or a validation rule (its when, its attribute or its check) that reads a field through a reference into a managed entity, also inside exists/count over a child. case-types/case.appeal.yml:31: required-when reads lead.status, a field of Party, whose rows are ruled; ...Warning, at startup and beside a publish's resultDo not write a rule on a record over a confidential field of the record it refers to: the condition is evaluated on the stored record, and its outcome shows to someone who cannot open that record. A condition on the reference alone ({attribute: lead, empty: true}) reads no field and is not warned of.
A queue's where that reads a field through such a referenceStarts; said once at INFONothing: the filter is applied with the managed entity's read rule.
A queue's old JPQL condition on such a path (e.office.name like ...)Starts; said once at INFOWrite it as where: condition is the application's own query text, run as written, and no rule of the managed entity is asked in it. Only paths from the row's alias (e.) are examined; a path inside a subquery with an alias of its own is not found.

A child's reference to its parent is judged like any other. A composition child is read no wider than its parent, yet none of these checks exempts the reference from child to parent: where Appeal is managed, a Decision named by its appeal (instance-name: appeal) is refused, a child list of decisions sorted by appeal.caseTitle is refused (a queue of decisions sorts by it, masked), and a form rule on the decision's form that reads appeal.status draws the warning. Name and order a child by its own fields; a rule that must read the parent is written with the warning accepted.

What the read-rule check cannot see. It asks every RowLevelRoleProvider (annotated classes on Jmix's scan, the database, any other provider) for the roles it has at startup and at each publish, and every PolicyStoreContributor but the platform's own for what it adds, on each managed entity and each class under one, as it answers with nobody signed in: contributor rules are judged as they apply to nobody signed in, at startup, at a publish and on the save of an Access scope alike. A provider that adds a role later without saving it through the data store, and what a contributor adds only for a person signed in, are not seen: an application that writes either keeps its read rules on managed entities to query text with no join itself.

A refusal names the model file and line where the entity has a model file, else the entity's class. The checks are RowRuleCheck.namedThroughRuled, unsecuredReferences, orderedThroughRuled, unqueryableReadRules, listsBehindInMemoryRules, cachedReferrers, openSerializationToken, listsOfRuled, rulesThroughRuled and filteredThroughRuled, each with a fixture in RowRuleCheckTest or AccessPolicyGuardTest.

Migration. Upgrade: nothing changes, and default-deny stops being refused. Add rows to the roles to narrow and rows: all to those meant to read everything; check what each role's person reads in a test. Make sure assignments exist (an assign action on create, or a backfill): a record nobody is assigned to is invisible to workers and visible to managers by unit. Then list the entity under default-deny; from there a new role with no rows grants nothing.

Opening a case​

Everything in JCM that opens a record (queue and inbox rows, my tasks, dashboard alerts, the calendar, recently viewed, quick find, search results, related cases, possible duplicates, child pages and their breadcrumbs) asks the RecordOpener bean in jcm-core first: boolean open(Object record), open(record, queryParameters) for a return to a tab, and openFromList(record, queryParameters) for a row opened from a list with words on its address (a queue's ?queue=<code>), closing back to the list as open(record) does. True means it opened the record; false, or no such bean, leaves today's Jmix navigation to the entity's detail view. jcm-screen provides it as CaseNavigator (jcm_CaseNavigator), which also offers openNew(caseType). A case opens on the app's own detail view for its entity when the app has one, meaning a view Jmix would find for it (the standard <Entity>.detail id or @PrimaryDetailView); otherwise on the case screen. A child record opens on the app's own detail view for its entity when there is one; otherwise a record of a type that opens in the panel (the default) and sits directly under its case opens in the side panel on its case's screen (cases/{type}/{id}?child=<code>&record=<id>), and any other opens on its page (below). Records that are neither cases nor declared child records are left to the caller. A Jmix entity picker's own open action on a case entity, outside JCM, finds no detail view unless the app has one.

Child records​

A child type with no detail view of the app's own gets a generated form (FormGenerator, the child type's form, its parent reference left out) with Save and Cancel (#saveAndCloseButton, #closeButton; only Close when the user may not change the record), the breadcrumb from the case, and under the form the lists of its own child types with New and Open. Where it opens follows the child type's open:

  • open: panel (the default): ChildPanel (jcm_ChildPanel) in the side panel beside the case (vaadin-dialog .jcm-side-panel, fields in one column). A record directly under the case keeps ?child=<code>&record=<id> in the case page's address while it is open, and that address opens it again.
  • open: page: ChildScreenView (jcm_ChildScreen) at cases/{type}/{id}/{child}/{childId}, one {child}/{childId} pair per level (cases/case-appeal/<id>/parties/<partyId>/contacts/<contactId>), under the case header; a new record is .../{child}/new under the record before it. Saving puts the record's id in the address; Save and Cancel return to the parent (the case on the child type's tab). Every child record has this address, whatever its open, so a deeper record or a copied address can always be opened as a page.

The address is checked from the case down: each code must be a child type of the level above, each record one the user may read whose parent is the record before it. A case or a record on the way that is not there, is not readable or is under another parent shows "This record is not available to you" (Data roles, "Row rules in role files"); an address that names no child type of its level, or a code without its id, shows "There is no such record on this case". Nothing is loaded either way. A user who may not read the child type is told "You may not see contacts"; a new record under a parent the user may not change, or a child they may not create, is refused ("You may not add decisions to ..."). A new record from a list's New button or the Add menu gets its parent set under the same rule. CaseScreenUserRole grants both views.

A saved record whose child type has a workflow of its own shows that workflow on its page and in its panel: a band (#childWorkflow) under the breadcrumb and, on a page, the case header (#childCaseTop), holding the record's path (#childStageTrack) with its transitions beside it (#childTransitionBar, menu style, with the fields its own form rules ask for and its transitions' confirm), then the queue buttons marked on-record (#childQueueButtons, see Queues: On the record); a type with no workflow gets the band for those buttons alone. It is drawn the same way on the app's own detail view for the child entity. A new record, a record of a type with no workflow and no such button, and a user who may make no move see no buttons; a user who holds none of a transition's roles does not see it. A band that fails to draw is left out and logged at WARN; the breadcrumb, the case header and the form stay.

When a child's side panel closes, after a save, a move of the child's own or nothing, the page it was opened from is brought up to date without a reload (RecordRefresh, jcm_RecordRefresh), as is the case screen beneath when that page is itself a panel: each record its controls show is read again from the database into the page's data context, and every record control redraws, so the parent's moves and why they are held (a when on its children, their states among them), its record actions, the stage track, the deadlines, Next up and the timeline answer for what the child did, including a child's on-enter move of its parent or case. The side panels still open between the one that closed and the page are brought up to date the same way, nearest first; a panel closing as its page is left changes nothing beneath. Fields the person changed and has not saved keep their values and stay unsaved when the database still holds what they held before the person changed them; a field someone else changed meanwhile (a move's effect, say) takes the database's value, and a notice names it: "<Field> was changed meanwhile and now shows the saved value; your entry was not kept." Every other attribute, the version, the id, the audit attributes and whatever a move set among them, takes the database's, so the next save is not refused as stale; a save forgets the changes it saved, so a later refresh does not put them back over the database. The page's form answers its rules again for the record as read (its state among them), and the values read are not taken for the person's typing. A record with unsaved edits that cannot be told apart safely is left as it is and only its controls redraw: one no record control watched from while it was unchanged, one loaded with lists or embedded values, or one whose data context holds other unsaved records. A record gone or no longer readable stays as shown, with a notice; a record that fails to read again is logged at WARN, and the controls redraw regardless. A child opened on its page returns to a parent page drawn afresh.

Extension records: fields on a user account​

An application adds its own fields to user accounts with one model file that says extends: user:

# src/main/jcm/model/UserProfile.yml
entity: UserProfile
extends: user
fields:
employeeNumber: {type: text, length: 20}
phone: {type: text, length: 30}

The entity is one row beside the account: ownerId (column OWNER_ID, required, unique index, no foreign key) holds the account's id, and jcmChangelog writes the table. Its form is jcm/extension-forms/UserProfile.yml, fixed when the application is built like the model and role files, with entity: and a form: holding the keys of a case-type form; a field may also say self-service: true. With no file the form shows every field. Rules on the form name no state, transition or fact. A user leaf means the person signed in (under substitution the one substituted), not the account's owner, and with no person, as in system work, it fails closed as on any form, so put it in an all behind a leaf that is false for what system work saves. They hold at every save as a case form's do, whatever saves the row, system work included: a read-only-when that is true refuses a change through the data manager with "The 'Employee number' field cannot be changed now", on the row's first save too.

entity: UserProfile
form:
- section: Contact
fields:
- phone: {self-service: true}

The fields are drawn below the account form by the shell's account-form slot (needs jcm-screen) and saved by the same save, in one transaction: one create form makes both. A row nobody typed into is not saved, so AccountProfile.profile(username, type) may be empty. It reads through the secure data manager, so grant the entity in role files like any other; attribute policies are not applied when data loads, so the row comes back with every attribute whatever view says. Removing an account removes its row.

A row changes only with the right to update the user entity, whatever saves it; without that right a person may change only the self-service attributes of their own row, removing a row counts as changing all it holds and is judged on the row as stored (a copy carrying changes is refused), and anything else fails with "Changing UserProfile needs the right to update accounts". System work passes. Today no screen offers self-service to such a person: the account view is read-only for them.

Refused: UserProfile.yml:2: extends 'task' is no record an entity can extend; the records are user; two extensions of one record; a field with the name of an attribute of the user (a user condition would read that one); parent: or children: on an extension; a field named ownerId or on column OWNER_ID; an extension form for an entity that does not say extends:, or naming a field the entity lacks. user is the only target today. The console's data dictionary lists the extension as extends user.

Shared records: one record many cases point at​

A shared record is a model entity of its own that several cases point at: a person's profile, say, kept once and neither a child of one case nor a numbered case. Three files make the flow, with no view code:

# src/main/jcm/model/PersonProfile.yml
entity: PersonProfile
instance-name: fullName
fields:
fullName: {type: text, length: 120, required: true}
birthDate: {type: date}
phone: {type: text, length: 30}
email: {type: text, length: 254}

# in src/main/jcm/model/Appeal.yml, under fields:
applicant: {type: reference, entity: PersonProfile}
# jcm/shared-forms/PersonProfile.yml
entity: PersonProfile
form: # the keys of a case-type form; left out, every field
- section: Person
fields: [fullName, birthDate]
- section: Contact
fields:
- phone
- email: {required-when: {attribute: phone, empty: true}}

# in jcm/case-types/case.appeal.yml, on the form
- applicant: {shared-record: true}

shared-record: true goes on a reference field of a listed form: a case's, a child's, an extension's or another shared record's. The field stays the combo box of Generated forms, and under it stand New person profile (#field-applicant-new) and Edit person profile (#field-applicant-edit), the words taken from the entity's caption. Each opens SharedRecordPanel (jcm_SharedRecordPanel, granted by CaseScreenUserRole) in the side panel: the generated form, with #sharedNotice above the fields. On a saved record the notice says that saving changes the record on every case that points at it, and how many records the person can see point at it, counted through their read rules and over the references that say shared-record; on a new one, that it will be shared.

  • Binding. The panel saves in a data context of its own, so the case is not saved. What goes back to the field is read afresh through the person's read rules, so a row they may not read is not bound. Save on a new record puts it in the field as an unsaved change of the case, which the case's own Save stores or Cancel drops; the new shared record stays either way. Save on an edit freshens the field's name and leaves the case unchanged. Cancel touches nothing.

  • A new record stored with the case. Where the role files narrow what the person reads of the shared entity (a rows on it other than all, as follows), a new record stored alone could be out of its maker's sight, and one read by follows always is. So the panel's Save on a new record then stores nothing: the record goes in the field as part of the unsaved changes of the record that refers to it, and that record's own save stores both in one transaction, the reference with the record it names, after which the person reads it by their rule. Nothing is written for it. Until then Edit opens that same unsaved record to correct it; once stored it is a record as any other, and Edit saves it at once. A save that is refused, by a field, by a rule or by the database, stores neither, and the next one stores each once; leaving the case unsaved stores neither. The read rule is not widened and nothing is created as system.

    • Only what is still referred to is stored. The save decides, not the form: at the save of a screen from which such a record was made, a new record of a shared entity the person's rows narrow is stored only where a record of that save refers to it, directly or through another such record (references inside embedded values count). One the field no longer holds (another was made or picked, the field was cleared by the form or by code, or the form was drawn again before the record came back to it) is left out, with any record made on its own form. Nothing is kept about which field made which record. Code of the application's own that puts a new record of such an entity in that screen's data context must have a record of the save refer to it.
    • A record made on the form of one that waits (the demo's person and its guardian) waits with it and is stored in the same save. Its maker reads it afterwards only where their rule reaches it: follows is one step, so a rule that follows the case's reference does not reach a record only the shared record refers to.
    • Where it holds, each proven on screen by SharedRecordFollowsUiTest: the case screen's form, for a new case and a saved one; a child's form, whose own Save stores the child with the record; a queue's create-case and add dialogs, whose button stores the new record with the records its fields made (a refused row keeps none, and the next press starts afresh); and a document's fields dialog, whose Save tried again after the database refused it stores the same records once.
    • A reference may name a new record only where the same save stores it: a copy that only claims to be new, or one the save also removes, is refused (You may not set Appeal.applicant to a record you cannot read).
    • Known limits. A record made and not yet stored is left out without a question when another is picked or the field is cleared, and until the save the screen still counts it as an unsaved change. What the person may not do with the new record (create it, set an attribute) is refused at the save of the record that refers to it, not in the panel. A reference field in a transition's dialog keeps the panel's own save, so there a new record read by follows is still stored out of its maker's sight and does not reach the field. Records the earlier behaviour left with nothing referring to them are not removed.
  • What is offered. New needs create on the entity and a field that may be changed. Edit needs update on the entity and on the row the field holds, in-memory and query row rules included, and is asked again when the value changes; a field locked by a rule or by the case's rights still offers Edit to someone with that right, since the record is not the case's. Someone who may read the entity but neither create nor update it gets the pick alone. The form follows Generated forms: an attribute the person may not view is not drawn, one they may not modify is read-only. A field whose stored value is a record an in-memory read rule hides loads empty with its identity erased, and Jmix puts that identity back over whatever the case holds before the save. So the field is locked, offers neither New nor a pick, and says This holds a record you may not see, so it cannot be changed here. (#field-<attribute>-hidden). A query rule erases nothing: the field shows the reference and the save holds it as below. Role files carry no row rules of either kind; an in-memory rule comes from a Java @RowLevelRole or a stored role's script policy.

  • What is enforced. SharedRecordGuard (jcm_SharedRecordGuard) runs on every save of an entity with a shared form, through any data manager, as an EntitySavingEvent listener ahead of the form rules, for a person (system work passes): a new record needs create and the in-memory row rules for create; a saved one needs update, a stored row the person may read, and the in-memory row rules for update, asked of the stored row whatever version the copy says, so a row that has gone is refused as a hidden one is and is not recreated; and every attribute that differs from the stored row (from a blank record on a new one) needs modify, the check RecordOperations.save makes. It refuses with SecurityException (You may not change PersonProfile.birthDate). A form default is filled after it, so a default is no change of the person's. The form's rules hold at every save as an extension form's do, and name no state, transition or fact, there being no case. On the record holding the reference, a reference marked shared-record may be changed only to a record the person may read (You may not set Appeal.applicant to a record you cannot read); one left alone may stay on a record they cannot read. That allowance is the rule of an application with no row rules; where they are in force see "References to records a person cannot open", Which rule applies when. One erased on load may not be pointed anywhere else (Appeal.applicant holds a record you may not read, so it cannot be changed), refused by a store listener ahead of Jmix's restore, the screen's lock being a courtesy. A copy with no mark of the erasure, as the record a save returns, is refused at the saving event, for a pick or a clear; on a marked copy a clear is no change, and Jmix puts the reference back. A shared record saved in the same SaveContext as the record that points at it, or that stops pointing at it, is asked by its stored row before the store writes either (jcm_SaveSetReads): the changes of both are stored in either order, and a record the person may not read is no pick though the same save would make it readable. A generated screen's save reads the record back through the person's read rules with its references loaded (SecuredReload), so erasure and the lock outlast the save and no name reaches the page, on a plain reference too; a record they may no longer read does not come back, and the screen keeps its own copy. Not covered: a save with the jmix.skipEntitySavingEvent hint, and removal, which stays with the entity's delete right and the database's foreign key. No screen offers removal.

  • The selection. Rows come through the secure data manager as for every generated reference field, so a row a rule hides is never offered. Each row shows AttributeAccess.nameOf: to someone who may not view the instance name's attribute, the entity's caption; and typing then narrows nothing, so no one can probe a hidden name.

  • Two people at once. A copy older than the stored row answers for update and the row rules, then is left to the save, which fails on its version with StaleRecord.MESSAGE; the panel stays open with the person's edits. The guard does not report such a copy's differences as a refused attribute. A copy ahead of the stored row raises no lock, so it answers for every attribute it differs on.

  • The cases that point at it. The shared form's file may list them under the form, one list per case type and reference:

    # in jcm/shared-forms/PersonProfile.yml
    cases:
    - case-type: case.appeal
    through: applicant # a to-one reference of the case's entity to this one
    columns: [case-number, caseTitle, receivedOn]
    sort: receivedOn desc # optional: a direct attribute of the case; else the case's id
    label: Appeals naming this person # optional: else the case type's plural label

    On a saved record, never a new one, the panel shows under the notice (#sharedCases) each list the person may see (#sharedCases-<n>, n from 1 in the order written): a heading with the count, a compact grid (#sharedCases-<n>-grid) of the first 20 cases in the list's order, 20 of 37 shown where there are more (#sharedCases-<n>-more), and None you can see. (#sharedCases-<n>-none) for none. Rows and the count are read through the person's secured data access, e.<through> = :record (SharedRecordCases, jcm_SharedRecordCases), so a case their entity rights or row rules hide is neither listed nor counted. The list is in its sort order only where the person may view that attribute, else in native database id order, so a hidden value's order is not told (UUID order is not creation order); where a read rule of theirs runs in memory, ids are read first a page at a time and the cases by id, so the first 20 are the first 20 they may read, and the count is the rule's too. Case numbers are read for the page in one query (CaseNumbers.numbersOf). A list shows only to a person who may read the case entity and view the through attribute, since the list itself would say who names the record; a column only where they may view its path; a reference through a record they may not read reads A record you cannot open, and a referenced record is named by AttributeAccess.nameOf. A column ending on a reference, including a nested path such as applicant.guardian, fetches that record’s instance-name fields. A double click opens the case on its screen, closing the panel, once the form holds no unsaved change (else Save or cancel this form before opening a case.). Refused at startup and in a next-start check, naming the file and line: cases that is not a list of mappings, an unknown key (case-type, through, columns, sort, label are the keys), 'case.nosuch' is not a case type, 'caseTitle' is no reference of Appeal to PersonProfile, so it cannot list the cases that point at it, no columns or more than six, a column twice, 'shoeSize' is neither case-number nor a single-valued attribute path of Appeal, 'sort' is a direct attribute of Appeal, optionally followed by asc or desc, not 'applicant desc', and the cases of case.appeal through 'applicant' are listed twice. Not built: child records that point at it, paging past the first 20, a sort by heading, filters, export, and the lists anywhere but the panel.

  • History. A change to a shared record is written to the entity log, and no screen shows it. Anyone asking what changed on a shared record, and who changed it, has to read the entity log directly.

Refused at startup, naming the file and line: a key other than entity, form and cases; a shared-forms/ file for an entity not in the model, a case type's entity ('Appeal' is a case type's entity; a shared record is neither a case nor a child), a child, an entity that says extends: or one with children:; an upload field on the form; any key or field a case form refuses; shared-record on an attribute that is no reference, on a reference to an entity with no file in shared-forms/ ('applicant' says shared-record, but PersonProfile has no file in shared-forms/), or with a value other than true or false. The kind is fixed at build, as its file puts the entity under the guard. A form with no listed fields cannot say shared-record. An entity's rights come from role files as for any other; JCM widens none.

Generated forms​

FormGenerator (jcm_FormGenerator) draws the case's Details form and every child form: build(MetaClass type, FormSpec.Form form, InstanceContainer<?> container, Set<String> leftOut) returns a GeneratedForm with component(), field(attribute) (field ids are field-<attribute>) and sections() (by title, in order). Without a form key, or with an empty one, the form has every attribute that may be on a form, in declaration order: persistent, single-valued, not id, version, audit or soft delete, not a composition (compositions are child types), and not the child's reference to its parent. A listed form shows exactly the listed fields, grouped in sections:

code: case.appeal
entity: Appeal
form:
- section: Filing
shown-when: {state: [RECEIVED]} # section rules: shown-when, required-when, read-only-when
fields:
- caseTitle
- filedOn: {default: today}
- status:
required-when: {attribute: filedOn, empty: false}
children:
- code: decisions
entity: Decision
parent: appeal
form: # a child type takes the same key
- section: Decision
fields: [outcome, decidedOn, summary]

A field is an attribute name, or attribute: {rules} with the rules shown-when, required-when, read-only-when, default, clear-when-hidden, filtered-by, options-where and parent-of (read as described under Form rules), and on a reference shared-record (Shared records) and display (Form rules). Any other key under a section or field, an unknown attribute, a path (status.code), an attribute listed twice, one that cannot be on a form, or a child's parent reference stops startup, naming the file and the line of the key at fault.

Each attribute gets the control its type implies: a text field (a text area for a lob or a length over 255), number, date, date-time, check box, select for an enum, the reference-list picker for a jcm_RefItem with @RefListCode, and a combo box for another entity that loads a page of records at a time through the secure data manager, narrowed by typed text when the instance name is one stored text attribute and ordered by it, otherwise by the primary key, so the pages of a scrolled list never overlap or skip a record. Required marks and validation come from the entity's annotations. A Boolean's check box treats unchecked as the value false, never as missing: a required Boolean (every model boolean, a @NotNull attribute, or one a rule requires) shows its required mark and its required message only while the attribute holds null, which is when the save refuses it too. A model boolean has its default and is never null; a hand-written Boolean left null is drawn unchecked with its required mark, and a screen reader hears a required check box, not checked. A tick says yes; to say no the person ticks the box and clears it again, which stores false and takes the mark away. Another record drawn in the form leaves a null it holds null, and a check box on a form put in a dialog after the person changed something there counts as typed only once the person changes it. A Boolean that must be true (a consent) needs a check of its own (Validation rules). The same holds on a hand-written screen: a <checkbox> in a screen descriptor, and any check box made by the UI factory, is this check box, so a required Boolean is saved as false there too (a letter template is switched off by clearing In use). A child form's form rules name the case's states and transitions, or, when the child type has a workflow of its own, that workflow's (see Form rules). An attribute the user may not view is not drawn, nor is a reference to an entity the user may not read; an attribute the user may not change is read-only, and so is every field of a saved record the user may not update (of a new record, when the user may not create one). A section with nothing the user may see is not drawn. Two sections may not share a title.

Form rules​

A new record's form opens with nothing marked wrong: a required field still empty shows its required marker, and says it is missing when the person saves (or leaves the field), never before they have touched anything. In an upload field each chosen file's name is shown whole, wrapped where it is longer than the field, with the whole name as its title; a child record's outcomes, actions and queue buttons wrap within its band; and the case screen's tab bar sticks over the page in the page's own colour, so what scrolls under it does not show through.

Rules on a section or a field of a listed form, declared once and read on the server:

code: case.appeal
entity: Appeal
form:
- section: Appeal
fields:
- caseTitle
- filedOn: {default: today}
- status
- program
- issue: {filtered-by: program}
- receivedBy: {default: current-user}
- withdrawalReason:
shown-when:
any:
- {attribute: status.code, in: [WITHDRAWN, CLOSED]}
- {transition: [withdraw]}
required-when: {transition: [withdraw]}
clear-when-hidden: true
- section: Review
shown-when: {mode: edit}
fields:
- startDate: {read-only-when: {not: {state: [RECEIVED, IN_REVIEW]}}}
  • shown-when, required-when, read-only-when take a condition in the validation rules' vocabulary (see Validation rules: attribute, state, transition, role, mode, fact, all, any, not; a bare list means all). A section's rule applies to every field in it: a field is shown when its section and itself say so, and required or read-only when either does. For a child type's form the state and transition conditions are the case type's: its workflow, answered for the case the child belongs to, and its fields are checked for the case's moves; fact names a fact of the child's own class, which runs on the child record, or a fact of its case, which runs on the case (see Validation rules: Facts). A child type whose binding has a workflow of its own (see Workflow) is answered in that workflow instead, on the record itself: state and transition name the child's states and transitions (a case state is refused at startup like any unknown state), fact names the child's own facts alone (a case's fact is refused, as it is in a rule or a workflow file of the child's binding), its fields are checked when the child's own move enters a state and in saves inside that move, never for its case's moves, and its transition fields are those its own transitions ask for (on the child's page and panel, and in a queue's row-transition dialog). The child types below it still name their case's moves.

  • Values as written: condition values and default are taken as written in the file (see Configuration layout), so NO, ON, 007 and 1.50 stay text, as in a rules file, and are compared by the attribute's kind. Leaving a rule key out is fine; a condition key written with nothing after it (shown-when:) is refused, never read as always.

  • default: today, now, current-user, or the value itself, as written, for a new record. It must suit the attribute, or startup stops: today and now a date or time, current-user a text (the username) or a reference to the user entity, a written value one the attribute's type parses (an enumeration's id, a reference list's item code); no written value for another reference.

  • clear-when-hidden: true or false.

  • filtered-by: another field of the same entity whose value narrows this field's options. The field it is on must be a reference, and not the field named. On a child record's form the other field may be one of a record above it, named by the path through its parents (field: appeal.program on a party, party.appeal.program on a contact); every form below reads it so (see A field above the record, below). It has three forms: a reference list whose items each name one parent, an entity whose records each hold the value they belong under, and options shared by several values through membership rows. Startup stops, naming the key, when the two do not line up:

    • On a reference list field, the other field's name alone (issue: {filtered-by: program}): the options are the items whose parent is the other field's item. The other field must be a reference list field, and this field's list must name that list as its parent list (see Reference data); match is refused here.

    • On a reference to another entity, {field, match} (office: {filtered-by: {field: agency, match: agency}}): the options are the records whose attribute match equals the form's field field. The option entity must have that attribute, and the two must be able to hold the same value (the same type, or one a subtype of the other; two reference list fields of the same list). A field name alone is refused here.

    • For options shared by several values (an option X that belongs under A and under B), on a reference list field or on a reference to another entity alike, {field, through, match, option}: the options are the items or records that a row of the membership entity through links to the other field's value. match is the row's attribute that must equal the form's field field, as above but read from the row, and option is the row's attribute that holds the option. The field keeps the option itself (the one item X, whichever value it was chosen under), never a copy of it per value and never the row. With a model of an intake whose category and topic are reference list fields:

      # src/main/jcm/model/CategoryTopic.yml: one row for each topic a category has
      entity: CategoryTopic
      fields:
      category: {type: ref, list: ref.intake-category, required: true}
      topic: {type: ref, list: ref.intake-topic, required: true}
      # the intake's case-type file
      form:
      - section: Intake
      fields:
      - category
      - topic: {filtered-by: {field: category, through: CategoryTopic, match: category, option: topic}}

      The membership entity is the application's own (a model entity or a hand-written one), and so are its rows: a seed file, an import or a screen of the application writes them, and a unique constraint over the two columns is the application's to add. Startup stops, naming the key, unless all three of through, match and option are given, through is a stored entity in the same data store as the options, match is a stored attribute of it that can hold the other field's value (the same test as for an entity above), and option is a different stored attribute of it, a single reference to what this field holds (the same entity, a subtype or a supertype of it; for a reference list field, not an item of another list). Where a row's attributes are reference list fields themselves, the reference data check holds them to their lists and to items active on the day a row is written. What follows applies as for the other two forms, with these differences:

      • The rows are read as stored, with system access, on the screen and on save alike, by the ids the record holds, so the two always agree, a row built in memory is no membership, and a person needs no right to the membership entity. The options themselves are loaded with the person's own access: a reference list field offers its list's items active today among the members, and a reference to an entity offers the member records the person may read, so an option hidden from the person by a row rule is never offered even though a row lists it.
      • On the screen, changing the other field's value keeps a value that is also a member of the new one and clears one that is not.
      • On save, the pair is judged when the save sets it: on a new record, and on a stored one whose option or whose other field's value the save changes. The refusal is the same sentence and ruleCode.
      • An option taken out of a value's options later (its row deleted) stays on the records that hold it: the screen shows it as stored and does not offer it, and a save that leaves both the option and the other field's value as stored is not judged again, so the record saves its other changes. Once either is changed the pair is judged as any new choice, so the option cannot be chosen again and the other field cannot be moved under it. An item ended with valid-to is shown as retired and kept the same way (Reference data).
      • An option the person may not read: where a row rule hides the record the field holds, the field is locked on the screen (Row rules) and a save that leaves the other field's value alone keeps the pair as any other. A save that changes the other field's value from such a copy is refused, whether or not the hidden record is one of the new value's options, with The 'Category' field cannot be changed while the 'Topic' field holds a record you cannot open (ruleCode form.<Entity>.<attribute>.filtered-by.hidden, beside the other field), so the answer never tells which options the hidden record belongs under. Someone who reads the record makes the change.
      • Tenants: the rows are read with system access, as a save's other stored reads are, and this form was not run with the tenant starter on. Until it is, do not rely on it to keep one tenant's membership rows from counting for another's records: keep a membership entity's rows the same for every tenant, or leave the form out of a multi-tenant application.
      • The rows are read when the save is made, not when the record was opened: an option whose row was deleted while a screen was open is refused at that screen's save. A row deleted by a transaction that commits after the save's check leaves a record as in the previous point. Not seen, as for the reference data check: a membership row written in the same save as the record and not yet stored (save the rows first), direct SQL, and a save with the jmix.skipEntitySavingEvent hint.
    • On the screen, the field offers only the options that match the other field's value as edited. While that value is empty it offers nothing, is disabled and says so (Choose the Program first). When the user changes that value, a value of this field that no longer matches is cleared, unless a lock holds the field (permission, record, read-only-when); a record opened with a value that does not match keeps it on screen until saved, and a value of the other field that cannot be read changes nothing (logged). The other field's value is the one the user sees: a reference erased because a row-level rule hides its row counts as empty here (nothing offered, the hint shown), so the options never tell which row is hidden; conditions and the save still read it as stored.

    • On save, from every caller, a value the record holds outside the options the other field's value allows, whether the field is shown or hidden, refuses the save with The 'Issue' field is not one of the choices for the 'Program' given (ruleCode form.<Entity>.<attribute>.filtered-by), beside the field on the screens. An empty value is allowed; a value while the other field is empty is not. The option's matching attribute is read from the stored option, by the id the record holds (a parent changed on an item in memory changes nothing), and the other field's value as saved. The check holds whatever locks the field, so the other field cannot be moved away from a locked value.

    • A field above the record (office: {filtered-by: {field: appeal.program, through: test_CategoryDesk, match: category, option: desk}}): each step but the last must be the record's parent reference (its parent holds the record as a composition); any other step is refused at the key ("'agency.code' reaches past the record through 'agency', which is not its parent; filtered-by reads a field of the record, or of a record above it through its parents"), and so is a path naming no attribute. The other field is never edited on this form, so the options stand still while it is open. On the screen the value above is read as the person may read it: where they may not view a step or the field (Party.appeal, Appeal.program) or may not read a parent's row on the way (each asked of their own access by id), it is empty here, the field offers nothing and is disabled with "Nothing to choose until the Appeal's 'Program' is given". On save, from every caller, the value above is read from the stored parent, as the other forms read the other field as saved, and a value outside its options is refused with The 'Office' field is not one of the choices for the Appeal's 'Program' given (form.<Entity>.<attribute>.filtered-by). A save that leaves the record's value as stored is not judged again when the field above moved since (the parent is changed by its own saves), so the record keeps saving its other changes until its value is changed or it is moved under another parent, when it is judged again. Moving it under another parent while the saver's copy has a shared option erased (a row rule hides it) is refused as for the other field's value: "The 'Appeal' field cannot be changed while the 'Office' field holds a record you cannot open" (...filtered-by.hidden, beside the parent reference). A person who sets or changes the value while they may not view the field above is refused whatever the value, with The 'Office' field cannot be chosen by someone who may not view the Appeal's 'Program' (form.<Entity>.<attribute>.filtered-by.unseen), so a refusal never tells what the parent holds; system work and someone who may view it are judged as above. Proved with the membership form by ParentFilteredByTest, ParentFilteredByUiTest and FormRulesTest.

  • options-where: on a reference to another entity (not a reference list), a condition asked of each record the field may hold, so the picker offers, and every save accepts, only the records it holds for:

    - appeal:
    options-where:
    all:
    - {not: {state: [CLOSED, WITHDRAWN]}}
    - {attribute: kind, equals: STANDARD}
    - {not: {exists: {child: rehearings}}}
    • What it asks: the vocabulary of a queue's where (Queues: where), asked in the database over the target entity: attribute with equals, in, empty, compare and the text operators, through to-one references; state, the option's own workflow state (the target is a case type, or a child type with a workflow of its own); exists and count over a child type declared directly under the target, nested for the types below; all, any, not; a map, a list (all) or a text in the filter language (kind = 'STANDARD'). It asks of the option, never of the record being edited (that is filtered-by) nor of the person.
    • Refused at startup (and by a publish's check of the next start, against its workflows), at the rule's line: on a field that is not a single reference to another entity, or is a reference list ('options-where' narrows the records of a reference to another entity; 'status' is not one); transition, role, mode, fact, user or a module's leaf ('options-where' asks only of each record offered (its fields, its state and its child records); 'transition' is not one of those); state on a target with no workflow of its own ('state' asks of the offered record's own workflow; Office has none); an unknown state, attribute or child type, and anything a query cannot ask, with the sentences of a queue's where. Every form of one entity asks the same condition of a field, as one save check holds for all of them: two forms (a case type's, a child type's, a shared or extension form) that give one field different conditions are refused (another form of Pick gives 'matter' a different options-where (<file>:<line>); ...); the same condition in both is one. These refusals come with the other form rules', at startup and on a publish's check.
    • On the screen the picker's query adds the condition beside filtered-by, a hook's options and the typed text, through the person's secured data manager, so their own rules narrow it further; a stored value that no longer meets it is shown as stored.
    • On save, from every caller (a screen, the API, the import, a workflow set, system work), a value is judged when the save sets it: on a new record, and on a stored one whose value the save changes. The condition is read as system on the stored option, by the id the record holds; a value outside it refuses the save with The 'Appeal' field is not one of the choices offered (ruleCode form.<Entity>.<attribute>.options-where), and one that cannot be answered with The 'Appeal' field could not be checked, so nothing was saved (...options-where.failed). An empty value is allowed. A value left as stored is not judged again, so a record whose option has moved on (closed, say) still saves its other changes. Not seen: direct SQL and a save with the jmix.skipEntitySavingEvent hint.
    • Disclosure: the condition is answered as system, so it is asked only for a person who could read all it reads: every attribute path it names viewable to them (each step), no entity on a path through a reference narrowed for them by row rules, and every child type under exists or count readable to them and not narrowed by row rules (a row kept from them would be counted), its own where held to the same. For anyone else the picker offers nothing, is locked and says The choices for this field depend on values you may not see, and a save of theirs that sets the field is refused with This check needs a value you may not see; ask someone who can see it to make this change. (...options-where.unseen) whatever the value, so neither tells what the condition would have answered. Clearing the field is always allowed, to them too: an empty value asks nothing. System work, jobs and imports are judged on the condition alone.
  • display: on a reference to another entity (not a reference list), the target's own fields that label each record in the picker, in order: occurrence: {display: [occurredOn, stage]} reads "Mar 4, 2026 · HEARD" where several occurrences share an instance name. A list rather than a format string, so that every part is a field checked at startup and asked for permission on its own. Each part is a stored attribute of the target holding one value (text, number, date, time, flag, enumeration), not its id, its version or a reference; startup refuses anything else, an unknown or repeated field and an empty list, at the rule's line. Nothing is stored and no id is shown.

    • Each part is shown only to a person who may view it, as a column is; the label joins the parts they may view that hold a value with " · ", each formatted as the grid formats it, and with none it is the record's instance name as any picker shows it. The same label stands in the list and on the chosen value; a chosen record loaded without those fields is read again with the person's access, and one they may not read shows by its name alone.
    • Typing matches the text parts they may view (with none, typing finds nothing); the list is ordered by the first part they may view, then by the primary key, so its pages never overlap. filtered-by and a hidden reference's lock work as on any reference picker.
  • copy-earlier: on a stored reference of a child type's form (another entity or a reference list item), the fields of the same form that an earlier record of the child type holding the same value fills on a new record: organization: {copy-earlier: [name, email, phone]}. Startup and a publish refuse at the rule's line: the rule on a case type's, an extension's or a shared record's form ('copy-earlier' stands on a child type's form, ...), on a field that is not a stored single reference, an empty list or one that is not a list, a name not on this form, the record's parent, a field holding several records or child records, the field itself, and a name written twice.

    • On the screen, on a new record's form only, while the field is drawn, editable and holds a value: below it a picker Copy from an earlier <entity caption> (id copyEarlier-<attribute>) of at most 20 earlier records, each by its instance name where the person may view every field of it and by the entity's caption where not, newest first where the entity has a @CreatedDate attribute, else by a single stored instance-name attribute, then the primary key. It is hidden while there are none. Changing the field reloads it and clears the pick. A saved record's form shows no picker.
    • A pick fills each listed field the form draws and the person may change now (not read-only by their rights or a rule) with the earlier record's value, where they may view that attribute and the value is not empty; it fills over what was typed. Other fields keep the form's values. Nothing links the records and nothing is stored until the person saves, which is judged as any other save.
    • Access: the earlier records are rows of the child type (the parent attribute set) read through the secure data manager with the person's entity, attribute and row rules, and each row's way up to its case is then read as the case tree reads it, with the person's access: a row whose parent or case they may not read is not offered, also for a child type that is no composition of its case. The 20 are counted after that: rows are read 60 at a time, at most ten pages, until 20 pass. A reference the person may not read is empty on the row as loaded and is not copied; an attribute they may not view is never copied.
    • Cost: each time the field changes, one query a page, and for each page one secured read per level of the parents not read yet (CaseTree.readablePaths), so a parent many rows share is read once.
    • Not built: a picker on a saved record or a case type's form, keyed on a text field or several fields, a choice of fields at pick time, and a record of which earlier record was copied.
  • parent-of: the field always holds the parent of another field's reference list item, and is never chosen (program: {parent-of: issue}, where the items of the issue's list name their parents in the program's list). The other field is the one the person picks; this one shows what it belongs under:

    form:
    - section: Referral
    fields:
    - issue # ref.appeal-program-issue, whose parent list is ref.appeal-program
    - program: {parent-of: issue} # ref.appeal-program

    Startup stops, naming the key, unless the other field is a reference list field of the same entity whose list names a parent list, and this field is a reference list field of that parent list. It is also refused on a field with default, filtered-by or clear-when-hidden: true (the other field decides its value), when the other field is itself parent-of a field (a field follows a field the person chooses), and when the other field is filtered-by this one (its options would wait for a value only it can give).

    • On the screen the field is always read-only, whatever the permissions say. On a new record it shows the parent of the item chosen as soon as the item is chosen or changed, and empties when the item is cleared. A stored record opens showing what is stored, and follows the item once the person changes it. What the screen reads is read under the person's own rules: the chosen item is loaded by its id with their access, its parent reference as that load gives it, and the parent loaded by its id with their access; where either load gives nothing the field is left empty (the save fills it), so the form holds no id or name of a parent kept from them. An item erased from the person's copy (a row rule) or one that cannot be read changes nothing. Nothing else is read for this field on the screen, with system access or otherwise.
    • Items kept from a person. Role files may not write rows on jcm_RefItem (Row rules), so an item is hidden only by a hand-written row-level role, and such a rule is applied to a query for items, not through a reference: a person's load of the record shows its stored program, as it shows any reference-list value. parent-of adds nothing to that: the instance a person's save hands back holds what their next load of it would.
    • Known limit. A parent hidden from a person only by a Java row role is shown to them on any load of a saved record, as every reference to reference data is.
    • On save, from every caller (a screen, the API, the import, a workflow set, a queue's copy, system work), before any other form rule, the field is set to the parent of the item the record holds, read as stored by the item's id (a parent changed on an item in memory changes nothing), whatever value the caller gave: a different program is replaced, not refused, since it is never the caller's to give, so an import column or an API value for it is ignored. An empty item empties the field. A stored copy that loaded neither field is left alone. A stored copy that did not load this field cannot have it written, so a save from it that changes the item is refused with The 'Issue' field is changed only together with the 'Program' field, which follows it (ruleCode form.<Entity>.<attribute>.parent-of.unloaded, beside the other field); load both. A parent that cannot be read refuses the save (form.<Entity>.<attribute>.parent-of). Not seen, as for every form rule: direct SQL and a save with the jmix.skipEntitySavingEvent hint.
    • Whose access the save uses. The item, its parent and the field's stored value are read as stored, without the saver's rules, as a save's other stored reads are: a person who may not read the item their copy holds (or its parent) still has the parent stored, and the refusals above name the two fields' captions, never an item.
    • Until the next save. The field is stored, so listings, queue filters, searches and reports read it as stored. Where it can disagree with the item: an item moved under another parent in the reference data, a row written by direct SQL or with the hint above, or records stored before the rule was added. Each is put right by the record's next save that loads the field (the parent is set again, whatever was stored); until then a listing or filter on the field gives the stored value, not the item's present parent.
  • FormRuleChecks (jcm_FormRuleChecks) reads every form's rules when the application is ready (or at the first save that asks, if earlier) into FormRules (sections, and FieldRules by attribute with the section's rules folded in) and keeps them by entity (rulesFor(entityName)). An unknown attribute, state, transition, job role or fact, a value that cannot match, or a rule of the wrong shape stops startup naming the file and the line of the rule. What the rules do on save is under "On save" below.

  • On the screen (LiveRules, kept on every generated form: the case form, a child's panel and page): the rules are answered on the server against the record in the form, as edited, and answered again when the form gets another record, when an attribute a condition reads changes, and after a save (a new record becomes edited, so mode changes). The state is the case's workflow state, the job role the session's, the facts the case's; a child form reaches its case through its parents. Values are read through RecordReaders.asEdited (jcm_RecordReaders, jcm-core, the reader every engine shares): the record and the references it loaded as they are in memory; a reference the form did not load, or one erased from the loaded record because a row-level rule hides the row it names, is read from the stored record on the server with system access; a path through an empty reference is empty, never an error. A value the user may not view is read only to answer the rule and is never sent to the browser: what the screen shows of it is the rule's outcome, so a field the save will require is marked required on the screen even when the user cannot see the status that requires it. Within one round of answers the stored rows are read once and each fact is asked once (RuleContexts, below).

    • A hidden field (shown-when not holding) is not drawn on the page, nor in the Details summary; a section is hidden while none of its fields is shown. A hidden field is never required by a rule, and the save does not check it.
    • Required: the entity's own mark (@NotNull and the like) always stands; required-when adds to it while it holds and the field is shown. A required field that is empty is marked wrong only once the user saves or continues (or empties it), not as soon as a rule makes it required or a dialog opens: the browser is told the field is not wrong once, when a rule starts requiring it (and again for another record), never while the rule goes on holding, and never for a field the server has marked wrong.
    • Read-only comes from every source at once: the attribute's permission, the entity's create (new record) or update permission, and read-only-when. Any one locks the field; answering a rule again never unlocks a field another source locks.
    • default fills a new record once, when the form gets it, into fields the user sees and may change that are still empty. A saved record is never filled.
    • clear-when-hidden empties the field, on the record, when a value the user changed hides it while no source locks it (permission or read-only-when); a field hidden from the start, or hidden because a save made the record no longer new, keeps its value. Clearing on save is the save's.
    • A rule that cannot be answered (a fact that fails, a stored value that cannot be read) fails closed: the field is locked and required, keeps its visibility, is never cleared, and the failure is logged.
  • In a transition's dialog: the fields whose rules name a transition ({transition: [withdraw]} in any of the three) are asked for in its dialog, above the comment, with the rules answered as during that transition: shown and required as they say, the state the one the transition enters. A transition with such fields opens the dialog even when it needs no comment, and is refused while the form has unsaved edits. The values are entered on a fresh copy of the case read with the user's access; Confirm hands the copy's save to the engine as the move's beforeMove (WorkflowService.transition(binding, record, code, comment, beforeMove)), so it is saved inside the move, in its transaction and its TransitionScope, and a refused move saves nothing. A refusal is shown in its own words (a broken rule's message rather than the engine's sentence around it; a workflow refusal as written; a record someone else changed meanwhile as such); any other failure gets a general sentence, its cause logged. Exceptions whose message is for the user implement com.jcm.core.PlainMessage (WorkflowException, RuleViolationException). On the form itself, outside the dialog, no transition is being taken.

  • On save (FormRuleEnforcement, jcm_FormRuleEnforcement, built like jcm-validation's RuleEnforcement): the rules hold for every save of a case or child record at any depth, whoever saves: a screen, system work, a scheduled job, the import, a service, REST, the secured or the unconstrained data manager. A broken rule refuses the save with RuleViolationException (a PlainMessage; one RuleViolation per field, ruleCode form.<Entity>.<attribute>.<rule>), its messages the ones the form shows beside the field (The 'Withdrawal reason' field is required). The generated screens answer the same rules as part of their validation, so the message stands beside its field before the save is tried; the import reports it on the row; a refusal that reaches a screen another way is shown as an error notification. Only records of an entity with form rules are looked at, and the stored row is read once per save, without the user's constraints: a user's attribute permissions do not change a rule's answer.

    • default: a new record's empty attributes are filled on the server, whatever the caller and whether or not the user could see the field (current-user is the user saving; under system authentication, the system user). A saved record is never filled.
    • required-when: an empty value while it holds refuses the save. A field hidden by shown-when (answered for the record as saved) is never required.
    • In a move (com.jcm.workflow.TransitionScope): the workflow engine, once a transition's own checks (state, role, comment) have passed, opens the scope for that record and transition around the save a caller supplies before the move (transition(..., beforeMove)), the transition's effects and actions and the transitioned event, and closes it when the move ends however it ends. A save of the moved record made inside it is a save made during the transition: a transition condition holds, and shown-when and required-when read the state being entered. Until the state is entered, though, such a save (the caller's, an effect's, an action's), and one of a child record whose rules name this move, leaves to the entering every field whose shown-when or required-when names a transition or a state, for a transition alone as for one of several of a name: the save neither requires nor clears it, so a list of actions may fill it in any order. The transitioned event's listeners after the entering and the moves it sets off save with these rules asked as usual. Only the engine can open a scope (TransitionScope.open and Move's constructor are package-private; current() is public), so a plain save never holds a transition condition, a value a transition asks for survives only when saved inside its move, and a save of another record inside a move is a plain save. This is how the dialog saves its values and how a job moves a record together with what its transition asks for.
    • Entering a state (WorkflowTransitionedEvent, at @Order(-100) before other listeners, a start included): the fields shown or required by a transition or a state are answered once on the stored record, with the transition taken and the state entered, so required-when: {state: [CLOSED]} refuses the move into CLOSED while the field is empty, with the form's message, and the refused move writes nothing else. The case's child records at any depth are checked the same way, each type's rows loaded once with system access together with what their rules read: a decision's summary: {required-when: {state: [CLOSED]}} refuses closing the appeal while a decision has no summary.
    • read-only-when: answered for the stored record and, inside a move, with the stored current state, never the one being entered: a field locked in the state the record is leaving stays locked for the move's own saves, and one locked only in the state entered is still free until the move is made. A save that changes the attribute while the lock holds is refused (The 'Review started' field cannot be changed now). A new record has no stored row: the condition is answered for the new record itself, so {mode: create} holds and {mode: edit} does not, as on the screen. The saved value and the stored one are compared as values (a number by value, so 1.0 is 1.00; a moment by instant, so a date is its timestamp; a reference by id), never by class or scale. A locked new field with a default takes the server's default whatever the caller gave (so default: now under a lock creates fine from the screen and from a job); one without a default refuses a value.
    • clear-when-hidden: a hidden field is cleared on the server by every save, from any caller, unless read-only-when locks it. So a field shown-when: {mode: create} with clear-when-hidden keeps its value only until the record is next saved, and a value entered for a transition's dialog is kept only when saved inside that move. The one exception is the save inside a move, above: a field whose shown-when or required-when names a transition or a state keeps its value through the move, and the first save after it entered its state clears the field if it is hidden. The entering refuses or passes; it clears nothing.
    • Reading through a reference (status.code): RecordReaders.asSaved (jcm_RecordReaders, jcm-core), the one reader the form rules, the validation rules and the screen share. The record's own attributes are read from the copy being saved where loaded, else from the stored row, loaded once with every path the rules read. Past the first segment, the referenced record is read from the database by the id the record holds, with system access, unless the same save holds a record of that type and id (SaveContext, tracked by jcm_SavingSet, a store listener registered on every store), when the save's own copy is read, whichever instance the reference holds: a rule sees the value the save is giving that record, and never the values of an in-memory item that merely carries its id, for a form rule and for a validation rule alike. A record a copy's fetch plan left out cannot be set on it at all (Jmix refuses the setter), so no change slips in that way. A save that fails leaves at most one record of the save on its thread, dropped by the next save there. Stored rows are read by a value query (StoredRows), so reading a row the same save has already written drops none of its changes (see "Loads while a save is being written").
    • A SaveContext holding a parent and a child is checked record by record, the child reading its new parent as saved alongside. A new child reached only through a composition the save does not list fails the whole save (the store refuses the unlisted record), so nothing is saved unchecked.
    • The context is the case's, built by RuleContexts (jcm_RuleContexts, jcm-workflow, shared with the validation rules and the screen): a child reaches its case through its parents (read without constraints); the state is read only when a rule asks for it, once per check; each fact is asked once per check however many fields name it; the job role is the session's, so a system job works as no job role and a role condition is false then. A role condition is enforced like any other condition, but it is not a permission: access itself comes from roles' data permissions. A child whose case cannot be reached has no state and no facts: a state condition is false, and a fact cannot be answered.
    • Fail closed: a rule that cannot be answered (a fact that fails, a stored row that cannot be read) refuses the save with The '<field>' field could not be checked, so nothing was saved, a default that cannot be made with The '<field>' field could not be filled in, so nothing was saved, and the cause is logged. A path through an empty reference is empty, never a failure.
    • The entity's own annotations (@NotNull, nullable = false) are its own contract and stand whatever a rule hides: Jmix does not run bean validation in DataManager.save, so a required attribute a rule hides is refused by the database, with no plain message, unless the caller or a default gives it. Do not hide an attribute the entity requires without a default.
    • Not covered, as for save rules: saves with the jmix.skipEntitySavingEvent hint.
  • Field hooks (framework/legacy only, not exported): checked applications use form rules, RecordLifecycle for persisted derivations, RecordValidator for save checks, and CaseScreenSection for UI. There is no exported dynamic field-options SPI; a declared condition on the options is options-where (Form rules). In framework implementation, a Spring bean implementing com.jcm.screen.CaseFieldHook names a case type (caseType()), a child type's code for a child form (childType(), any depth; null for the case form) and an attribute (attribute()). Its three methods are optional (defaults do nothing):

    • onChange(record, changedAttribute): on the screen, after the user changes any field of the form (the case form, a child's panel or page, a transition's dialog), the hook may set values on the record: deriving a supervisor and a team from the assessor. The rules are answered for the user's change first, so a lock that change brings already holds; the hook is given a deep copy of the record (its references and collection members are copies too, so what it changes inside them reaches no record and is never saved), and each of the record's own single-valued attributes it changed (a reference compared by id) is written to the record only where the user may change it now (the attribute's permission, the record's create or update permission, read-only-when, a field locked by a failing hook); elsewhere the change is left out and logged. A reference pointed at another record is written as that record loaded by its id with the user's own access and merged into the screen's data context, never the instance the hook handed over (an edit the hook made on it is lost); a record the user cannot read, or that is not stored, refuses the hook as below. Then the rules are answered again. A hook that changes a collection (in place or by replacing it; members compared by id), or sets an attribute the record did not load, has nothing applied, its field locked with the hint below, and a warning logged; an unloaded attribute stays unloaded. Screen only: no other caller runs it, so a derived value is checked on save like any other, and attribute permissions on save are the store's and the roles', not the hook's.
    • options(record): the values the field may hold (null for no narrowing, empty for none; records compared by id). On the screen a reference-list or entity field offers only those, together with filtered-by (only options both allow), answered again as the record changes; a stored value stays visible. Every save, from any caller, refuses a value outside them: The 'Issue' field is not one of the choices offered (ruleCode hook.<Entity>.<attribute>.options). The screen takes at most 1,000 options, the bound of a query's list on every database: more lock the field as a failing options does.
    • validate(record): plain messages; each refuses every save, from any caller, as a RuleViolation on the attribute (hook.<Entity>.<attribute>.validate), so the screens show it beside the field before the save is tried and the import reports it on the row, as for form rules.
    • Fail closed: a hook that throws on save refuses it with The '<field>' field could not be checked, so nothing was saved (hook.<Entity>.<attribute>.failed) and logs the cause. On the screen, an onChange that throws has nothing it wrote applied (it worked on a copy), and an options that throws leaves the field as it was; either locks the field with the hint "This field could not be checked, so it cannot be changed now" until the hook answers again.
    • The record a hook is given (on save and on the screen) is the record as saved or edited, with every single-valued attribute the caller's copy did not load read from the stored row with system access, on a deep copy that keeps the record's new or saved state, so the answer does not depend on the caller's fetch plan and nothing saved changes; the value checked against options is the copy's. A collection the copy did not load is not read for it. A row that cannot be read is a failure, so the save is refused.
    • An unknown case type, child type or attribute, or two hooks on one field, stops startup naming the beans (CaseOverrides).

Case workspace: children, header and layout​

jcm-workspace (with jcm-ui) lays out the case page from the case-type file. The sample's case.appeal.yml declares, among its other keys:

code: case.appeal
entity: Appeal
header:
title: "${record.caseTitle}" # placeholders ${record.<path>}; parts the user may not view are left out
fields: [filedOn, status] # shown under the title, each only to users who may view it
children: # records of the case; each a composition (children: in the parent's model file)
- code: parties # stable, unique within the case type
entity: Party
parent: appeal # the child's reference to its parent
label: Parties # default: the composition's caption
columns: [name] # default: the first fields the user may view
children: # grandchildren, shown on their parent's panel or page
- {code: contacts, entity: PartyContact, parent: party, label: Contacts, columns: [kind, value]}
- code: decisions
entity: Decision
parent: appeal
label: Decisions
columns: [outcome, decidedOn]
sort: decidedOn desc
open: page # panel (default: beside the case) or page (under the case header)
workspace:
overview: # cards on the first tab
- deadlines # a JCM control by name
- {children: decisions, show: 3} # the latest few, with View all
tabs: # one tab each; default: a tab per top-level child type
- {children: parties}
- {children: decisions}

Grouped tabs and More. workspace.tabs also accepts {name: Work, children: [requests, reviews]}. Each readable child has its own section, heading, count, New and Download CSV actions; the tab count is the sum of the readable children's existing counts. An unreadable child is neither rendered nor counted, and a group with no readable children is omitted. A child may belong to only one tab; groups require a nonblank unique name and a nonempty list of distinct top-level child codes. Unknown children, grandchildren and invalid boolean settings are refused at their file and line.

workspace.show-empty defaults to false. A child tab with a known zero count moves to the trailing More menu; show-empty: true keeps it inline. A single child tab or group may override that default with its own show-empty. An unknown or failed count is never treated as zero. Tabs that exceed the available width also move into More, preserving declaration order, existing panels and edits. More announces how many tabs it contains, not how many records. Arrow keys navigate its menu, Enter/Space selects, and Escape closes it and restores focus. The selected tab remains selected across reflow or count changes. showTab(childCode), overview View all and a ?tab=<childCode> address select the child's containing group even when folded. Grouping and folding reuse the child lists' counts and introduce no count query for deciding overflow.

Header fields through a reference. A header field and a title placeholder are each a path: an attribute of the case (filedOn), or an attribute of a record the case refers to directly, one step through a single reference (applicant.phone, where applicant refers to a shared record; the attribute may itself be a reference, shown by its name). The demo's appeal shows its applicant's phone and email under the title:

header:
title: "${record.caseTitle}"
fields: [receivedOn, applicant.phone, applicant.email]
  • Who sees each part, the rule of the details summary, for each field and each placeholder alone: the person must read the case's entity and view the reference attribute, and read the referenced entity and view the field on it (AttributeAccess.canView, every step). Otherwise that field is left out of the header (no label, no value) and that placeholder out of the title; the rest stands. A reference holding a record the person's rows hide shows A record you cannot open for each of its fields and placeholders, never their values (a hidden reference is never shown as an empty one); a reference that is not set shows - (nothing in the title). The label is the field's own caption on the referenced entity ("Phone").
  • Cost. No query per field. The generated case screen loads every single reference of the case with its base fields in the case's own load, so its header reads them from memory (the queue's record panel loads the case by the same plan). Where the record in hand lacks a needed field, the header reads the referenced record again by id through the person's own data manager, once per reference attribute per drawing, with every field it needs of it; their rows decide, and a record they may no longer read is told as hidden. A child page is such a place: its case header gets the case from CaseTree.path with base fields only, so each drawing of the page costs one read per reference the header names. So is a hand-built case view whose plan left the field out.
  • Refused at startup and at publish (CaseLayoutParser), naming the file and line, in the fields and in the title alike: more than one step ('status.list.code' reaches through more than one reference; a header shows the case's own fields and the fields of a record the case refers to directly); a collection anywhere on the path ('parties.name' goes through parties, a list of Appeal's records, which has no single value to show in the header); an unknown attribute (Appeal has no attribute 'nosuch'; on the referenced record PersonProfile (Appeal.applicant) has no attribute 'phon'); a step after an attribute that is no reference ('filedOn.year' goes on from filedOn of Appeal, which is not a reference to another record). Design note: docs/design/header-reference-fields.md. Tests: CaseHeaderReferenceUiTest (demo: the case screen, the re-read, title placeholders), CaseLayoutTest and StudioStagedParityTest (sample); the queue's record panel and the child page are not covered by a test of their own.

Controls by name: stage-track, transition-bar, assignees, deadlines, tasks, timeline, attachments, letters, hearings, appointments, related-cases, possible-duplicates, case-reports; each once per workspace, with the id view XML conventionally gives it. Startup stops, naming the key, on an unknown key, entity, attribute or control; a parent that is not a composition of the parent entity through that attribute; an entity declared twice; a child type, at any depth, with nowhere to open its records (neither served by the case screen's generated child forms, when jcm-screen is installed, nor by a detail view of the app's own for its entity; WorkspaceControls.checkChildTypes); a show outside 1 to 50; or a child of a child placed on the workspace.

The generated case screen (below) lays this out with no view code. On a hand-built case screen of the app's own (level 3), put <jcm:caseWorkspace binding="case.appeal" dataContainer="appealDc"/> on the case's detail view, and give it a Save button (detail_save): a case takes children once saved. Child lists show only records and fields the user may see; New needs permission to create the child and to change the parent, and ChildOpener checks the same rule before it opens a new record (mayAdd(type, parent)); the server asks it again at the save, whichever screen or data manager saves the new child: a person's new record of a child type whose parent is a stored record they may not update, row rules included, is refused with You may not add a record under this record (ChildParentGuard), however the child's own create permission stands; system work, as a move's or a configured create, passes. A stored parent written by the same save as the child is asked by its stored row before the store writes either (jcm_SaveSetReads), so the parent's own changes are stored whichever of the two the save lists first. Each list has a CSV download. A child type opens on the app's own detail view for its entity when the app has one (<Entity>.detail or @PrimaryDetailView), and otherwise in the forms jcm-screen generates (see "Child records" below; the ChildForms interface in jcm-ui). A panel's address (?child=<code>&record=<id>) opens it again; ?tab=<code> shows a tab. Every detail view of a child type gets, with no code in it, a breadcrumb from the case, the case header when opened as a page, the path and transitions of its own workflow when its type has one (see Child records), and the lists of its own children (none for a child type the user may not read); a child page closes back to its parent (the case on the child's tab). A new child opened as a page is attached to the parent its address names (jcm-parent), when the user may read and change it and may create the child. CaseTree: parentOf, path, caseOf, walking the declared parents with the user's access.

Search refreshes keep row identity for records still in the current results. A delayed row click or Open button opens only a record in the latest permitted result set, using that result's current instance. An expired client row key or a result removed by filtering leaves the search open and says, "The search results have changed. Choose a result again." A current result remains available to open normally.

The search screen jcm_CaseSearch (route jcm/search, ?type= and ?q=; CaseSearchUserRole, jcm-case-search-user) and the quick-find box (CaseQuickFinds.create() in the main view header; Ctrl+K or ⌘K) find records of a case type, declared in its file. In the quick-find box, picking a match opens it and Enter hands the text to the search screen; either way the box empties, so its late lookup answer or focus leaving it cannot send the text again and jump back to the search over what the user did next. The keyword matches, in any case and anywhere in the text, the case number always, and the quick-find fields, or the text fields of the record's instance name when none are declared. A quick-find field is a text attribute of the record or a dotted path through single references to one (person.fullName, person.office.phone, or into an embedded value, address.city), checked at startup: a path through a collection, through an attribute that is not saved (a transient reference), through a reference to a record kept in another data store, or one that does not end in text, stops startup naming the file and line. An embedded value is part of the record and is looked in as it is. Each reference in a path is looked in by a subquery on the referenced record, so a record whose reference is empty still matches on its other fields; the referenced record's query row-level rules apply there, so a record the user may not read matches nothing by its fields, and a referenced record that is soft-deleted no longer matches. The field is not looked in when an in-memory rule or a rule with a join clause narrows a referenced record, or when the user may not view the reference or the field. A correction or a clear of the reference is searched as it now stands:

code: case.appeal
entity: Appeal
children:
- {code: parties, entity: Party, parent: appeal}
search:
quick-find: [caseTitle, status.name] # text fields, or through single references, besides the case number
filters: # offered as chips
- status # reference items: a choice of the list's items
- state # workflow state
- assignee # Me or Nobody
- filedOn # dates: from and to
- {children: parties, fields: [name]} # "has parties" and the fields to look in
columns:
default: [case-number, caseTitle, status, filedOn, state, assignee]
saved-views: # shipped, read-only; checked at startup
- {code: my-open, label: My open appeals, filter: "assignee = current-user and status not in (CLOSED)"}

The filter language (FilterParser in jcm-core, over a FieldScope; CaseFilters.parser(caseType) gives it the case fields through CaseFieldScope; CaseSearchService.search(SearchRequest) runs what a person types): field op value with =, !=, <, <=, >, >=, contains, starts-with, ends-with, in (a, b), not in (...), between a and b, is empty, is not empty; and / or (never mixed without brackets), not, brackets, and has <child> where (...) to any depth. Values: 'text' ('' for a quote), numbers, dates 2026-01-31, today, today-30d, today+7d, start-of-week, start-of-month, start-of-year, true / false, current-user, and codes of reference items, workflow states or enums. Case fields: case-number, assignee, state. A filter is read strictly (an unknown field, a value of the wrong kind or an unknown code is refused, saying what), written back the same (Filter.text) and said in plain words (Filter.words). In a file it is the text form of a condition: see Conditions. Typed here it becomes a query with parameters only: a field the user may not view, or a child type they may not read, is refused; the row-level rules on a child are applied inside its condition, and a child narrowed by an in-memory rule is refused. Dates compare whole days. Saved views (CaseViews) are personal until shared; only the owner shares or removes one. What a person types keeps its own reading: text = is exact, not a = x leaves out a record with no a, and a field or child they may not see is refused. A condition in a file reads as the tree does, so a saved view's text and the same text in a where can differ by case: caseTitle = 'harper' finds Harper in the where and, on a case-sensitive database, not in the view.

Upgrade note: captions of the platform's own entities. The captions of JCM's own entities now resolve. Jmix asks for one as <class package>/<SimpleName>.<attribute>; the modules had 122 of theirs keyed by the entity's name (com.jcm.tasks/jcm_Task.title), which was never read, so screens, queue headings, the field history, the data dictionary and the studio's column list showed the key (Task.title) where they now show words (Title). What changes for an application: a browser test that selects by the raw key text must select by the words; a caption is overridden in the application's own bundle under the same key (com.jcm.tasks/Task.title=Subject), and the application's bundle wins; an override written as .../jcm_Task.title was never read and still is not; QueueClaim is under its class's package, com.jcm.queues.next/QueueClaim.<attribute>. The studio's column list still offers a reference item by its name alone.