Add office-scoped user-list API and management UI by krowvin · Pull Request #1734 · USACE/cwms-data-api

krowvin · 2026-05-15T22:14:29Z

Summary

Adds the complete, authenticated CDA user-list feature for office-scoped recipient groups:

office-scoped user-list metadata CRUD
list membership read and management endpoints
candidate-member lookup
owner and office authorization behavior
schema/feature gating for installations without the database objects
Groundwork-styled CDA UI for creating, editing, and deleting lists and managing members
ADR documenting the CDA user-list context, ownership, office scope, API, and UI decisions

Related Issue

Database foundation: HydrologicEngineeringCenter/cwms-database#160. Two follow-up database commits for office scoping and CDA grants remain local for review before a separate database PR.

Validation

latest origin/develop fetched and merged: already up to date
:cwms-data-api:integrationTests --tests cwms.cda.api.users.UserListControllerTestIT: 5 passed
:cwms-data-api:test --tests cwms.cda.features.CdaFeatureManagerProviderTest: 6 passed with the local runtime feature override isolated
CDA UI npm run lint: passed
CDA UI source Prettier check: passed
CDA UI npm run build: passed
broad Gradle build completed compilation, WAR packaging, and the bundled UI build; its unit-test phase still reports unrelated existing Windows/JDK 21 fixture and Mockito failures

Screenshots

Checklist

AI tools used

krowvin · 2026-05-15T22:14:36Z

Drafting until DB changes are in. Did one endpoint to start so i can check performance of the endpoints as I go.

MikeNeilson

Seems like a reasonable start.

MikeNeilson · 2026-05-18T19:48:17Z

        crud("/users/{user-name}", new UsersController(metrics), adminRoles);
        get("/roles", new GetRolesController(metrics), adminRoles);
        get("/user/profile", new UserProfileController(metrics), userRoles);
+        get("/user/list/{user-list-id}/members", new UserListMembersController(metrics), adminRoles);


long term, I'd probably group these by "/user/list" rather that method -> "/user/..."

But that's just me.

krowvin · 2026-06-02T21:47:50Z

Added the next user-list GET endpoint under /user/list:

GET /user/list/{user-list-id}?office={office}

Returns metadata for a single office-scoped user list

Separate from the existing members endpoint.

EDIT: Going to resolve conflicts at the end when it's ready for merge (not draft)

krowvin · 2026-07-24T16:37:15Z

Spoke with Mike N on 07/24/2026

Needs to be behind a feature flag (togglez) to make sure the DB has it. This will make it not show it in swagger. and a proper unsupported response. Minimum schema version enum.

Also to go ahead and PR this to have all the GET/POST/DELETE/etc for one larger review.

All the user stuff should have add user handlers/function for grouping so things are more clear.

Signed-off-by: Charles Graham, SWT <charles.r.graham@usace.army.mil>

krowvin · 2026-07-31T15:48:10Z

Added office scoped list CRUD and member management endpoints
Added owner/office authorization and candidate member lookup
Added the requested togglz/schema version gate, including unsupported schema handling and hiding unavailable endpoints from openapi
Added the authenticated CDA UI for creating, editing, deleting, and managing list members using Groundwork styling
Added an ADR covering ownership, office scope, API behavior, and UI decisions
Updated the branch onto current develop

Signed-off-by: Charles Graham, SWT <charles.r.graham@usace.army.mil>

Signed-off-by: Charles Graham, SWT <charles.r.graham@usace.army.mil> # Conflicts: # cwms-data-api/src/main/java/cwms/cda/helpers/DatabaseHelpers.java

krowvin · 2026-08-04T15:48:55Z

Related Batch Events follow-up: USACE-WaterManagement/cwms-batch-events#186

This draft consumes PR 1734's office-scoped CDA user-list API/UI so script administrators can select maintained recipient lists for failed-job email alerts. Batch Events resolves current membership at failure time instead of duplicating users locally.

MikeNeilson

Otherwise looks good.

while i would like to see pages/user-lits/index.jsx broken down into smaller components, i wouldn't consider it super critical right now. but open an issue to track that work.

The test changes should be done, there already exists an annotation to do what you're doing with the schema version check.

MikeNeilson · 2026-08-05T13:13:32Z

