Optional technical reference. This material is for developers, integration specialists and platform administrators. For the consultant lesson, read the practical guide.
Preserved from source baseline
d4587c7c0e073e58c2d430342f65ac55dd701bf4; source/static examples retain their stated scope. They are not new runtime verification or required consultant setup steps.
Operate and transfer the People Operations application
Story and output
Nadia has completed a synthetic Leave requests application in an admitted development workspace. She wants a controlled source release, a separately admitted target, a clear post-transfer check and an operational diagnosis plan. This tutorial connects the deployment manual, active-active guide, migrations and logging.
A workspace lifecycle uses DEV → STAGING → PRODUCTION. A deployment environment record has its own type vocabulary (DEV, TEST, UAT, STAGING, PROD, OTHER) and transfer mode (PUSH, PULL, OFFLINE). Those are not interchangeable request enums, and neither automatically copies application content.
flowchart LR
Published[Authorized published source assets] --> Release[Build signed release]
Release --> Inspect[Inspect original bytes in target context]
Inspect --> Admit[Trust / grants / references / target policy]
Admit --> Transfer[Supported import or transfer]
Transfer --> Check[Exact target readback and admitted smoke]
Check --> Operate[Node / queue / logging diagnosis]
Keep a private operator record with actual source/target IDs, candidate/build, original release bytes/hash, signing/trust identity and native reports. Credentials, private keys and confidential records are not part of the public tutorial.
This is a source-backed teaching journey with synthetic data. It is not a built-in leave application or a completed import package. Perform any real mutations only in an admitted owned environment with normal authentication; this documentation program did not execute the product/provider workflow. Keep actual IDs/revisions/versions and private session material outside public examples.
Milestone1 — Establish source, target and operational authority
Scenario and inputs. The source People Operations workspace exists with reviewed current publications. The target is separately owned and not assumed importable because it has a similar name. A normal signed-in person has the actual deployment action grants and required workspace/asset access; platform bypass, an API key and a service identity do not substitute for this release admission.
Procedure. Read the source workspace and visible release workspace/candidate surfaces. Identify the exact source environment/candidate and target environment definition, owner, type and transfer mode. Review trust/signing/peer/outbound policy only with their authorized owners. Keep source and target account/provider/connection identities separate. Confirm that the intended route is admitted for this target and that no production/private/native/provider/data/resource hold is being treated as released by this tutorial.
Expected result. The operator record has a concrete source, legitimate target route and accountable action owners. It distinguishes release viewing, building, downloading, inspecting and importing/transferring, rather than assuming one “deployment admin” label covers everything. The current public records and policy determine what can actually be attempted.
Failure and recovery. If the desired target or action is absent, resolve that specific grant/ownership/policy issue. Do not change an environment's classification, trust any presented signer or use another person's credentials to gain visibility. Keep the plan incomplete when no route is admitted; a source-authored runbook is not execution permission.
Sources. ReleaseService.java:45, EnvironmentType.java:1, TransferMode.java:1.
Milestone2 — Check the schema and dependency boundary without mutating it
Scenario and inputs. Before a real target rollout, the operator needs to know whether the intended API/runtime has compatible schema and admitted dependencies. The source and target have different actual connection/Compose settings. Reading version/status is distinct from applying a migration, starting a provider or restarting a shared renderer.
Procedure. Inspect the selected target and served build metadata through its authorized operating route. Compare the actual readiness verifier and ordered migration history with the target's reported clean journal; use the wrapper only in the specifically admitted lane, with java-dev available for its exec client. Review required plugin-runner health and actual broker/document/provider boundary for the intended features. Keep provider/template/native qualification and external service readiness as separate recorded conditions.
Expected result. The plan identifies known readiness evidence and explicit missing boundaries. A clean journal number or a reachable page is not full product verification, and physical data-model publication is not automatically reproduced by applying platform migrations. Existing target data, schema and evidence remain intact during this read/assessment stage.
Failure and recovery. On a dirty/mismatched schema or unavailable dependency, preserve the original failure and ask the accountable owner for the exact authorized repair/start action. Do not force a journal marker, drop a database, restart a shared service or substitute an old artifact's pass. Historical upgrade numbers and screenshots retain their original candidate scope.
Sources. migrate.ps1:77, DatabaseSchemaReadinessVerifier.java:1, README.md:1.
Milestone3 — Build and download the intended signed release
Scenario and inputs. The source contains the published teaching assets and the caller has the actual BUILD grant plus required access to every included asset. Nadia chooses WHOLE for this synthetic workspace; a real selected release must use actual returned family/key/version candidates and their dependency closure.
Procedure. Read the native source candidates and then build through:
POST /api/deployment/releases?workspaceId=<source-workspace-id>
Content-Type: application/json
{"scope":"WHOLE","roots":[],"tombstones":[]}
Inspect the returned summary, source server/workspace, release number/hash, signing key and entries. Download the actual original format-4 file through the native download route when permitted. Retain its exact bytes/hash privately; do not reconstruct the package from a shortened response projection.
Expected result. The release records its immutable content and admitted published dependencies. Building/downloading it is not a target import, a migration or runtime acceptance. Unreadable required assets can refuse the entire build. The current DTO has no generic client operationId to invent as a substitute for its actual state/readback.
Failure and recovery. If the reply is uncertain, inspect existing releases and the matching content/source report before another build attempt. Do not assume a new release number is the same original operation. Correct missing asset access or unsupported dependencies through their owners and preserve original failures instead of excluding inconvenient content to obtain a green package.
Sources. DeploymentReleasesController.java:62, ReleaseService.java:125, DeploymentReleasesController.java:68.
Milestone4 — Inspect the original package and resolve target references
Scenario and inputs. The original signed package is available and the operator has selected the actual admitted target workspace. Source identity IDs, local accounts, connections and providers may differ from target identities. A matching label does not establish a valid binding, and a package signature does not authorize the importing actor.
Procedure. Use POST /api/deployment/releases/inspect in the current target workspace context, wrapping the unmodified downloaded object in the native release field. Read its compatibility, trust/signature, dependency, family, ownership/ledger and target-reference findings. Resolve allowed aliases with the actual target-side authorized catalogs and intended secret/provider owners. Retain the original signed bytes and the concrete proposed binding map; re-inspect if any relevant target condition changes.
Expected result. The native inspection can explain whether the package is verifiable here and what prevents an import, without importing it. Its evidence is tied to the actual target and original signed content. It does not authorize replacing a signing key, exposing a provider secret or choosing another workspace's contract as a convenient alias.
Failure and recovery. On unknown signer, unsupported content, missing native qualification or an ownership conflict, preserve the refusal and resolve the named owner action. Do not edit signed content, hand-write a fake release hash or use a legacy format as a bypass. If the target route remains forbidden, no import should occur merely because source inspection looked correct.
Sources. DeploymentReleasesController.java:99, ReleaseWorkspaceImport.java:90, WorkspaceTransferController.java:49.
Milestone5 — Perform only the admitted transfer and read its actual result
Scenario and inputs. The package, target, caller, route and bindings have an explicit admitted operating plan. This milestone is consequential and must not be attempted when production/private/source/data/provider/runtime holds still block it. A direct workspace import and an online peer transfer have different native entry points and authorization; do not transpose their payloads.
Procedure. Use the selected supported route and its exact current request. The direct workspace import contract accepts either exportPackage or release, not both, and uses the current workspace context plus actual bindings. Preserve the native result and original uncertainty if the reply is lost. Read the exact target asset/publication/ledger state through authorized surfaces after an accepted transfer; compare logical identities, explicit reference mappings and reported changes with the signed release's intended content.
Expected result. An accepted native report establishes its actual imported/transferred state, not automatic provider availability or a completed ordinary-user workflow. Production and managed-target restrictions remain enforced independently of a valid signature. The target's actual published version and source provenance, not its display label, identify what was delivered.
Failure and recovery. Do not relabel Production, remove managed ownership, import both payload families or replay a timeout with fabricated generic receipt fields. Reconcile the original native outcome and current target state with its owner. If no safe discriminator exists, retain the outcome as uncertain and keep a separately scoped recovery decision rather than force another business effect.
Sources. WorkspaceTransferController.java:77, ReleaseWorkspaceImport.java:1.
Milestone6 — Qualify intended user behavior separately from package acceptance
Scenario and inputs. The target reports an accepted content operation. The operator now needs the actual normal-user boundary for the delivered application, using target-local Mohammad/Sara identities and their legitimate current contributions. Source-side group names and an administrator's preview are not target runtime proof.
Procedure. Read the target's current publications, native reference mappings and effective access. In a separately admitted ordinary-user exercise, cover employee submission, the exact manager task/action, an ungranted sibling object/workspace and applicable row/field/document restrictions. Use actual native result/receipt fields and current caller identity. Record served build, actor/fixture, state and relevant provider/template settings. Follow the current original UI recording/playback requirements if claiming product verification; do not relabel old or source-side media as a new target run.
Expected result. Package acceptance and runtime acceptance remain distinct. A successful target workflow can establish only its exact actor/build/fixture and affected dependencies. A denied or unavailable control stays correctly hidden/neutral according to current capability policy; a provider or template still needs its own current admission.
Failure and recovery. If a positive case fails, locate publication/reference/grant/native eligibility without granting all workspace permissions. If an exclusion fails, preserve the evidence and investigate the actual service boundary. This documentation program does not execute that live matrix and therefore leaves product/UI/provider verification NOT_RUN; source/schema parsing alone is not a substitute.
Sources. authorization-visibility-policy.md:1, application-user-access.md:1, task-persistence.md:1.
Milestone7 — Operate nodes and queues using observed ownership
Scenario and inputs. The application is in its intended operating state, but a notification or background action appears delayed. The operator has actual node/message administration authority and the original work identity. A healthy API page, active node heartbeat and successful release package answer different questions from queue ownership or a completed external effect.
Procedure. Read the actual node ID/roles and intended worker status; avoid assuming which backend a load-balanced /current call reached. Inspect the original queue row's due state, attempts, current lease owner/expiry and safe failure metadata. Correlate allowed trace/outcome identifiers through the relevant service logs. Use policy/status GETs before any maintenance action. Remember that a log-retention dry-run does not delete files but still writes a maintenance receipt and requires its own authority.
Expected result. The diagnostic record separates API serving, role/loop activation, transport reachability, current claim and native business outcome. It retains unknown remote effects instead of treating lease expiry as rollback. Operational log levels remain separate from durable append-only audit, and an administrative read does not authorize a queue replay or a node restart.
Failure and recovery. Do not start competing workers, mark another owner's message processed, globally kill browsers/services or delete retained evidence to force a clean result. Resolve the exact owning dependency/action, preserve original receipts and use a separately admitted drain/replay/retention plan only when legitimate. Current resource, CI and private/native/PR3228 holds remain unchanged.
Sources. NodeController.java:61, MessageController.java:1, OperationsController.java:149.