Skip to main content

The studio and publishing

Configuration studio​

jcm-studio with jcm-studio-starter (a Component; needs jcm-workflow, jcm-queues and jcm-roles) shows the configuration as the app read it, for the people who shape the application, and, where an environment turns editing on, changes it. The configuration is still the files: the studio writes the same YAML a developer edits, to a folder on disk (jcm.studio.files) that is the loader's first override root, and nothing it writes lives only in the database. Every change, from a form, the text editor, a matrix tick or an undo, goes through one pipeline: a draft of the file, Check (every check the application runs at startup, against the configuration as it would be, nothing written), Publish (the same checks again under a lock, the files written safely, the whole configuration swapped in one step and applied at run time on this server without a restart), a History record with its diff, and Undo of the newest publish. It shows names first, as users see them, with the code beside them, muted, for whoever edits the files; every refusal it shows comes from the loader, a registry or the workflow's own reasons, never a check of its own, with the file and line, put in plain words beside the field where a form has one.

How the parts fit (each is a section below):

  • Generations (framework implementation of reload, not an application SPI). ConfigGeneration holds the files and every kind's checked state as one generation; each registry reads from the current one per use. A publish prepares every kind against the candidate in startup order, verifies, swaps the whole generation in one write, then commits side effects (What a publish reloads; Configuration layout, "Configuration generations"). Every registry that reads files implements ConfigReloadable, so a new kind gets its editing setting, its place in the Files area and its reload by implementing it; a check lives in its prepare or verify (or a ConfigCheck bean), never in commit or a listener, so a publish refuses exactly what the next start refuses, with the same message (check parity).
  • Check and Publish. StudioPublisher.check(change) and publish(change) (Publish: the pipeline): areas and roles, stale forms, the candidate read by the loader and checked by every registry, the safe write, the swap and commits, the record. A failure after the write puts the files and the generation back; as.studio.last-publish says so.
  • The version rule. A workflow version with records on it keeps its meaning: a change that could strand a record (a state or transition taken away, a narrower from, a changed to or initial) is written as a new version, and the publisher refuses any such change, from any route, made in place on a version records are on; records finish on the version they started on (Workflow editor).
  • History and Undo. One jcm_StudioChange row per file of each publish, with the text before and after and whether the folder held the file; the History area lists them with their diffs; Undo reverses the newest publish as a publish of its own (Undid: <summary>), checks and all, after a confirmation, taking out a copy the publish put where the folder held none; Download gives the folder, its diff against the deployed application and the log (History and undo, History area).
  • The notice. Open sessions on this server are told after a publish applied: the inbox and the case screen show "Configuration changed: <summary>. Reload to see it." and redraw only when the user reloads; studio areas redraw in place, keeping what the viewer chose, unless they hold a draft (What open sessions see).
  • The editors. The workflow editor (states, transitions and stages on the diagram, renames carried to the files that name the state), the queue editor (columns as two lists, filters, buttons, layout, its inbox tab, with a live preview; new and removed queues; the inbox tabs), the job roles editor (add, edit, order and remove job roles; the role matrix's ticks put a resource role into or out of a transition's, queue's or button's roles), and the text editor (any file of an area that is on, new files, removals). Each holds a draft of one file (or the few files one change touches) and publishes it with a summary in words (Workflow editor, Queue editor, Inbox tabs, Job roles, Roles editor, The text editor).
  • Settings and the dev profile. Editing is off in every area unless that environment's own settings turn it on (jcm.studio.edit.<area>=true and a writable jcm.studio.files); the dev profile does so for a developer's own machine, writing into src/main/resources/jcm so git diff shows each publish (Editing settings, Where edits are written). The app never commits: outside development, edits reach source control by Download and a commit; a removal there is a .removed marker (commit the deletion of the real file, then delete the marker); under the dev profile a removal deletes the source file alone, the built copy counting until the next build.

