Skip to main content

Publish and inspect a studio change

Add a Return move to the hearings sample, use it from a queue and inspect the published YAML. Then see why Undo can remove an unused queue button but cannot erase a workflow state that records now occupy.

This is a separate exercise using the hearings sample's prepared roles and invented records; it does not continue editing the permit desk. Use a disposable, single-server local development instance prepared for studio editing. You need its existing manager and quality-assurance sign-ins, the matching source checkout and an environment owner who has enabled workflow and queue editing. Use the project's approved local sign-in setup; this lesson does not create accounts or change their role assignments.

The source development profile is distinct from a packaged application: jcm run builds a jar that does not contain the development profile. Do not assume starting that jar with a profile name enables editing. Verify the actual settings in Overview and use the studio settings reference for the project's development setup. Keep editing off in production.

Confirm the exercise environment​

Sign in to the prepared hearings sample as its manager and choose Configuration in Working as. Open Configuration studio under Case administration. In Overview, confirm that Workflows and Queues are editable and record where edits are written. If an area is read-only, use the displayed reason and the environment owner; do not add broad access just to follow the exercise.

Use a fresh copy of the sample: the Appeal workflow should not already contain Returned or Return. The seeded quality-assurance queue should have an invented appeal waiting in Pending release. If a previous exercise has changed those definitions, start with another prepared copy instead of guessing which changes to remove.

Draft a state and a move​

Open Workflows, then the Appeal workflow (wf.appeal). Choose Add state. Enter Returned, confirm the code is RETURNED, choose the Decision stage and save the state in the draft.

Choose Add transition. Use code return and name Return. Select Pending release as the source and Returned as the destination. Select the existing Quality assurance role and Requires a comment, then save the transition in the draft. Read the draft summary before proceeding.

Saving a dialog changes the draft, not the running definitions. The transition lists the role allowed to perform this move; it does not grant that role new record access. This exercise uses the sample's existing role design.

Choose Check and expect The checks pass. Choose Publish. Read the confirmation summary and find Returned and its Return arrow on the diagram. If Check or Publish refuses, read the file/line and reason before editing another definition; do not bypass the check.

Publish checks again. Existing workflow instances keep their definition version; an incompatible change that would strand them needs a later version. This exercise adds a state and move without deleting the states already used by the sample.

Put the move on the work queue​

Open Queues, find Pending release (q.qa.pending-release) and choose its edit control. Expand Buttons and choose Add button. Enter label Return, confirm code return, select Moves the record, and choose Return (return) as the target. Save the button draft and publish the queue change. Read its separate publish confirmation.

This is a second publish. The workflow describes the move; the queue button gives the sample's QA users a way to invoke it from their work list.

Sign in using the prepared quality-assurance account. Open the Inbox's Quality tab and Pending release queue. Select the invented Appeal of a market pitch allocation record. Choose Return, enter a short explanation and run the action. Check that the report says one record was changed. Inspect the record's Returned state and its history comment.

Use only the invented sample record. The UI confirmation and retained comment are evidence of this specific move, not a general approval of the application's role model or business process.

Read History and try Undo​

Studio History showing the two publishes and the added Returned state in the workflow diff.

Return to the manager's Configuration job role and open studio History. Find the workflow publish and the queue-button publish. Select each and inspect its file diff: the workflow adds RETURNED and return; the queue adds a button naming that transition. Record the summaries and source files for the handoff.

Select the newest queue-button publish and choose Undo, reading the confirmation before accepting it. Confirm that the queue returns to its shipped definition and the undo appears in History.

Next select the workflow publish and try Undo. It should be refused because the workflow version already has records, and undo would remove a state and transition from that version. One of those records is now in Returned. Read the refusal. The workflow file must remain in place; Undo is not a database rollback.

Do not remove the Returned state directly from the YAML to force an undo. The refusal preserves the meaning of the records already using it. Plan a later workflow version if the process needs to change again.

Hand the files back to the repository​

In Overview, recheck the studio output location. If it writes into the source checkout, inspect that checkout's Git diff. If it writes an override folder, use History's Download and review the entire archive against the deployed revision before applying intended changes to a branch. Keep unrelated edits and published changes separate.

In a source checkout, these commands help inspect the result; run the application's checks after applying and reviewing the intended changes and updating affected tests:

git diff --check
git diff -- src/main/resources/jcm/workflows src/main/resources/jcm/queues
jcm check

The download is an override snapshot, not a complete repository or just one selected publish. Do not copy it over the project wholesale. A source deletion and a studio removal marker need different handling; the history and files reference explains the mapping.

You have followed draft → Check → Publish → actual use → History → checked Undo, and identified the files needed for source review. Retain the failed undo as part of the exercise evidence. A publish in this local instance does not deploy a reviewed repository build to another environment.

For a separate local operation exercise with a prepared image and database, see Rehearse the production profile.