+    let detail = `${response.status} ${response.statusText}`.trim();
+    try {
+      const payload = await response.json();
+      detail = payload.message ?? payload.detail ?? detail;


what didn't return JSON? if it's the API itself something is wrong.

or is this just a bit of paranoid just in case... which yeah, probably a good idea.

bit of paranoid just in case

The gateway won't return a valid JSON if the API is down. It's a guard to make sure something can always render. I'm trying to be better at not assuming the API will always return valid...

MikeNeilson · 2026-08-05T13:34:49Z

This should be broken up into smaller components, overall everything does seem fine, but it's difficult to follow the logical structure of what's rendering by code alone (err, harder than it should be.)

Thanks, that was much easier to follow.

MikeNeilson · 2026-08-05T13:42:26Z

+public final class UserListDao {
+
+    private final DSLContext dsl;
+    private final Table<?> avUserListMembers = table(name("CWMS_20", "AV_USER_LIST_MEMBERS")).as("ulm");


The table and field definition can be static.

Additionally, as they are reused in different places they should be declared in their own classes. I would follow a style at least similar to the JOOQ auto generated output so that transitioning to the next code gen will be a bit easier.

MikeNeilson · 2026-08-05T13:47:12Z

+
+    @BeforeAll
+    static void ensureUserListSchema() throws SQLException {
+        if (!schemaSupportsUserLists()) {


Use the @MinimumSchema annotation on the class level

MikeNeilson · 2026-08-05T13:47:46Z

+    @AuthType(user = TestAccounts.KeyUser.SPK_NORMAL2)
+    void test_user_lists_are_unsupported_on_older_schemas(String authType,
+            TestAccounts.KeyUser user, RequestSpecification authSpec) {
+        assumeTrue(getSchemaVersion() < V2026_07_16.numeric());


use @MinimumSchema annotation at the class level.

oh wait, for this we would need a maximum schema. this particular one is fine for the moment.

Signed-off-by: Charles Graham, SWT <charles.r.graham@usace.army.mil>

krowvin · 2026-08-05T15:19:01Z

I put a TODO in there for the maximum comment. Do we have a pending issue to add that feature?

MikeNeilson · 2026-08-05T15:45:48Z

Thanks, that was much easier to follow.

MikeNeilson · 2026-08-05T15:49:18Z


    public static int getSchemaVersion() {
+        if (cwmsDb == null) {
+            // Class-level execution conditions run before the database container starts.


... I keep forgetting about that. But the fix for that is definitely beyond the scope of this PR.

MikeNeilson · 2026-08-05T15:50:39Z

I put a TODO in there for the maximum comment. Do we have a pending issue to add that feature?

We don't, I only just realized we needed it looking at your code.

## Summary - Load deployed Keycloak settings at runtime from the OpenAPI document instead of eagerly reading build-time Vite variables. - Keep the CDA GUI available when OpenID configuration is missing or invalid, and show a controlled sign-in-unavailable state. - Add a true application-level React error boundary and correct the React Router error fallback to use `useRouteError()`. - Share OpenID/Keycloak parsing between the application auth provider and Swagger UI, with focused regression tests. ## Related Issue Follow-up to #1734. The user-list UI introduced an app-wide `createKeycloakAuthMethod()` call during `main.jsx` module evaluation. The deployable production-mode bundle does not define `VITE_AUTH_HOST`, so Groundwork received `host: undefined` and failed on `host.trim()` before React or the router error boundary could render. This left the CWBI dev UI on a white error page. ## User Impact CDA now derives authentication configuration from the deployment's own OpenAPI document. If the deployment does not advertise usable OpenID configuration, public CDA pages remain available and authenticated features explain that sign-in is unavailable instead of crashing the entire application. ## Validation - `npm run test` — 4 tests passed - `npm run lint` - `npm run build` using Vite production mode - Repeated test, lint, and production build in an isolated `npm ci --ignore-scripts` installation using the locked Groundwork 3.9.0 dependency - Loaded the production artifact locally in a browser with unavailable OpenID configuration; verified the CDA introduction page rendered, the sign-in-unavailable state appeared, the page was not blank, and the console had no errors ## Checklist - [x] AI tools used --------- Signed-off-by: Charles Graham, SWT <charles.r.graham@usace.army.mil>

krowvin linked an issue May 15, 2026 that may be closed by this pull request

Add API support for managing and retrieving user lists #1733

Closed

MikeNeilson reviewed May 18, 2026

View reviewed changes

krowvin requested a review from MikeNeilson June 2, 2026 21:48

This was referenced Jul 24, 2026

Due Q2 2027 - Add Alert & Ad-Hoc (email) Queue USACE-WaterManagement/cwms-batch-events#157

Open

Add User List Management User Interface to CDA-UI #1847

Open

krowvin added 13 commits July 25, 2026 16:41

Add user list members endpoint (#1733)

0cc538c

Add user list metadata endpoint

71a0d61

Gate user list endpoints by schema support

99c6b99

Signed-off-by: Charles Graham, SWT <charles.r.graham@usace.army.mil>

Complete user list metadata CRUD

3fd984c

Signed-off-by: Charles Graham, SWT <charles.r.graham@usace.army.mil>

Add user list membership management

31f00dc

Signed-off-by: Charles Graham, SWT <charles.r.graham@usace.army.mil>

Document CDA user list architecture

f7bdd16

Signed-off-by: Charles Graham, SWT <charles.r.graham@usace.army.mil>

Complete office-scoped CDA user lists

e1be441

Add authenticated user list management UI

956d775

Signed-off-by: Charles Graham, SWT <charles.r.graham@usace.army.mil>

Allow bearer headers in CDA browser requests

873dcea

Enable local authenticated CDA user-list UI

0575f7f

Polish user list management with Groundwork

3a9d24a

Improve CDA user list management UX

555260a

Add contextual help to user lists

3e058f4

krowvin force-pushed the 1733-user-lists branch from 257c9e0 to 3e058f4 Compare July 27, 2026 03:31

krowvin changed the title ~~Add initial user-lists API endpoint~~ Add office-scoped user-list API and management UI Jul 27, 2026

krowvin added 2 commits July 31, 2026 16:23

Fix user list CI coverage and OpenAPI contracts

30bb58b

Signed-off-by: Charles Graham, SWT <charles.r.graham@usace.army.mil>

Merge remote-tracking branch 'origin/develop' into 1733-user-lists-ui

dd88fd8

Signed-off-by: Charles Graham, SWT <charles.r.graham@usace.army.mil> # Conflicts: # cwms-data-api/src/main/java/cwms/cda/helpers/DatabaseHelpers.java

krowvin mentioned this pull request Aug 4, 2026

Add failed-job email notifications using CDA user lists USACE-WaterManagement/cwms-batch-events#186

Open

krowvin marked this pull request as ready for review August 4, 2026 21:39

MikeNeilson requested changes Aug 5, 2026

View reviewed changes

krowvin added 3 commits August 5, 2026 09:36

Split user list UI into focused components

e2b90f9

Signed-off-by: Charles Graham, SWT <charles.r.graham@usace.army.mil>

Centralize user list JOOQ definitions

c3ef527

Signed-off-by: Charles Graham, SWT <charles.r.graham@usace.army.mil>

Use schema annotations for user list tests

77d90e5

Signed-off-by: Charles Graham, SWT <charles.r.graham@usace.army.mil>

krowvin requested a review from MikeNeilson August 5, 2026 15:18

MikeNeilson approved these changes Aug 5, 2026

View reviewed changes

krowvin merged commit 934bcad into develop Aug 5, 2026
7 of 11 checks passed

krowvin deleted the 1733-user-lists branch August 5, 2026 16:33

This was referenced Aug 5, 2026

Add @MaximumSchema support for integration tests #1863

Open

fix: prevent CDA GUI auth bootstrap crash #1865

Merged

Uh oh!

Conversation

krowvin commented May 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Related Issue

Validation

Screenshots

Checklist

Uh oh!

krowvin commented May 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

MikeNeilson left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

krowvin commented Jun 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

krowvin commented Jul 24, 2026

Uh oh!

krowvin commented Jul 31, 2026

Uh oh!

krowvin commented Aug 4, 2026

Uh oh!

MikeNeilson left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

krowvin Aug 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

krowvin commented Aug 5, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

MikeNeilson commented Aug 5, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

krowvin commented May 15, 2026 •

edited

Loading

krowvin commented May 15, 2026 •

edited

Loading

krowvin commented Jun 2, 2026 •

edited

Loading

krowvin Aug 5, 2026 •

edited

Loading