The areas:

  • Overview: whether each area's editing is on here and why not, and where edits are written (Editing settings).
  • Case types (jcm_StudioCaseTypes, route jcm/studio/case-types, jcm/studio/case-types/<code> scrolling to one), read only: a card per case type, its label first with its code beside it, muted, and its layout file (case-types/<code>.yml, a link to Files). When its entity is in the data model, each entity of the case follows, the case entity and then its children depth first in the order children: lists them: a grid of its fields (Field as the label with the attribute muted, Type, Required, Length, List), its parent, its children, and "Can read" and "Can change": every resource role (Java, file or database) holding an allowing entity policy on that entity, as Name (code) by name, with read (or *) for reading and create, update or delete (or *) for changing, child roles' policies counted; a policy on every entity (*, as full access holds) is not listed, which the area's intro says, and the empty case reads "No role besides full access". An entity with audit: true says "Records who created and last changed each record." "Belongs to" names the parent by its caption, with the entity name muted only when it differs. A case type whose entity is written in Java says so, by name, and shows no fields. CaseTypeSummaries (jcm_CaseTypeSummaries) builds it: all(), and build(Model, List<CaseBinding>, Function<String, Access>) with access(List<RoleGrants>) for tests.
  • Workflows: each version drawn in columns (its stages, or steps from the initial state), with records counted per version, and one record's path on it (Workflows, A record's path); where editing workflows is on, the diagram is the editor (Workflow editor).
  • Queues: a gallery of cards by inbox tab, in plain words, each with a preview under the viewer's own rights in which nothing runs (Queues); where editing queues is on, Edit opens a queue as a form with a live preview, New queue starts one, Remove removes one (Queue editor), and "Inbox tabs" adds, renames, orders and removes the inbox's tabs and moves queues between them (Inbox tabs).
  • Roles: a matrix of who may use each queue, make each transition, press each button and see each dashboard, as the app decides at run time, with the reason in each cell (Roles); a resource role's cell is a tick where editing its area is on (Roles editor). Under it, Job roles: each job role, what it is built from and its place in the job switcher, added, edited, ordered and removed where editing job roles is on (Job roles).
  • Where used: every place a code is named, before removing it (Where used).
  • Files: every file read, line by line, numbered as loader messages name them; any file of an area that is on edited as text, new files and removals (Files, The text editor).
  • History: every publish newest first with its diffs, the confirmation and Undo of the newest, the files that differ here from the deployed application, and Download (History area).

Not applied at run time, but staged: case types and their form rules (case-types: read at startup only), the data model, the data roles and access.yml (model, roles, access: fixed when the application is built). Each is an area of its own, edited as text where its switch is on; a publish there is checked by the startup readers, written where the build reads it, recorded, and counts after a restart, or a rebuild and a restart (Staged editing, below). An area whose component is not installed is no area. jcm.yml cannot be removed. Areas without a form (tasks, deadlines, rules, dashboards, letters, reference lists, jobs, questionnaires, duplicates, seed, and the staged kinds) are edited as text where their setting is on.

Not here yet: reloading case types (DefaultCaseRegistry as a ConfigReloadable) and their form rules; forms for rules, tasks, deadlines, dashboards, letters and reference lists (and jobs, questionnaires and duplicates); propagation of a publish to other servers (today editing is refused above one server, and a server behind the newest publish says so; another server reads a publish at its next start); a condition builder for queues (the JPQL condition stays under Advanced); a Git publish target (a PublishTarget writing a branch; the app names no git today); a check of another kind against a staged entity model (a case type binding an entity only the staged model declares is refused until the rebuild).

