Skip to content

docs: correct four known errors (group-status catalog, /dbfields writes, group-type change, provider link) #188

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
2000game merged 2 commits into from
Sep 26, 2026
Merged

docs: correct four known errors (group-status catalog, /dbfields writes, group-type change, provider link) #188

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6d84d16
docs: correct four known errors (group-status catalog, /dbfields writ…
2000game Sep 26, 2026
16571d0
docs(api-coverage): stop row 13 calling group statuses endpoint-less
2000game Sep 26, 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
5 changes: 3 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,8 +13,9 @@ code, and reconcile it against the ChurchTools API with Terraform-style
> **Frozen.** The TypeScript config DSL receives bugfixes only and is removed
> in ct-cli 5.0. Its successor is `terraform-provider-churchtools`, an
> OpenTofu/Terraform provider that replaces the state file with tfstate and the
> logical-key resolver with native resource references. Its repository is not
> public yet; this note will link it at the provider's first release.
> logical-key resolver with native resource references:
> [eqrm/terraform-provider-churchtools](https://github.com/eqrm/terraform-provider-churchtools)
> (public; first releases 2026-09).
>
> Migrating needs no re-adoption for the resource types the provider already
> covers: `ct export tf` generates HCL plus `import` blocks from your existing
Expand Down
36 changes: 18 additions & 18 deletions docs/api-coverage.md
View file
Open in desktop

Large diffs are not rendered by default.

4 changes: 3 additions & 1 deletion docs/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,9 @@ where it was used. Raw numeric ids remain a valid escape hatch everywhere; see
for a zero-numeric-id config.

**Exception: `groupStatusId` (a group's lifecycle status) is numeric-only,
always.** ChurchTools exposes no REST catalog to resolve a status by name
always.** ChurchTools does expose a read catalog (`GET /person/masterdata` →
`groupStatuses`: 1 active, 2 pending, 3 archived, 4 finished), but ct does not resolve
it by name yet (#157) — so a status still cannot be resolved by name
(`/group/memberstatus` is a different dimension, member statuses; #67), so a
`status:` declaration fails fast at eval time rather than resolving against the
wrong dimension.
Expand Down
2 changes: 1 addition & 1 deletion docs/group-field-decisions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ field — a plain top-level key. `campusId` is wired the same deliberate way as
| Field | Decision | Rationale |
| ---------------------------------------------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | **managed** | Core identity; already managed. |
| `groupTypeId` | **managed** | Determines the group's kind and role template; already managed. |
| `groupTypeId` | **managed** | Determines the group's kind and role template; already managed. **Changing it on an existing group is not a normal update:** ChurchTools rejects `groupTypeId` on the regular group update (`HTTP 400 groupTypeId: validation.always.invalid`) and requires `POST /groups/{id}/grouptype` with a role mapping. ct still plans it as a normal update, so the apply fails (#171). Until that is fixed, change a group's type in the ChurchTools UI and adopt the drift. |
| `groupStatusId` | **managed** | Lifecycle status; already managed. |
| **`campusId`** | **managed (new, #21)** | The campus link is the tool's core "instantiate this area per campus" requirement. Numeric escape hatch only — an existing CT campus id (or `null` to clear). A _logical_ `campus: "key"` reference (resolving a same-run campus by key) is **deferred to [#20](https://github.com/eqrm/ct-cli/issues/20)**; the DSL rejects a `campus` field with a pointer to #20 so it can't slip through as an un-diffable phantom. |
| `parents` (hierarchy) | **opt-in synthetic** | Group→group hierarchy is reconciled through its own endpoint, not the group body — see `src/engine/synthetic.ts`. Opt-in via `parents: [...]`. |
Expand Down
4 changes: 2 additions & 2 deletions docs/handbuch/dynamic-groups.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -305,7 +305,7 @@ At **capture** time (`ct adopt … --with-dynamic`) the state file and the
```text
! rulesets/jugend.json keeps 5 host-specific id(s) — NOT portable to another host:
ctgroup.id: 1246 left numeric — not under management — `ct adopt group <id>` for each (then re-adopt) makes them portable
ctgroup.groupStatusId: 1, 2 left numeric — group statuses have no REST catalog (#67) — no logical form exists
ctgroup.groupStatusId: 1, 2 left numeric — no logical form yet; the catalog is `/person/masterdata` → `groupStatuses` (#157)
person.id: 5703, 4389 left numeric — person ids are NEVER portable — ct does not manage people, so this ruleset names DIFFERENT people on another host. Remove the clause or accept the divergence
```

Expand Down Expand Up @@ -346,7 +346,7 @@ reason it never checked:
The capture-time reasons are distinct because the fixes are: an **unmanaged**
target (adopt it), a **role unknown to `/group/roles`**, a role whose **group
type is unmanaged**, or a dimension with **no logical form at all**
(`ctgroup.groupStatusId` — group statuses have no REST catalog, #67; this one
(`ctgroup.groupStatusId` — no logical form yet, although `/person/masterdata` carries the catalog, #157; this one
needs no lookup, so the plan-time scan reports it too).

**`--strict-rulesets`** turns the warning into a refusal: adopt writes nothing
Expand Down
21 changes: 14 additions & 7 deletions docs/handbuch/field-definitions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -88,7 +88,14 @@ Evidence:
`churchtools-api` tested @ CT 3.104, bensteUEM `ChurchToolsAPI` @ CT 3.101)
and the ChurchTools Academy docs. **Re-verify** against a freshly generated
schema per the re-audit procedure in `docs/runbook-manual-surface.md`.
2. **The REST field-definition resource is GET-only.** Every public client

> **Update 2026-09-26:** the eqrm prod OpenAPI spec now lists REST writes on field definitions —
> `POST /dbfields`, `PUT`/`DELETE /dbfields/{fieldId}`, `POST /dbfields/{fieldId}/options`,
> `PUT`/`DELETE /dbfields/{fieldId}/options/{optionId}`. Points 2–3 below describe the state when
> this page was written. The endpoints are **not live-tested**, and the tool still treats data fields
> as read-only: promoting the resource is the follow-up this section describes at its end.

2. **The REST field-definition resource was GET-only.** Every public client
exposes data fields solely as `GET /dbfields` (list) and `GET /dbfields/{id}`
(by id). No REST `POST`/`PUT`/`PATCH`/`DELETE` on a field-definition path
exists in any of them.
Expand Down Expand Up @@ -117,12 +124,12 @@ re-deciding rather than merely re-reading.

## Endpoint reference

| Purpose | Path | Methods (this CT) | `ct` surface |
| ------------------------------------------ | ------------------------------------------------------------------------------ | --------------------------------------- | --------------------------------------------------- |
| Person master-data model + security levels | `/person/masterdata` | GET (read-only) | `ct get person-masterdata` |
| Security levels, standalone | `/securitylevels`, `/securitylevels/{id}` | GET; POST/PATCH/DELETE on the item path | `ct get security-levels`, `ct.securityLevel` (#110) |
| Data-field definitions (person + group) | `/dbfields`, `/dbfields/{id}` | GET (read-only) | `ct get data-fields` |
| Field-definition **mutation** | legacy `churchdb` AJAX (`db_insertfields`/`db_updatefields`/`db_deletefields`) | non-REST | **not managed — manual** |
| Purpose | Path | Methods (this CT) | `ct` surface |
| ------------------------------------------ | ------------------------------------------------------------------------------ | ------------------------------------------ | --------------------------------------------------- |
| Person master-data model + security levels | `/person/masterdata` | GET (read-only) | `ct get person-masterdata` |
| Security levels, standalone | `/securitylevels`, `/securitylevels/{id}` | GET; POST/PATCH/DELETE on the item path | `ct get security-levels`, `ct.securityLevel` (#110) |
| Data-field definitions (person + group) | `/dbfields`, `/dbfields/{id}` | GET (writes in spec since 2026-09, unused) | `ct get data-fields` |
| Field-definition **mutation** | legacy `churchdb` AJAX (`db_insertfields`/`db_updatefields`/`db_deletefields`) | non-REST | **not managed — manual** |

All paths verified against public CT client libraries + CT Academy docs, **not**
against this repo's (git-ignored, ungenerated) `src/api/schema.d.ts`.
Loading
Loading