Rhythm 2.0 Specifications

Appearance

CAP-PFM-QRY-006Save and share reusable questions

Markdown

CAP-PFM-QRY-006

Save and share reusable questions

Markdown
  • DocumentDraft
  • Product intentConfirmed
  • ImplementationObserved

Planning

Feature
FEAT-PFM-QRY-02
Exercised by
FAS-PFM-QRY-02-01, FAS-PFM-QRY-02-02, FAS-PFM-QRY-02-03, FAS-PFM-QRY-02-04, FAS-PFM-QRY-02-05, FAS-PFM-QRY-04-02, FAS-PFM-QRY-05-03
Key concepts
CON-PFM-QRY-002
Actors
ACT-PFM-013, ACT-PFM-014, ACT-PFM-007, ACT-PFM-015
Journeys
JNY-PFM-QRY-001, JNY-PFM-QRY-002
Depends on
CAP-PFM-QRY-002
Related
CAP-PFM-QRY-007, CAP-PFM-QRY-011, CAP-PFM-QRY-015
Proved by
ATS-PFM-QRY-006
Executed by
TST-PFM-QRY-149

Implementation

Executable suites
TST-PFM-QRY-231, TST-PFM-QRY-233, TST-PFM-QRY-234, TST-PFM-QRY-345, TST-PFM-QRY-349, TST-PFM-QRY-413

KindCapabilityProduct areaPlatformModuleQuestions, record exploration and data deliveryRevision1

Read atservices-platform ad3f6a65react-console baf6dae3

Save and share reusable questions ​

Purpose ​

Keep useful questions available to their authors and chosen audiences without extending anyone’s data permissions.

How It Works ​

Staff save a question under a name so they can return to it. The stored definition has an owner and an audience. Colleagues find only the queries their audience and library access permit. Reading a stored query reports problems that may now prevent it from running. Changing it validates the definition again for the saver. Customer managers maintain shared work while private work stays with its owner. Reports and schedules can depend on the query. Narrowing or deletion therefore checks those dependencies and explains what must be changed first.

Relationships ​

The saved-question library supplies definitions for execution, reports, dashboards and schedules.

The Formal Contract

The narrative above explains; the sections below are authoritative — the rules, scenarios and tests this document binds.

Outcomes
Stored questions can be reused.Customer-private work remains owner-only.Audience changes account for dependent reports.
Surfaces
consoleapi
Intent sources
services-platform:docs/queries/saved-queries-and-recipes.md#2026-10-11 — Final acceptance (after the requested change)services-platform:docs/milestones/plans/RPT-M1-plan.md#D2services-platform:docs/milestones/plans/RPT-M1-plan.md#D4services-platform:docs/milestones/plans/RPT-M1-plan.md#D10

Controls

28 controls apply, from the corpus control catalogue.

TC-AZ-001 TC-AZ-002 TC-AZ-003 TC-AZ-004 TC-AZ-005 TC-DAT-001 TC-DAT-002 TC-DAT-003 TC-DAT-004 TC-IAM-001 TC-IAM-002 TC-IAM-003 TC-IAM-004 TC-IAM-005 TC-IAM-006 TC-LOG-001 TC-LOG-004 TC-LOG-005 TC-PI-001 TC-PI-003 TC-PI-005 TC-TEN-001 TC-TEN-002 TC-TEN-003 TC-TEN-004 TC-VEN-001 TC-VEN-002 TC-VEN-003

Permissions