Its overview is jcm_Studio (route jcm/studio), the item "Configuration studio" under the "Case administration" menu. Every studio view has the studio header and a left navigation, "Studio areas": Overview, Case types (jcm_StudioCaseTypes), Workflows (jcm_StudioWorkflows), Queues (jcm_StudioQueues), Roles (jcm_StudioRoles), Job roles (jcm_StudioJobRoles, a flat item set in under Roles: a nested item's expand button fails the accessibility scan), Where used (jcm_StudioWhereUsed), Files (jcm_StudioFiles) and History (jcm_StudioHistory); the areas have no menu items of their own. StudioViews.ALL lists the view ids. A studio view extends StudioAreaView, whose descriptor is one <vbox id="studioBox" padding="false" width="100%"/>, and fills content(). StudioLinks makes the deep links: workflow(code, version, transition) (jcm/studio/workflows/<code>?version=<n>&transition=<t>, each query value when given), queue(code) (jcm/studio/queues/<code>), whereUsed(value) (jcm/studio/where-used?code=<v>) and file(relativePath) (jcm/studio/files?file=<path>), history(publishId) (jcm/studio/history/<id>) and historyDiff(relativePath) (jcm/studio/history?diff=<path>), queueEditor(code) (jcm/studio/queues/<code>/edit) and newQueue() (jcm/studio/new-queue), jobRoles() (jcm/studio/job-roles), with the values URL-encoded; anchor(link, text) makes a link to one that is followed in the page.

Two roles, held with the host's minimal UI role:

  • StudioViewerRole (jcm-studio-viewer) opens every studio view and its menu item, and nothing else; its @ViewPolicy lists each view id, the queue editor's (jcm_StudioQueueEditor, jcm_StudioNewQueue) too, which are not in StudioViews.ALL (they are opened from a card, not the navigation) and show their form read only with the reason; the job roles' forms and the inbox tabs open for it read only, each button saying why. In History it sees every publish, its diffs and Download; Undo is disabled with the editor-role reason.
  • StudioEditorRole (jcm-studio-editor) composes the viewer and grants no more rights; holding it is what StudioEditing.of(area) asks of the signed-in user before a form, the text editor, a matrix tick or Undo may publish where the environment allows editing (no editor role below). The publisher asks the same whatever calls it, and History records the user and the job role they worked as.

Neither grants entity rights or composes a role of another component: whatever a studio view shows of records (a record's path, a queue preview's rows) runs with the user's other roles. Never give system-full-access to show the studio. A job role that holds a studio role beside a group's resource role, such as the hearings demo's Configuration (job.studio: jcm-studio-editor and demo-manager), lets that user show a record's path and preview the group's queues with rows; the demo's studio walk is in The hearings demo.

The Files area and where-used read what the loader read, never the files again: ConfigFiles.loaded() for each file's text, root and what it replaces, and ConfigNode.scalars() for each value with its line and what it is written under (see Where files are read from).

What a publish reloads​

Every kind that loads from files is a ConfigReloadable (see Configuration layout, "Configuration generations"). A publish prepares every one against the candidate in this order, each seeing the candidate's state of the kinds before it, then verifies, swaps the generation, then commits; the next request reads the new generation.

OrderKind (folder)RegistryChecked against on publishCommit
100Workflows (workflows)WorkflowRegistrybindings, roles, effects, related movesnothing; a move running finishes on its definition, records keep their version
110Duplicates rules (duplicates)DuplicateRegistrycase types' attributesnothing
120Jobs (jobs)JobRegistryjob beansJobScheduleSync.sync(): group jcm matches the files; a run in progress finishes; other groups untouched
200Job roles (job-roles)JobRoleRegistryresource and row-level rolesnothing; a removed job role drops to the default at the next request
210Queues (queues)QueueRegistrythe candidate's workflows; conditions in the database; set values in verify against the candidate's reference listsnothing
220Rules (rules)RuleRegistrythe candidate's workflows and job rolesnothing
230Task templates (tasks)TaskTemplatesthe candidate's workflowsnothing; tasks already made stay
240Deadlines (deadlines)DeadlinePoliciesthe candidate's workflowsnothing
250Seed (seed)SeedRegistrythe candidate's workflows and job rolesnothing; seeding runs at startup only
300Reference lists (refdata)RefDataSeedLoaderstored parentsthe changed lists and items, by hash, in one transaction
310Letters (letters)LetterSeedLoadercase types, placeholdersthe changed templates, by hash, in one transaction
320Dashboards (dashboards)DashboardRegistrythe candidate's queues and deadline policies; rolesnothing
330Questionnaires (questionnaires)QuestionnaireRegistrythe candidate's reference lists, then the stored onesnothing

Case types (case-types) are read at startup only and are not reloaded: a publish there is staged (Staged editing, below). Their form rules are still checked on every publish: FormRuleChecks is a ConfigCheck that parses the candidate's layouts' rules against the candidate's workflows and job roles, so a publish that takes away a state, transition or job role a rule names is refused with the layout's own <file>:<line> message (Configuration generations).

Publish: the pipeline​

Every save the studio makes goes through StudioPublisher (jcm_StudioPublisher): check(Change) runs steps 1 to 3 and writes nothing; publish(Change) runs all six. Both run under one ReentrantLock per application, so the candidate a publish checked is the one it swaps in, and two publishes never interleave. A Change(files, summary, undoes) names one or more FileChange(relative, before, after, area): before the text the form read (null: the file did not exist), after the new text (null: remove the file), area the editing area the change belongs to. FileChange.of(relative, before, after) derives the area from the path (the first segment; app for jcm.yml); a form that writes one kind's key of jcm.yml (inbox tabs, orders) builds new FileChange("jcm.yml", before, after, "<kind folder>"), and such a change is accepted under that kind's setting only when the two texts differ in no top-level key other than that kind's appWideKey (each key's value compared as written, from where its node starts to where its last value ends: a change only to comments or to whitespace outside the values counts as that kind's change); otherwise it needs app. For any other file the area must be the path's own (its first segment), and a FileChange that says otherwise is refused with IllegalArgumentException("<relative> is in the area <folder>, not <area>"), so no form can put a file past another area's switch.

  1. Areas. No change may remove jcm.yml, under any area: jcm.yml cannot be removed; edit it instead (an undo may still take away a jcm.yml the studio folder added where the application has none). Each file's area must be editable for the signed-in user (StudioEditing.of(area): the environment's reasons, then the role), its folder must have a ConfigReloadable or be a staged area (StudioEditing.staging; else Editing <label> is not possible at run time in this release: <label> are read at startup only. Edit the file and restart.), and there must be a publish target (Nothing can be published: jcm.studio.files is not set, so there is nowhere to write; set it to a writable folder.); a folder that cannot be read refuses Nothing can be published: jcm.studio.files names <path>, which could not be read: <reason>. A folder no kind owns is not an area; it is left to the loader, which refuses it on the candidate with its own message (<file>: no installed component reads <root>nosuch/; ...). A jcm.yml change labelled with an area no registry reloads (one the settings do not know, or a kind read at startup only) is put under app before anything else, since the loader reads jcm.yml whatever its label: the app-wide gate holds for it, and History and the notice read app.
  2. Stale forms. Each file's current text (the folder's copy, none when the folder holds its marker or when the folder is the source (jcm.studio.files-are-source) and lacks a file of its own, else what the application loaded) must equal before: <relative> changed since you opened it; reopen it and make the change again.
  3. The candidate and the checks. The folder's contents (target.contents()) with the change applied are read by the loader as the candidate, files.withRootBytes(target.root(), content), which runs every refusal the loader runs at startup; the files of a fixed kind the target stages (every fixed kind where the folder is the source, and a kind kept elsewhere, PublishTarget.elsewhere()) are taken out of that content and read first as the next build would copy them, files.asRebuilt(fixed) (Configuration layout), so a staged role or model file is checked, never refused as an override; then generation.prepareAll(candidate, every ConfigReloadable bean, every ConfigCheck bean) runs every registry's checks against it. A ConfigException (every kind's exception is one) is the refusal as it is, with the file and line; any other exception is The checks could not run: <message>, so a check that fails to run never lets a publish through. Once the candidate passes, every ConfigAdvice bean (jcm-core, notes(PreparedView candidate)) adds plain sentences to the result's notes: what publishing will do that the person should know, such as deadline actions a changed action definition cancels. Advice refuses nothing, and advice that cannot be given is left out. The version rule's refusal (WorkflowVersionRefusal) is worded for an undo when the change is one: Can't undo: removing Returned and Return from Appeal workflow version 1 would strand its 21 records; leave it, or remove it in a new version. (removing <state and transition names> from <workflow name> version <n>; changing ... (<reasons>) ... or make the change in a new version. when nothing is removed; removing <workflow name> version <n> would strand its <n> records; leave it. for a version dropped). check returns Checked(notes) here.
  4. Write. target.write(writes): each changed file; a removal deletes the folder's own copy and, when a file of that path still counts in the candidate (the application's own), also writes the item's marker (<folder>/<code>.removed, <code>.v<n>.removed for a version), read again by the loader before the checks so a marker's refusals are the loader's; a file written over its own marker takes the marker out. Two removals write no marker: one where the studio folder is the application's own source folder (jcm.studio.files-are-source, the dev profile), which deletes the file alone with the note <file> is deleted; the built copy counts until the next build; and a FileChange.dropCopy(relative, before, after, area) (dropsCopy), an undo taking out a copy the publish put where the folder held none, with the note <file>'s copy here is deleted; the application's own file counts again. A failure is Nothing was published: <relative> could not be written: <reason>, with everything put back by the target.
  5. Swap and commit. generation.swap(candidate, states), then each kind's commit in its reload order. When a commit throws, the files are put back from the contents read in step 3 (target.restore), the generation is swapped back (swapBack), and the previous state is committed again for the kinds the publish changed (a file's folder; for a jcm.yml change, the kinds whose key differs) that had committed: a kind the publish did not change committed the same entries by hash, so it is not committed again and an administrator's run-time edit to its rows stands. It is logged at ERROR, as.studio.last-publish fails, and the result is The change was undone after a failure applying it: <message>.
  6. Record. Every PublishRecorder bean is told (record(publishId, change, generation, heldBefore), the last the paths the folder held before the write), inside the lock on the publishing thread, the required ones first (required(), true for History, below). When a required recorder throws, the publish is put back exactly as a step-5 commit failure is (files restored, generation swapped back, the changed kinds committed again), as.studio.last-publish fails, and the result is The change was not published: History could not record it: <message>: a change History does not hold could not be audited or undone. Any other recorder that throws is logged at ERROR and the publish stands. ConfigGenerationChanged was published by the swap. StudioReloadNotifier is the last recorder, not required: it tells open sessions (What open sessions see, below).

