Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
23 commits
Select commit Hold shift + click to select a range
fc4a4ef
drafts: private means zoned exactly [userId]; a superset-zoned elemen…
dwolfson Nov 14, 2026
f3f89b2
paging G2-G4: one version gate per upstream fix; #9454 trusts get_rel…
dwolfson Nov 15, 2026
7389f39
paging G2 R1: the Overview's relationship scans pass their client to …
dwolfson Nov 15, 2026
ccf264e
Map Dr.Egeria Project Scope to ProjectProperties.scope (PY-5 / EG-14)
dwolfson Nov 15, 2026
405e1cb
Restore the report-spec seed manifest to upstream's census (378 runna…
dwolfson Nov 15, 2026
4674027
Spec cache: fetched_refusal gets the None-identity guard; document sh…
dwolfson Nov 15, 2026
50314e5
Send defaultValueOverride when the target type declares it (PY-4)
dwolfson Nov 15, 2026
8bd2753
Authoring validate: the find method must fit the target type, and col…
dwolfson Nov 15, 2026
a344e61
Strict validation: Project scope is accepted; the test derives its od…
dwolfson Nov 15, 2026
c598313
Release notes: the Properties catalog is regenerated from Egeria c61b…
dwolfson Nov 15, 2026
7ff3b3a
PY-18: drafts are listed by type with the author's zone, never by a "…
dwolfson Nov 15, 2026
30b3f32
PY-17: a find run's count says "at least N" unless confirmed; MCP rep…
dwolfson Nov 15, 2026
85105e4
fix(dr-egeria): Limit Result by Status is a list of element statuses;…
dwolfson Nov 15, 2026
41f192f
docs: Dr.Egeria techniques and best practices; status filters; effici…
dwolfson Nov 15, 2026
4b2eccd
paging: #9454 release floor is 6.3.0 (G3 passed against the V6.3 tag)
dwolfson Nov 16, 2026
ca93542
fix(status values): REJECTED, not REJECTED_FOR_DEPLOYMENT; seed activ…
dwolfson Nov 16, 2026
55fb4d3
docs(release notes): next.md lists only what is new since 6.2.42
dwolfson Nov 16, 2026
3a16bcb
PY-21: keep the seed specs generated; fix FOR_INFO at its source later
dwolfson Nov 16, 2026
f6e3851
docs/deprecation: "the next release", not "pyegeria 7 (expected early…
dwolfson Nov 16, 2026
b674c66
docs/deprecation: "pyegeria 6.4 or the next release", not just "the n…
dwolfson Nov 16, 2026
0521acd
docs(release notes): on Egeria 6.3, find counts can be incomplete ("a…
dwolfson Nov 16, 2026
533acd5
docs(release notes): which 6.3 counts are trusted, and what they leav…
dwolfson Nov 16, 2026
f9c135c
chore(release): bump version to 6.3.0
dwolfson Nov 16, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions commands/cat/load_report_specs.py
Original file line number Diff line number Diff line change
Expand Up @@ -3,10 +3,10 @@
SPDX-License-Identifier: Apache-2.0
Copyright Contributors to the ODPi Egeria project.

DEPRECATED command name, kept until pyegeria 7: it now runs the spec cache's sync
DEPRECATED command name, kept until pyegeria 6.4 or the next release: it now runs the spec cache's sync
(pyegeria.view.egeria_spec_cache.sync_report_specs, the same as `pyegeria report-specs sync`), which
loads the report specs held in Egeria into the cache the registry's EGERIA tier reads. It used to run
the legacy ReportType:: loader (load_egeria_report_specs), deprecated and removed in pyegeria 7.
the legacy ReportType:: loader (load_egeria_report_specs), deprecated and removed in pyegeria 6.4 or the next release.

Usage (standalone):
load_report_specs [--force] [--ttl <seconds>]
Expand Down Expand Up @@ -46,7 +46,7 @@ def _run(
) -> None:
console = Console(width=width, force_terminal=not jupyter)
# The owner's direction (2026-11-14): our own callers move off the deprecated legacy ReportType:: loader
# (load_egeria_report_specs, removed in pyegeria 7). This command now runs the spec cache's sync, the
# (load_egeria_report_specs, removed in pyegeria 6.4 or the next release). This command now runs the spec cache's sync, the
# system of record for Egeria-held report specs, exactly as `pyegeria report-specs sync` does.
console.print(DEPRECATION_WORDS)
if force or ttl_seconds is not None:
Expand All @@ -72,7 +72,7 @@ def _run(

#: Printed by load-report-specs / load_report_specs since it moved to the spec cache.
DEPRECATION_WORDS = ("[yellow]load-report-specs is deprecated[/yellow]: it ran the legacy ReportType:: loader, "
"which will be removed in pyegeria 7 (expected early January 2027). It now runs the spec "
"which will be removed in pyegeria 6.4 or the next release. It now runs the spec "
"cache's sync (`pyegeria report-specs sync`), which loads Egeria-held report specs.")


Expand All @@ -83,7 +83,7 @@ def _run(
def load_status_words(status: dict, elapsed: float, new_specs: list) -> str:
"""Words for how the deprecated load_egeria_report_specs ended (85f5bc15 read-back R1): one sentence per
status, never "no ReportType collections" unless Egeria confirmed the end. Kept for anyone still calling the
legacy loader until pyegeria 7; this command itself now runs the spec cache's sync."""
legacy loader until pyegeria 6.4 or the next release; this command itself now runs the spec cache's sync."""
kind, count = status.get("status"), status.get("count") or 0
retry_at, error = status.get("retry_at"), status.get("error")
if kind in ("loaded", "registered_unconfirmed") and not count:
Expand Down
4 changes: 2 additions & 2 deletions docs/design/report_spec_migration_design.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# Design: Migrating Report Specs to Egeria

> **Superseded loader (2026-11-14).** `load_egeria_report_specs()`, the loader this document describes, is the
> legacy path for the May-2026 `ReportType::` collections. It is **deprecated and will be removed in pyegeria 7
> (expected early January 2027)**. Egeria-held report specs are `ReportSpec::` elements, and they load through
> legacy path for the May-2026 `ReportType::` collections. It is **deprecated and will be removed in pyegeria 6.4 or
> the next release**. Egeria-held report specs are `ReportSpec::` elements, and they load through
> the spec cache: `pyegeria.view.egeria_spec_cache.sync_report_specs` (`pyegeria report-specs sync`), the system of
> record. It reads both markers and serves the registry's EGERIA tier, the consumer index and the authoring API.
> pyegeria's own callers have moved: the MCP server's startup and the `load_report_specs` / `hey_egeria ...
Expand Down
48 changes: 41 additions & 7 deletions docs/dr_egeria_manual.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,23 +13,24 @@ Dr.Egeria is a Markdown-based processing engine for Egeria. It allows users to i
- [Directives](#directives)
- [Planned Elements](#planned-elements)
- [Reference Resolution](#reference-resolution)
4. [Supported Command Families](#supported-command-families)
5. [CLI Utility: dr_egeria](#cli-utility-dr_egeria)
4. [Techniques and Best Practices](#techniques-and-best-practices)
5. [Supported Command Families](#supported-command-families)
6. [CLI Utility: dr_egeria](#cli-utility-dr_egeria)
- [Running a folder: dr_egeria_folder](#running-a-folder-dr_egeria_folder)
- [The `_batch.json` manifest](#the-_batchjson-manifest)
- [Automatic loading in the Egeria Portal](#automatic-loading-in-the-egeria-portal)
6. [Python API](#python-api)
7. [Python API](#python-api)
- [process_md_file (synchronous)](#process_md_file-synchronous)
- [process_md_file_v2 (async)](#process_md_file_v2-async)
7. [Supporting Utilities](#supporting-utilities)
8. [Supporting Utilities](#supporting-utilities)
- [Template Generation (`gen_md_cmd_templates`)](#template-generation-gen_md_cmd_templates)
- [Help Documentation (`gen_dr_help`)](#help-documentation-gen_dr_help)
- [Command Search (`dr_egeria_help`)](#command-search-dr_egeria_help)
- [Report Specification (`gen_report_specs`)](#report-specification-gen_report_specs)
- [Spec Validation (`validate_compact_specs`)](#spec-validation-validate_compact_specs)
- [Migration Tool (`migrate_dr_egeria.py`)](#migration-tool-migrate_dr_egeriapy)
8. [Advanced Configuration](#advanced-configuration)
9. [Jupyter Notebook Support](#jupyter-notebook-support)
9. [Advanced Configuration](#advanced-configuration)
10. [Jupyter Notebook Support](#jupyter-notebook-support)

---

Expand All @@ -44,7 +45,7 @@ Dr.Egeria utilizes a specific header hierarchy to distinguish between document c
### Document Structure

- `# Title`: Single-hash headers are reserved for document titles and narrative text. Dr.Egeria ignores these during command processing but preserves them in the output.
- `---` or `___`: Horizontal rules are used as optional delimiters between command blocks.
- `---` or `___`: Horizontal rules end a command block. Between two commands they are optional, because the next `##` header also starts a new block, but a command followed by prose must end with one: otherwise any `###` heading in the prose is read as an attribute of the command. See [Techniques and Best Practices](#techniques-and-best-practices).
- **Bullet Points**: Dr.Egeria supports both `*` and `-` for list-style attributes on input. For generated output, it defaults to using `-` for better compatibility with various Markdown editors.

### Command Blocks
Expand Down Expand Up @@ -247,6 +248,39 @@ In the SDK, `with pyegeria.lineage_visible():` applies the same `forLineage=true

---

## Techniques and Best Practices

These rules follow from how the parser (`md_processing/v2/extraction.py`) reads a document. They matter most in long documents that mix commands with prose, such as tutorials, and in documents that are loaded more than once, such as Portal bootstrap batches.

### How a document is read

The document is cut into **blocks**. A new block starts at every line that begins with `# ` or `## `, and at every line that is only `___` or `---`. Code fences are not recognised: a fence line is ordinary text.

A block is a **command** if its first non-blank line matches `Verb Object`, with or without a leading `## `, where Verb is one of: Add, Attach, Cancel, Classify, Clear, Count, Create, Declassify, Delete, Detach, Display, Find, Import, Initiate, Link, Process, Provenance, Publish, Reclassify, Remove, Run, Search, Set, Setup, Unlink, Update, Validate, View (case-insensitive). Every other block is prose and is copied to the output unchanged.

Inside a command block, every `### ` heading is an attribute, up to the end of the block, and the lines below it, up to the next `###`, are its value.

### Rules that follow

- **End every command with `___`.** Prose after a command is part of its block until the next block boundary, so a prose `###` heading becomes an attribute of the command.
- **Don't start a `##` heading, or the first line after a separator or heading, with a verb** unless it is a command. `## Process Parameter Time Series` is read as the command *Process* on *Parameter Time Series*, and logs `No processor registered for 'Process Parameter Time Series'`. Use `#` or `###` for such headings, or reword them.
- **Fenced commands run.** A command inside a ```` ```markdown ```` fence, or any other fence, is executed. End a runnable fenced command with `___` before the closing fence, or the fence line becomes part of the last attribute's value. To show a command that must not run, write it as `## <Verb> <Object>`, or indent it below a line of prose in the same block. An indented command straight after a separator is still a command.
- **Attributes are headings.** A `Key: value` line is not an attribute. Before the first `###` it is ignored, and after one it becomes part of that attribute's value.
- **Validate before processing.** References to elements created earlier in the same document show as not found during `--validate` (see [Planned Elements and Forward References](#planned-elements-and-forward-references)). On `--process` the commands run in order, so they resolve.

### Re-running documents

- `Create` and `Update` commands upsert by qualified name, which is derived from the display name and the command's type unless given. Renaming an element, or changing its type (for example `Create Agreement` to `Create Digital Subscription`), therefore creates a second element on a repository that is already loaded.
- `Link` commands handle an existing relationship in different ways. `Link Report to Dashboard Sheet` replaces an existing placement, and `Link Governance Results` skips a pair that is already linked. Before relying on a re-run, check what the command does; a folder that uses one that adds a relationship on every run should set `"idempotent": false` in its [`_batch.json`](#the-_batchjson-manifest).

### Status filters

`Limit Result by Status` filters on element status, Egeria's `ElementStatus`: `UNKNOWN`, `ACTIVE`, `INVALID`, `DELETED` or `OTHER`. Empty or `ACTIVE` returns elements that aren't deleted, `DELETED` returns soft-deleted elements, and `ACTIVE, DELETED` returns both. It is validated locally, and lifecycle values such as `DRAFT` produce a warning.

Lifecycle states are filtered with `Limit Result by Content Status` (`ContentStatus`), `Limit Result by Deployment Status` (`DeploymentStatus`) and `Limit Result by Activity Status` (`ActivityStatus`). Each reaches Egeria only through a report whose find method has the matching `content_status_list`, `deployment_status_list` or `activity_status_list` parameter. For any other report it is dropped with a warning. See [search-and-get-filters.md](search-and-get-filters.md).

---

## Supported Command Families

Dr.Egeria organizes its commands into "families," each corresponding to a specific area of metadata management. You can discover all available commands for each family using the `gen_md_cmd_templates` and `gen_dr_help` utilities.
Expand Down
Loading
Loading