KeyChecked atScope
platform.saved-queries.readapitenant
platform.saved-queries.useapitenant
platform.saved-queries.shareservicerecord
platform.saved-queries.manageservicerecord
<application>.<dataset>.query (the owner's key)servicetenant

Business Rules

15 rules, 15 to be proved before approval. A rule's product intent is derived from its origin: 15 confirmed by a product decision, the rest inheriting this capability's confirmed.

IdRuleKindEnforced atProvenance
01must prove
Confirmed
A private saved query is visible only to its owner among customer users; colleagues and customer managers receive not-found responses.
origin: services-platform:docs/queries/saved-queries-and-recipes.md#2026-10-11 — Final acceptance (after the requested change)
proved by ATS-PFM-QRY-006-01, TST-PFM-QRY-234
permissionservicetest
services-platform:modules/queries/tests/e2e/saved-queries.e2e.spec.js#tells a manager the same thing, as 404
02must prove
Confirmed
Role-shared queries are visible to their owners, managers and current active holders of a selected role; other users neither list nor open them.
proved by ATS-PFM-QRY-006-02, ATS-PFM-QRY-006-17, ATS-PFM-QRY-007-12, TST-PFM-QRY-234
permissionservicetest
services-platform:modules/queries/tests/e2e/saved-queries.e2e.spec.js#answers not found for a role the caller does not hold, and excludes the record from the list [E2E-SQ-09]
03must prove
Confirmed
The library’s read permission allows listing, opening and running shared queries, while use is required for creation, replacement and deletion, so Read Only staff cannot write.
origin: services-platform:docs/milestones/plans/RPT-M1-plan.md#D10
proved by ATS-PFM-QRY-006-03, TST-PFM-QRY-231
permissionapitest
services-platform:modules/queries/tests/e2e/read-tier.e2e.spec.js#is refused creating a saved query with 403
04must prove
Confirmed
Changing between private and organization visibility requires share permission, which is included by default for users allowed to save queries.
origin: services-platform:docs/queries/saved-queries-and-recipes.md#2026-10-11 — Final acceptance (after the requested change)
proved by ATS-PFM-QRY-006-04, TST-PFM-QRY-234
permissionservicetest
services-platform:modules/queries/tests/e2e/saved-queries.e2e.spec.js#refuses making the query the organization’s without the power to share it as 403
05must prove
Confirmed
The owner can maintain a query, and managers can maintain shared queries, while customer managers cannot reach private queries.
origin: services-platform:docs/queries/saved-queries-and-recipes.md#2026-10-11 — Final acceptance (after the requested change)
proved by ATS-PFM-QRY-006-05, TST-PFM-QRY-234
permissionservicetest
services-platform:modules/queries/tests/e2e/saved-queries.e2e.spec.js#refuses a colleague editing the organization’s query as 403
06must prove
Confirmed
Rhythm staff using a workspace staff grant can read and maintain every saved query, including customer-private queries.
origin: services-platform:docs/milestones/plans/RPT-M1-plan.md#D4
proved by ATS-PFM-QRY-006-06, TST-PFM-QRY-413
permissionservicetest
services-platform:modules/queries/tests/unit/services/saved-queries/saved-query-access.spec.ts#lets staff write a colleague’s private query, which a non-staff caller may not
07must prove
Confirmed
Role sharing accepts one to one hundred distinct active workspace roles, replaces the complete selected set, and excludes archived roles from membership matches.
proved by ATS-PFM-QRY-006-07, TST-PFM-QRY-234
validationapi, servicetest
services-platform:modules/queries/tests/e2e/saved-queries.e2e.spec.js#replaces the whole selected-role set rather than appending to it [E2E-SQ-07]
08must prove
Confirmed
Query audience narrowing is refused when a dependent report or dashboard would have a wider audience, with the blocking reports and owners identified.
origin: services-platform:docs/milestones/plans/RPT-M1-plan.md#D2
proved by ATS-PFM-QRY-006-08, ATS-PFM-QRY-006-18, ATS-PFM-QRY-011-14, TST-PFM-QRY-231, TST-PFM-QRY-345
policyservicetest
services-platform:modules/queries/tests/integration/services/saved-queries/saved-query-narrowing.integration.spec.js#refuses narrowing it to private with 409 saved_query_narrower_than_reports, naming the report
09must prove
Confirmed
A save preserves omitted visibility and preserves existing role selections when role visibility is supplied without a replacement set.
origin: services-platform:docs/milestones/plans/RPT-M1-plan.md#D2
proved by ATS-PFM-QRY-006-09, TST-PFM-QRY-231, TST-PFM-QRY-345
policyservicetest
services-platform:modules/queries/tests/integration/services/saved-queries/saved-query-narrowing.integration.spec.js#keeps a role-shared query’s visibility and roles when the save states no visibility
10must prove
Confirmed
Saving validates the definition for the saver without running it, refusing unauthorized or missing datasets and collecting the remaining definition problems.
origin: services-platform:docs/queries/saved-queries-and-recipes.md#2026-10-11 — Final acceptance (after the requested change)
proved by ATS-PFM-QRY-002-18, ATS-PFM-QRY-005-18, ATS-PFM-QRY-006-10, ATS-PFM-QRY-008-11, TST-PFM-QRY-234
validationservicetest
services-platform:modules/queries/tests/e2e/saved-queries.e2e.spec.js#refuses a body whose definition cannot be run as written as 400
11must prove
Confirmed
The saved definition retains its exact values, fits within 64 KiB, and identifies the same dataset as its query record.
origin: services-platform:docs/queries/saved-queries-and-recipes.md#2026-10-11 — Final acceptance (after the requested change)
proved by ATS-PFM-QRY-006-11, TST-PFM-QRY-234
invariantservice, databasetest
services-platform:modules/queries/tests/e2e/saved-queries.e2e.spec.js#leaves a criterion’s value exactly as the person typed it, spaces and all
12must prove
Confirmed
Saved-query names are unique for each owner within a workspace after case and surrounding-space normalization, while other owners or workspaces can reuse them.
proved by ATS-PFM-QRY-006-12, TST-PFM-QRY-234
validationservice, databasetest
services-platform:modules/queries/tests/e2e/saved-queries.e2e.spec.js#refuses a create whose name normalizes to one the owner already has, naming the trimmed proposed name as 400 [E2E-SQ-01]
13must prove
Confirmed
Replacement requires the version previously read, rejects a missing version and reports a conflict when it is stale.
proved by ATS-PFM-QRY-006-13, TST-PFM-QRY-234
validationapi, servicetest
services-platform:modules/queries/tests/e2e/saved-queries.e2e.spec.js#refuses a replacement at a version that is no longer in force as 409
14must prove
Confirmed
A saved query used by a report, dashboard or schedule cannot be deleted, and the refusal identifies its dependencies.
origin: services-platform:docs/migrations/query-scheduling-exports/README.md#D3. A schedule runs a pinned copy of the saved query (snapshot), and says when the saved query has changed
proved by ATS-PFM-QRY-006-14, ATS-PFM-QRY-006-19, ATS-PFM-QRY-015-17, TST-PFM-QRY-233, TST-PFM-QRY-349
policyservice, databasetest
services-platform:modules/queries/tests/e2e/reports.e2e.spec.js#refuses to delete a saved query a report presents as 409 saved_query_reported
15must prove
Confirmed
Library pages, counts and facets exclude colleagues’ private queries, while opening a query reports its current reader-specific problems rather than rejecting the entire read.
proved by ATS-PFM-QRY-006-15, TST-PFM-QRY-234
policyservicetest
services-platform:modules/queries/tests/e2e/saved-queries.e2e.spec.js#leaves a colleague’s private query out of the numbered page too

Scenarios

IdGivenWhenThenProvenance
01A shared report depends on an organization-visible query.The author attempts to make the query private.The save is refused and the existing audience remains.test
services-platform:modules/queries/tests/integration/services/saved-queries/saved-query-narrowing.integration.spec.js#leaves the query as it was after the refusal
02A query has selected-role visibility.A save retains role visibility without supplying new roles.The stored role selection is preserved.test
services-platform:modules/queries/tests/integration/services/saved-queries/saved-query-narrowing.integration.spec.js#keeps the roles when the save states "roles" and no roleIds

The Markdown files under specs/ in rhythmsoftware/rhythm-v2-docs are the canonical source of truth. This reader is a generated, read-only projection of them.

Rhythm Software