publish(change, guard) runs guard (a Supplier<Optional<String>>) first under the lock, before anything is read or written, and refuses with its text when it gives one; undo passes History's refusals as the guard.

The result is a PublishResult: Published(publishId, generation, notes), Checked(notes) or Refused(message, relative, line), where relative and line are read from a <file>:<line>: prefix when the message names one of the change's files by its display under the folder (null otherwise), for the form to show the refusal at the field. Notes say what a removal did: <file> is removed by the marker <marker>; the application's own copy remains or <file> is deleted. Every publish logs one INFO line naming the generation, the summary and who published, as which job role. The console assertion as.studio.last-publish ("The last publish applied") passes with No publish has failed while applying, or The last publish applied, and fails with The publish at <time> failed while applying: <message> from a step-5 failure until the next publish goes through.

What open sessions see​

After a publish applied (committed and recorded; a refused or put-back publish tells no one), StudioReloadNotifier (jcm_StudioReloadNotifier, a PublishRecorder) sends ConfigurationChangedUiEvent(source, generation, folders, summary) (in jcm-core, com.jcm.core.config) through UiEventPublisher.publishEventForUsers(event, null), which reaches every UI of every session on this server. generation is the number the publish made current, folders the areas its files belong to, each once ("" for jcm.yml as a whole), summary the publish's summary as History shows it. words() reads `Configuration changed:

. Reload to see it.` (a final full stop of the summary dropped), as in `Configuration changed: Renamed My team's work to Team work. Reload to see it.`; with no summary it names the kinds instead, each folder with dashes as spaces, `jcm.yml` for the app-wide file: `Configuration changed: workflows, queues. Reload to see it.`
  • The inbox and the case screen show a notification (ConfigurationChangedNotice, in jcm-queues): Notification id configurationChanged, bottom start (over the menu, clear of the header's controls and of a grid's pager), no auto-close (duration 0), theme variant info (one the Aura theme styles), the text (configurationChangedText), a "Reload" button (configurationChangedReload) and a "Dismiss" button (configurationChangedDismiss), both reached by Tab. Reload reloads the page at once, unless the screen shown holds unsaved changes (its view's data context has changes, as a case screen with edited fields does, or the view HoldsUnsavedInput and says so, as a studio area with a draft does): then the dialog configurationChangedConfirm asks "You have unsaved changes on this screen. Reload anyway and lose them?" with "Keep editing" (configurationChangedKeep, focused; closes the dialog, keeps the input and the notice) and "Reload" (configurationChangedReloadAnyway). Nothing on the screen is drawn again: the inbox keeps its tabs, the queue it shows and its grid's columns, the case screen its record and any unsaved input, until the user reloads. There is one notice per browser tab (ConfigurationChangedNotice.of(UI)), whichever screen opened it: moving from the inbox to a case screen keeps it, and a further publish while it is open changes its text; it never stacks. InboxView.configurationNotice() and CaseScreenView.configurationNotice() return it while open.
  • Every studio area (StudioAreaView) is drawn again in place, as the same view: the header's counts, then the area's refresh() (abstract; each area implements it), which re-reads the current generation and keeps what the viewer chose. Workflows keeps the chosen workflow and version, the zoom, the marked transition, the record searched for and its path, and an open state's detail; Queues redraws its cards (an open preview stays open); Roles keeps the column group (by its name) and both checkboxes; Where used searches the new files for the code last searched, the field as typed; Files keeps the kind filter and the open file; History keeps the selected publish, or the file whose difference is shown, and an open Undo confirmation. When what was chosen is gone, the area says so in studioRefreshNote (role=status) as <name> was removed by a publish (Appeal workflow (wf.x) was removed by a publish, ... version 2 ..., queues/q.a.yml ..., the group's name) and falls back to the first workflow or latest version, no open file, the first group. No route is navigated or refreshed.
  • An area holding a draft (an editor's unsaved input) returns true from hasDraft(); it is then not drawn again, and the tab's ConfigurationChangedNotice is shown instead, whose Reload asks first (StudioAreaView implements HoldsUnsavedInput through hasDraft()). The editors hold one while their input is unpublished: the workflow editor's draft, the queue editor's (and a new queue's), an open job role or inbox tabs dialog with changes, and the text editor's changed text; once published, the form is drawn again from the new generation. The session that published receives the event too, after its own request. Nor is such an area left by the router without a question: a navigation item, the header's or where-used's links, a Diff link or the browser's Back stop at studioDiscardConfirm (Discard your changes to <x>?, <x> the workflow, the queue by name and code, the file's path, the job role, the inbox tabs), where studioDiscardKeep (focused) cancels the navigation and studioDiscardYes forgets the draft (discardDraft()) and lets it go on (Jmix's BeforeCloseEvent with a NavigateCloseAction, the BeforeLeaveEvent postponed meanwhile); a second navigation while the question is open (Back, another click) asks nothing more: the one question stands and answers for the newest navigation (Vaadin keeps one postponed navigation per tab).
  • The studio's areas, WhereUsed and RoleMatrix read the current generation's files (ConfigGeneration.files()) per use, never the startup ConfigFiles bean, so none shows the files as they were before a publish; the case registry and layouts keep the startup bean (case types are read at startup only).
  • A publish whose every file is of a staged kind tells no session: nothing changed at run time. One that also touches a kind applied at run time names those kinds alone (StudioReloadNotifier).
  • Other screens are not told; they show the new configuration at their next navigation.
  • A server push is needed for a session to be told without a click: the app class carries @Push, as the scaffold writes it. Another server is not told; it reads the change at its next start.

How a form writes YAML​

A form changes a file's text where the node it edits is written; the file is never written out again from what was read, so every comment, the order of keys, blank lines and every line the change does not touch stay byte for byte, with the file's line separator (\r\n or \n) and a leading byte order mark kept. YamlEdits (jcm-core, static) does it from a node read from that same text (ConfigFile.ofText(...).root() and its find, sequence, items); a node read from another text is refused, so read the text again after each change:

  • replaceItem(text, item, itemText): from where the item starts to where its last value ends; the dash before it and a comment after it stay.
  • appendItem(text, sequence, itemText): a block list's new item on a line after the last item's last line, at the list's dash column; a flow list's after its last item as , item; an empty [] becomes [item]. A list not written yet is addKey(text, mapping, key, "[" + item + "]").
  • removeItem(text, item): a block item's lines, comments on them included; a flow item with its , . A list left empty is written [].
  • setScalar(text, scalar, value): the value as text, quoted when it needs it (below); a block scalar's lines go.
  • addKey(text, mapping, key, valueText) at the mapping's end (a block mapping's new line at its first key's column, a flow mapping's before }); a key already written is refused. removeKey(text, mapping, key) takes its lines, or its place in the line with its , ; a mapping left empty is written {}.
  • itemText(fields, indent) writes a new entry, keys in the order given: one flow mapping, {code: RETURNED, name: Returned}, when indent plus its length is at most 118 characters (YamlEdits.LINE_LIMIT) and no value is a mapping; else a block mapping, its later lines at indent (the entry's first key's column: the list's ConfigNode.indent() plus 2). Lists of values are [A, B], mappings are block style, lists of mappings are block items written by the same rule; numbers and flags are bare.
  • scalarText(value): bare when YAML reads it back as the same text, else double-quoted with \ escapes: an empty value, one holding : , #, ? or a flow indicator (, [ ] { }), one starting with a special character or a space, one with a line break, and one YAML would read as a number, flag, date or null (007, yes, ~).

Every change is read again before it is returned; one that does not read is refused with the reader's message, <file>:<line>: <problem>, as in workflows/wf.appeal.v1.yml:28: expected ',' or ']', but got : (while parsing a flow sequence at line 27). Whether the file still means a valid configuration is the registries' check at publish. ConfigNode.span() (Span(startLine, startColumn, endLine, endColumn): lines from 1, columns from 0, the end exclusive) says where a node is written, a block mapping or list ending at its last value, not at the next key; ConfigNode.indent() is a block list's dash column or a mapping's first key's column.

