Immutable reference baselines¶
Reference baselines are created and read in the Web client. Windows preserves their project data but has no dedicated baseline interface.
A reference baseline captures requirements and the test library together under a name. Subsequent changes or deletion of the originals do not change its saved content. You can inspect it and compare it with today's contents of the same scope, for example before and after revising a product feature.
A baseline is an immutable reference point. It is not an electronic signature, content approval or automatic release acceptance. Test case versions capture individual normal test cases; a release comparison evaluates test results.
Prerequisites and permissions¶
Creation requires an active project account with the administrator role, or the project manager role with permission to edit project settings. You must also be able to read the entire selected scope. This includes linked objects and parent sources whose names, inherited contents or files are captured. Insufficient permissions reject creation rather than silently producing an incomplete baseline.
Reading, comparing and downloading files recheck current permissions. Creating a baseline does not grant permanent special access. If a required original no longer exists or a project's identity has changed in a copy, only project administrators can read the saved baseline. Revoking permissions can therefore remove a previously visible baseline from the list and block known detail or download links.
Capture a baseline¶
- Open Reference baselines in the Web project. You can also reach the page from the test library and requirements.
- Enter a meaningful name and reason, such as “Checkout before revision” and why this reference point is needed.
- Select the requirement scope: all requirements, or a folder, document or chapter together with its descendants.
- Independently select the complete test library or a test unit with its descendant units and cases. A requirement link does not automatically expand that selection to include other test cases.
- Review both scopes and explicitly confirm the immutable capture. Open the saved baseline and check its objects and files.
Name, reason, author, capture time and scope are retained with the content. This version provides no editing, restoration or deletion of individual baselines. Creation does not change originals, test case versions, plans, runs or results.
If the application reports a concurrent change, reload the sources and review the request again. If size limits are exceeded, select a smaller scope; a truncated partial baseline is never saved.
Saved contents and files¶
A baseline includes the selected structure and order, descriptions, custom fields with their definitions, inherited content effective at capture, and requirement-to-test-case links. Normal test cases include their variants, steps, expected results and reusable step blocks. Quick test cases additionally include field definitions, rows, cells and row attributes.
Stored attachments and embedded images are retained with their bytes independently of the originals. This includes captured inherited attachments and files in Quick cells. Files already missing at capture are explicitly marked as missing. External file links remain references: their targets are neither downloaded automatically nor archived as file copies. Historical previews do not fetch external images. Password fields are excluded.
Limits are 100 MB per file and 256 MB for all saved files combined. The application also limits the number of objects and content size. Back up the complete project: historical file contents belong to the project database. A spreadsheet or text export does not replace that backup.
Compare with the current scope¶
Open a saved baseline and request a comparison with current content. The overview distinguishes added, removed, changed and unchanged objects. Detailed differences show old and current values, including links, variants, order and files.
The comparison resolves the saved scope again against today's project. A newly added child is therefore included in the current comparison; an object moved out of the scope is treated as removed. A deleted scope root never expands the comparison to the whole project. That side of the current scope is empty instead, and its saved objects appear as removed. The Web view displays a warning. Because the source was deleted, only project administrators can read that historical baseline. Current contents must also be readable in full.
Example: capture a requirements document and the “Checkout” test unit. Then change a test step, remove a requirement link and add a Quick test case inside the unit. The comparison shows field differences for the changed case and the new Quick test case as added. The saved baseline retains the original step and link. Comparison does not apply any changes to the library or test planning.
MCP and REST¶
The APIs use the same project and object permissions as Web. The project.library-baseline.read capability requires project API access and current read permissions; no additional read-scope grant is required. REST exposes the tools as POST /api/v1/operations/<tool name>; see the REST chapter for authentication and project routing. Availability depends on the installed server version.
| Tool | Inputs and result |
|---|---|
ztm_library_baseline_options |
Read permitted requirement/test-unit scopes and creation availability |
ztm_library_baseline_list |
Read visible baselines with skip and take (maximum 100); HasMore indicates another page |
ztm_library_baseline_read |
baselineId: read saved contents and asset metadata without file bytes |
ztm_library_baseline_compare |
baselineId: compare with current contents of the saved scope |
ztm_library_baseline_asset |
baselineId, assetId: read a stored file up to 512 KiB; Content is Base64-encoded |
Authorized users download larger files through the authenticated Web download. APIs do not fetch external references either.
A comparison also reports deleted scope roots in MissingScopeRoots. This warning distinguishes a missing scope from an existing scope that contains no objects.
Creation requires the explicitly granted project.library-baseline.create write capability and enabled write actions. Call ztm_project_action_prepare with this capabilityId, your own idempotencyKey and, for example, these arguments:
{
"name": "Checkout before revision",
"reason": "Jointly confirmed reference point for the revision",
"scope": { "requirementType": "", "requirementId": 0, "testUnitId": 0 },
"operationId": "b7830698-beb9-4a89-a3c3-cf1a07543ee9",
"scopeConfirmed": true
}
An empty requirementType with requirementId: 0 selects all requirements. Otherwise use ReqFolders, ReqDocuments or ReqChapters with an ID returned by scope options. testUnitId: 0 selects the entire library. The responsible user must actually select and confirm the name, reason and both scopes; scopeConfirmed does not replace that decision.
Review the preview, then explicitly confirm it through ztm_project_action_commit with the same capabilityId and returned previewToken. Preparing alone does not save a baseline. The authenticated user is the author. Preserve operationId for retries; changed contents with the same ID are rejected. Retries also recheck current permissions. General write permission does not enable editing, restoring or deleting reference baselines.
Open from Windows¶
In Windows, right-click a library test unit, requirement folder, requirement document or requirement chapter and choose Open reference baselines on the web. The selected scope is preselected for creation. Opening the page does not create a baseline; Web checks permissions again.
Your authenticated Windows session signs you in automatically. Only if the handoff fails does the sign-in page appear; the destination is retained.
Impact of a requirement change¶
Use a saved baseline in the change-impact view to compare a requirement chapter with its current content and associated readable tests. Analysis does not create a retest.
Adopt standards from another project¶
In the Web client, you can adopt an explicitly selected reference baseline from another accessible project as local normal test cases. Choose Project standards in the test library header, or Import reference baseline in its import/context menu. Read-only users can compare; missing write permissions appear as blockers and prevent application. The ordinary project import remains available: it copies the current source contents without establishing a controlled relationship to a historical baseline.
- Choose the source project, a readable reference baseline and the destination folder. Select individual normal cases or test units with their descendant units and cases. The expanded selection can contain up to 200 units and cases combined; overlapping selections count each object once. Selecting a baseline does not approve or publish its contents.
- Choose how to handle matching names and review the preview, including target paths, final names, affected local cases and blockers. Adoption uses saved contents and files; subsequent live changes in the source do not replace them.
- When adopting a newly selected baseline later, the preview distinguishes source changes, local changes and changes on both sides. Local changes are retained by default. Choose Replace local changes only for the individual case you have reviewed, then choose Review decisions to prepare a new preview. Text is never merged automatically.
- Confirm Apply after reviewing the preview. Open the saved local cases from the receipt and check their contents and files after reloading.
Selected test units are created beneath the destination folder with their saved names and historical hierarchy, including empty units. Later moves in the source do not change that historical structure. Units serve as containers; their own source descriptions, attributes, attachments and permissions are not copied. Previously mapped target units are reused on repeat imports and are not renamed or moved to follow later source changes.
The copy has its own local identities, normal variants, independent files and test-case versions. Repeating the same completed operation does not create another copy. A later explicit update retains the mapped target case's identity. Templates and open runs keep their existing copies; synchronize those separately when required. Source ACLs, user accounts, credentials and foreign requirement or dependency links are not imported as local relationships.
The imported normal case offers Source and update. Open its origin, explicitly select the readable baseline you want to compare and choose Compare. Without current source access, only a generic origin hint remains; the local case is still usable. Original name additions, including a collision suffix assigned during import, are retained during case updates; new prefixes and suffixes apply to new copies. Moved local cases retain their target folder. Deleted or copied targets are never remapped by matching their names.
You need a genuinely mapped active user in the source project, read access to the entire selected baseline and the appropriate target permissions. Creating a case and updating an existing case require separate permissions. Missing source access must not silently reduce the selection. A new adoption rechecks and reads the authorized source when execution starts, then performs the local target change. There is no shared transaction across both projects. Losing source access later does not remove legitimately saved local contents; exact replay checks current target access and reveals no additional source information.
Older baselines without saved stable object identities or required historical field and variant definitions cannot be used for this controlled workflow. Capture a new complete baseline in the source instead of presenting current definitions as historical ones. Quick test cases and variants with an active test-data binding are excluded from this workflow. Nonportable contents or files appear as blockers in the preview; the confirmed selection is not partially applied. Windows can use the resulting local cases as ordinary test cases; controlled adoption and comparison use the Web client.
Handle matching names¶
The name decision applies to new objects in the same target folder, separately for test units and test cases:
- Import: Create an independent copy with the same name; an existing object with that name is not overwritten.
- Skip: Omit the conflicting object. For a unit, this skips its entire selected subtree, including cases already mapped within it.
- Rename: Use an available name with a suffix such as “(2)” or “(3)”. The preview shows the final name.
Existing origin mappings are recognized by identity. Their updates still follow individual local-change decisions; matching names never establish a mapping. A selected nonportable case remains a blocker even with Skip and stops the whole adoption. If the target changes after preview, review a new preview.
Attributes, images and limits¶
Portable attributes include free text and clearly defined single-line or multiline text fields, integers, dates, checkboxes, single-choice or multiple-choice lists and simple HTML fields. Required fields are matched unambiguously by name, type and saved definition, or created locally with the necessary management permissions. Inherited values effective at capture are saved as independent local values without further inheritance. Updates change the imported fields specifically; additional local attributes are retained.
Password values are not transferred. SQL fields, buttons, menus and link field types are excluded from this controlled workflow. Older baselines without complete historical field definitions require a new capture; current definitions are never substituted. Images in HTML attribute values and variant definitions are copied independently when the preview confirms they are portable. Images in an attribute definition's default values are currently an explicit blocker. A blocker stops the whole confirmed selection.
Open from Windows¶
In Windows, right-click the target test unit and choose Open project standards in Web. The Web workflow preselects that target. Your existing authenticated Windows session signs you in; if the handoff fails, Web sign-in retains the destination. The project-wide visibility setting for optional Windows Web entries can hide this menu item. Adoption and comparison have no separate Windows editor; the resulting local cases remain normal Windows test cases.
MCP and REST for controlled adoption¶
The read capability is project.standards.read. ztm_project_standards_lookup returns authorized choices with kind: sources, baselines, targets, items or units. Baselines require sourceProjectId; cases and historical units also require sourceBaselineId. Use skip for paging; query is allowed only for sources and targets, and take (1–100) only for cases and units. Project paths and foreign user IDs are not inputs.
ztm_project_standards_preview compares an explicitly selected set without saving. Supply sourceProjectId, sourceBaselineId, your own operationId, targetTestUnitId and items, each with a distinct sourceTestCaseId. Each case may set replaceLocalChanges, which defaults to false; set it to true only after reviewing that specific replacement. Optional namePrefix and nameSuffix are limited to 100 characters each. Use sourceTestUnitIds to additionally select historical units with their subtrees. A unit-only selection still requires items as an empty array. The expanded selection is limited to 200 cases and units combined. conflictHandling accepts import (default), skip or rename. Preview and receipt additionally include Containers; case previews expose TargetPath and TargetTitle. General write authorization does not decide the selection or individual replacements.
To apply, pass the same arguments to ztm_project_action_prepare with capabilityId: project.standards.apply and your own idempotencyKey. Review the returned preview, then confirm with ztm_project_action_commit, the same capability and its previewToken. The durable receipt identifies authorized local targets and applied revisions. Repeats retain the same operationId and contents; changed arguments are not replay. Target identities that are no longer readable remain hidden on repeat requests.
The receipt records who applied the import and when (UTC). For each created or updated case, it counts copied variants and file references (including inline images), and source requirement links and dependencies omitted from the copy. Older receipts may omit these details.
ztm_project_standards_receipt reads the signed-in user’s saved receipt by operationId without reopening the source. Current target permissions filter target references; a missing operation is reported as not found.
Additional reads support later updates:
| Tool | Usage |
|---|---|
ztm_project_standards_imported |
List readable local standards with optional targetTestUnitId, query, skip and take (1–200, default 50). Hidden source references are omitted. |
ztm_project_standards_origin |
testCaseId: read local provenance. Source project, baseline and case details appear only with current source access; otherwise a generic origin hint remains. |
ztm_project_standards_compare |
sourceProjectId, sourceBaselineId and 1–200 distinct targetTestCaseIds: compare already local cases with an explicitly selected source baseline without writing. Absence from that baseline does not automatically mean deletion. |
For a targeted update, an items entry may additionally contain targetTestCaseId. That local case must match its recorded origin; an arbitrary target ID cannot establish a relationship. This also lets you address a local case after it has been moved. Review the comparison and individual replacement decision again before Prepare/Commit.
REST exposes the same tools through POST /api/v1/operations/<tool-name>. Current project/object permissions, API-key scopes, enabled write actions and demo restrictions apply as in the Web client; see the REST chapter. Available operations depend on the installed server version.
Resuming after a process terminates¶
For controlled standards adoption, VistaDB modifies a temporary complete database copy and replaces the original file only after successful completion. This requires available database access and additional disk space for the entire database plus imported files and versions. If another access holds the database open, the application reports it; close that access and retry the request.
A process termination before file replacement leaves the previous database state intact. After replacement, the change and receipt are saved; retry with the same operation ID to retrieve the stored result. This protection applies to controlled standards adoption and does not repair an already damaged database. If a database conflict persists, ask your administrator to inspect the state after taking a backup; no automatic repair is performed.