Staged editing​

A kind the application reads at startup only is edited in the studio as any other, and its publish is <em>staged</em>: checked, written and recorded like every publish, applied at run time by nothing. StudioEditing.staging(area) says which: RESTART for a registered folder no registry reloads (case-types), REBUILD for a kind fixed when the application is built (model, roles, access, the shared and extension forms), each only when some ConfigCheck names its folder in startupFolders() (CaseTypeFileCheck, ModelFileCheck, RoleFileCheck, AccessFileCheck, SharedForms, ExtensionForms). A kind read at startup only that no check reads as the start does (audit, whose AuditFileParser runs at startup alone) is never staged: its area is refused whatever its switch, Editing <label> is on (jcm.studio.edit.<area>), but <label> files are read at startup only and no check here reads them as the next start does, so a staged change could stop it. Edit the files in the source, rebuild and restart. Each staged kind is an area under its own switch (jcm.studio.edit.case-types, .roles, .access, .model), with the folder, the server count and the editor role as every area has; the text editor is the editor (the Case types area links each card to its layout file in Files, and its intro says how the layout, the model and the roles are changed here).

  • Only on a developer's own machine. jcm.studio.files-are-source=true and the switch of a kind fixed when the application is built (jcm.studio.edit.roles, .model, .access, ...) stop startup unless the dev profile or the local-preview profile is active (StudioSettings.LOCAL_PROFILES): jcm.studio.files-are-source=true is refused: writing the application's own source folder is for a developer's own machine and needs the dev or local-preview profile active; the active profiles are <profiles>. (none is active), and jcm.studio.edit.<area>=true is refused: <label> files are fixed when the application is built, and staging them is for a developer's own machine; it needs the dev or local-preview profile active; .... local-preview is for a local preview run under a profile of its own (and for tests that stage a fixed kind); no environment shared by people sets either. Case types stage under any profile, in any writable studio folder.

  • Where it lands. Case types, roles and access.yml under jcm.studio.files at their own paths; the model in jcm.studio.model-files (model/<Entity>.yml in the studio's paths, <Entity>.yml on disk). Under the dev profile these are the project's own source files, so ./gradlew bootRun copies the case types, roles and access.yml to the classpath and generateJcmModel reads the model, and git diff shows the change. A fixed kind stages only where jcm.studio.files-are-source is true (StudioEditing refuses it elsewhere, with why: an override folder's copy of one is refused by the loader at the next start); a case type stages in any writable studio folder, where it is an override the next start reads and shows as "only here" or "changed here" to promote by Download.

  • The checks. The startup readers run against the candidate as ConfigCheck beans (Configuration layout, "Configuration generations"), so check and publish refuse what the next start refuses with the same file and line: a case type binding an unknown entity, a form naming a field the entity lacks, a rule naming a state the workflow lacks, a role granting an unknown entity or attribute, a model file the parser refuses, a model difference jcmChangelog refuses. The candidate reads a fixed kind as the next build would copy it (ConfigFiles.asRebuilt, Publish: the pipeline, step 3). While the candidate's case types differ from the startup ones, every kind and check runs a second time against them (NextStart, Configuration generations): a staged case type that takes away a child type a rule, a queue or a letter names, or a case type a workflow binds, is refused with that file's own sentence followed by The next start would refuse this: it reads the case types staged in the studio folder, which this server does not run yet. Change the file, or discard the staged case type in History. (StudioPublisher.NEXT_START; a refusal at a line of the change's own file is the startup reader's sentence alone), and a publish of a kind applied at run time is held against the running and the staged case types both. A case type binding an entity only the staged model declares is refused with the loader's own refers to unknown entity until the rebuild: stage the model, rebuild and restart, then the case type (the editor's intro says so for a model file).

  • What is not checked, and recovery. The checks see the files, not the database or the code: records already stored on a case type, child type or state a staged change takes away, Java code naming them, a bean that keeps what it read from the case types in a field of its own, and, for a fixed kind, the build itself (the model is held against schema.json and the running metamodel, not the classes the build makes). So a restart can still refuse a staged change, and then the application, and the studio with it, does not start. Every place a staged change is shown says so, and how to put the file back by hand (StagedChanges.recovery(pending)): in a source folder or the model's, restore <absolute path> from version control (git checkout -- <absolute path>) and start again, or delete <absolute path> and start again. for a file the change added; in any other folder, delete <absolute path> and start again; the application's own file counts again. (delete the marker <path of the .removed marker> ... for a removal). With the application down, the folder is the record: git status in the source, or the studio folder's files against the deployed ones.

  • The result. Published and Checked carry, in their notes, one sentence per staged area the change writes, StudioEditing.stagingWords(area): Changes to case types wait for a restart; this server keeps the case types it started with. (Changes to roles wait for a rebuild and a restart; ...), and for the model ModelFileCheck's advice (Configuration generations). Files says Staged: <summary>. <notes> <limits> in studioFilesPublished rather than Published: <summary>, where <limits> is StudioEditing.stagedLimits(area): for case types It was checked as the next start reads it, with the queues, workflows, letters and other kinds held against these case types; a restart can still refuse what no check here sees, such as records already stored or code that names a case type., for a fixed kind It was checked by its own startup check; the build and the restart can still refuse it, since nothing here runs the build. The line is a status (jcm-studio-result): a clock icon and the warning tone for a staged save, a check icon and the ok tone for one applied at run time; its text is the words alone. The generation is swapped as for any publish, so the Files area and where-used show the staged text; the registries that read these kinds keep what they loaded at startup, and no session is told (What open sessions see).

  • The pending state. StagedChanges (jcm_StagedChanges, jcm-studio) reads it from the files, never from History, so it is right after a studio publish, a restart without a rebuild, or an edit made outside the studio: for each file of a staged kind this target stages (pending(), in path order, as Pending(relative, area, label, code, kind, need, words, startupText, nextText)), the text the next start would read (the folder's copy, the model folder's file, else what the application loaded; a marker or, in a source folder, a missing file as none; StudioPublisher.currentText) against the text this server read at startup (the startup ConfigFiles bean); one that differs is pending, CHANGED, ADDED or REMOVED (kindWords(): changed here, added here, removed here), with its Need: RESTART (a restart; the words restart the application), REBUILD (a rebuild and a restart; rebuild and restart the application (./gradlew bootRun does both)), CHANGELOG (a changelog, a rebuild and a restart; the model whose tables change, ModelFileCheck.need(candidate, startup), with the words The entity model change alters the tables (<summary>): run ./gradlew jcmChangelog, then rebuild and restart the application for it to count.) or REFUSED (the entity model files to be put right, then a changelog, a rebuild and a restart; a model the parser or jcmChangelog refuses, which an outside edit can leave: a file the loader cannot read, one without its entity: key, gives The entity model files cannot be built as they are: <the loader's sentence>. Change the model files, then run ./gradlew jcmChangelog, rebuild and restart., never an exception, so the header and History keep drawing). of(relative), count() and headerLine() (1 staged change waits for a restart, 3 staged changes wait for a rebuild and a restart, the strongest need named; empty when none waits); a page that asks often takes pending() once and passes it down (StagedChanges.in(pending, relative), StagedChanges.headerLine(pending)). The folder is read on every pending(), but what waits is worked out again (the model parsed, the schema diffed) only when the folder's contents changed since the last call. A fixed kind's file in a folder that is not the source is never pending: the loader refuses it at the next start.

  • Where it shows. The header, on every area, has one status strip, studioStatusStrip (role=group, named Studio status), of chips (jcm-studio-chip, a pill with an icon, a count and a label, the tone tinted behind text mixed toward the text colour; a chip that links underlines its label on hover only): studioEditingOn (the accent tone, <n> areas with editing on, 1 area with editing on; hidden above one server or with every area off), studioOverrideCount (neutral, linked to History, <n> files here differ from the deployed application), the status region studioStaged (role=status) holding studioStagedLink (the warning tone, a clock, the headerLine() words, to History's "Waiting for a restart"), and while jcm.yml is read from the studio folder studioAppWideShadow (warning) with the link studioAppWideDiff; the strip is hidden when it holds nothing. History: above "Differs here", the section studioStagedSection with studioStagedHeading "Waiting for a restart", studioStagedIntro (that each file was checked as the next start reads it, that a restart can still refuse what no check sees and then nothing starts, and that each row says how to put its file back) and the card studioStagedList (role=list), one row studioStaged-<n> (role=listitem) per pending file: studioStaged-<n>-words (<name> (<code>) — <path>: changed here; Restart the application., the name and path in bold), studioStaged-<n>-recover (If a restart refuses it, <recovery>), the need as a chip studioStaged-<n>-need (Restart, Rebuild and restart, Changelog, rebuild, restart, or Build refuses it in the danger tone), then at the right, in one small tertiary style, studioStaged-<n>-diff ("Diff", a link to ?staged=<path>, StudioLinks.stagedDiff, read as Diff of <path> against what the application started with) and studioStaged-<n>-discard ("Discard", named Discard the staged change to <path>; enabled where the user may edit the area, else disabled with the reason as tooltip and aria-description). Discard asks first, as Undo does: the dialog studioDiscardStagedConfirm "Discard the staged change?" (studioDiscardStagedConfirmText: Discard the staged change to <path>? The text the application started with is written back; History records it, and Undo of that publish puts the staged text back.), Cancel (studioDiscardStagedConfirmNo, focused) and Discard (studioDiscardStagedConfirmYes, primary). In "Differs here" a file that also waits for a restart carries the chip Also waiting for a restart, linked to the section. ?staged=<path> shows studioStagedDiffSummary (<path>: what the application started with, then what the next start reads. <words>; : added here; the application started without it; : removed here; the application started with it; <path> is not staged; this server runs with the file it started with) and diff-0 of the startup text against the next start's; ?staged alone opens History at the section (StudioLinks.staged()). A refusal of Discard shows beside the list as Not discarded: <message> (studioStagedRefusal, role=alert); a discard that applied says Discarded the staged change to <path>; the file reads as the application started with it. in studioHistoryPublished (role=status, the ok status) and lists History again. Files: the Difference column holds the chip Staged (warning tone, a clock) for a pending file, a link to its diff read as <path> is staged and waits for <need>; its difference against what the application started with; the open file's note studioFileStaged (class jcm-studio-staged-note) reads Staged: this file is changed here and waits for a restart; this server runs with the text it started with. Restart the application. A restart can still refuse what no check here sees; if it does, <recovery> while it is pending, else the area's stagingWords; hidden for a kind applied at run time. The text editor's intro, for a staged kind, reads Save runs the checks a publish runs; nothing is written unless they pass. This kind is read at startup only: a save is staged and waits for <waits for>; this server keeps what it started with., then for case types The save is checked as the next start reads it, the other kinds held against these case types; a restart can still refuse what no check here sees, such as records already stored. and for a fixed kind The save is checked by this kind's own startup check; the build and the restart can still refuse it. (and, for a model file, the order with the case types that bind its entities); for any other kind Save runs every check the application runs at startup; nothing is written unless they pass. The Overview's Why column reads Editable here; changes wait for <waits for>. The Case types area's card adds caseTypeStaged-<id>: Staged: the layout file is changed here and waits for a restart; this server shows the case type it started with. while its layout file is pending.

  • Discard. StagedChanges.discard(relative) publishes the startup text back through StudioPublisher, summary Discarded the staged change to <path>: an added file removed; a removed one written back (in a source folder or the model's; elsewhere the marker taken out); a changed one written back in a source folder or the model's, its copy taken out elsewhere (FileChange.dropCopy). History records it, Undo reverses it as any publish, and the checks may refuse it. Nothing is staged at <path> when nothing waits there.

  • Not here. No reload of these kinds at run time, no propagation, no in-app restart, no discard while the application is down other than by hand (What is not checked, and recovery), and the application never runs jcmChangelog or a build: the words say what to run.