Volunteer Engagement V2 - EDM + SPA by Roman-Pilip · Pull Request #41 · microsoft/Nonprofits

Roman-Pilip · 2026-06-11T08:17:38Z

No description provided.

Add deployment, security, operations, and migration checklists plus a documentation improvement plan under VolunteerEngagement/docs. Simplify the top-level README and align titles, link text, and cross-references across docs. Fix incorrect Prettier/.editorconfig notes in the Portal src coding-guidelines README and remove the obsolete Power Pages 9.7.4.x prerequisite.

Restructure the Volunteer Engagement README to match the other solution READMEs (intro, capability bullets, Common Data Model connective paragraph, Deploy and Use sections). Remove the Contents table and overlapping headings.

- Add proactive guidance rule for provisioning/migration flow - Add environment selection, JS upload unblocking, site reactivation, restart, and URL lookup instructions - Fix restart script to pick newest site instance when multiple exist for the same websiteRecordId

lukasdominms · 2026-06-12T06:46:45Z

@@ -0,0 +1,119 @@
+# Volunteer Engagement AI instructions


This is focused only on upgrade path. We should also consider vanilla new deploy path.

Added changes to instructions

lukasdominms · 2026-06-12T06:50:10Z

+The SPA uses:
+
+- npm, not Bun.
+- Node.js `>=20.18.1 <25`.


Node 24 Active Support Ends in 4 months (20 Oct 2026)
I'd consider upgrade or at least not to cap the version.

Node 24 is active LTS but we should not limit it by < 25
Added changes

- Delete stale bot-setup.md (superseded by site-agent-setup.md) - Add site-agent-setup.md with correct powerpages-site-agent:* script references - Add site agent scripts: patch-roles, customize-ve-vm, configure-advanced - Update deployment-validation.md with site agent flow - Update README and package.json with new script names

…ntrolled format string' Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>

- Add new deployment section with instruction file references to README.md - Cross-reference deployment-validation.md from spa-development.md - Remove Node.js <25 upper cap from package.json and spa-development.md

lukasdominms · 2026-06-12T06:55:03Z

+npm run sync
+```
+
+Use PAC CLI to select the target environment:


Maybe also state the minimal pac version to avoid potential missing features

Added/kept PAC CLI minimum version guidance: 1.44.x or later, matching Microsoft’s SPA code-site docs

lukasdominms · 2026-06-12T07:06:33Z

+- Do not migrate site settings by default. Classify them and require review.
+- Do not copy authentication configuration, secrets, or tenant-specific values.
+- Preserve least privilege for web roles, table permissions, Web API fields, and bot visibility.
+- Prefer React, TypeScript, Fluent UI v9, and the existing `Portal-EDM` service patterns over legacy Liquid or Bootstrap implementation details.


We repeat some same info over and over on different places. Can you ask AI to consolidate information presented in instructions/docs?

Consolidated duplicated AI guidance. Removed stale nested AI guidance and merged useful coding/project rules into the root AI guidance. Removed the obsolete documentation improvement plan.

lukasdominms · 2026-06-12T07:22:46Z

@@ -0,0 +1,58 @@
+# Volunteer Engagement Documentation Improvement Plan
+
+Keep the Volunteer Engagement documentation simple, task-focused, and easy to maintain. The documentation should help a reader choose the right path, complete the setup, validate the site, and find official Microsoft guidance when they need more detail.


This sounds like an AI instructions, not the actual docs

lukasdominms · 2026-06-12T07:35:35Z

@@ -0,0 +1,65 @@
+# Volunteer Engagement Operational Notes


Another separate docs. Can we consolidate them?

Removed the plan-like docs artifact and kept human docs task-focused: deployment, migration, security, and operations. AI-specific behavior remains in AI instruction files.

lukasdominms · 2026-06-12T08:07:02Z

High generate-snippets.ps1:37 advertises non-English snippet generation through -Language, but snippet IDs are generated only from the localization key at generate-snippets.ps1:149-170. That means MSVE_SPA/Common/Save gets the same deterministic GUID for en-US, fr-FR, de-DE, and every other language. I verified the current en-US snippet ID for MSVE_SPA/Common/Save is exactly the GUID produced from the key-only seed. Creating a non-English variant through this script can therefore collide with the English Content Snippet primary key during upload, or overwrite/update the wrong record. Include the language in the GUID seed for non-English snippets while preserving existing en-US IDs.

Fixed. English snippets preserve their existing deterministic IDs. Non-English snippets now include the language code in the deterministic GUID seed, avoiding collisions across languages.

lukasdominms · 2026-06-12T09:57:35Z

Localized snippet ID generation should include the language code in the deterministic ID input. Using only the snippet key can cause ID collisions between default-language and localized snippets.

Fixed. Localized snippet ID generation now includes the language code in the deterministic ID seed for non-default languages, so localized snippets no longer collide with the default-language snippet IDs.

lukasdominms · 2026-06-12T09:58:19Z

The script output should include enough context to diagnose multi-site issues, such as the selected website ID, selected language record ID, language code, and number of pages/snippets created or updated for that website.

Fixed. The localization script now prints the target context it resolved and the work it performed, so multi-site/language issues are easier to diagnose.

lukasdominms · 2026-06-12T10:46:37Z

We shouldn't include those hardcoded (our) GUIDs

Some GUIDs are required Power Pages metadata IDs, so they cannot all be removed from .powerpages-site

lukasdominms · 2026-06-12T11:37:23Z

Localization workflow does not validate runtime bootstrap, only metadata presence

The validation flow can report snippet coverage while the actual portal runtime still cannot use those snippets. In the test, the cs-CZ snippets existed, but the page did not contain #ve-bootstrap-data, so the SPA loaded html lang="cs-CZ" but still initialized as __VE_LOCALE = "en-US". The check should include a runtime/template validation step, or at least verify that the active page template emits the bootstrap element expected by portalBootstrap.ts.

Runtime bootstrap validation: added to check-strings.ps1 and documented.

lukasdominms · 2026-06-12T11:38:37Z

The documented localization path does not account for synced Enhanced sites using generic templates

After syncing the Enhanced site, the local metadata reflected the actual runtime shape: a generic Default studio template with the SPA HTML in page copy. The localization scripts cloned snippets and content pages, but did not detect that the runtime template was missing the VE bootstrap required by the SPA. The instructions should call out this post-sync verification explicitly, because a successful sync/add-language/deploy/restart sequence is not enough to prove the portal will render localized UI.

lukasdominms · 2026-06-12T12:42:24Z

The Power Pages template renders the SPA shell twice.
MSVE_Home.webtemplate.source.html:35-37 already injects
, /assets/index.js, and then appends {{ page.adx_copy }}. However, the content pages store the full Vite document in adx_copy, including another module script and another #root, for example Home.webpage.copy.html:2-14. This produces invalid nested HTML, duplicate id="root" elements, and duplicate asset/script tags on each page. In the Power Pages runtime this is fragile and can cause double initialization or unexpected DOM/asset behavior. Either the template should stop rendering page.adx_copy, or the page copy should not contain the full built index.html.

Fixed
Good catch

Roman-Pilip · 2026-06-15T07:41:48Z

Duplicate SPA shell: fixed by making MSVE_Home the single owner and clearing built Vite HTML from page copies.
Localization language lookup: fixed by scoping to target website record ID and failing on ambiguous/missing matches.
Localized snippet GUID collision: fixed by language-aware deterministic IDs for non-English while preserving en-US.
Runtime bootstrap validation: added to check-strings.ps1 and documented.
Node/PAC wording: aligned.
Docs/AI duplication: consolidated, with useful guidance merged into root .ai.
First-install deployment flow: corrected to deploy → reactivate manually → sync → restart → validate, after your point about reactivation.

lukasdominms · 2026-06-15T11:47:43Z

The post-deploy scripts currently depend on Get-AzAccessToken, which ties them to the caller’s global Az PowerShell context. That makes the deploy fragile when PAC is authenticated to one environment but Az PowerShell is logged into a different tenant/account.

A simpler and more portable fix would be to use Azure CLI for Dataverse tokens instead, with an optional override for custom CLI wrappers.

Then normal users can rely on their default az login, while test/CI environments can set AZ_CLI to an isolated wrapper without changing global Az PowerShell state.

Done. Get-DataverseAccessToken now prefers Azure CLI (az account get-access-token) so the token follows the same account used for deploy, with an AZ_CLI env override for isolated CI wrappers, and falls back to Az PowerShell when CLI isn't present. Also consolidated the three duplicated fallback helpers so all deploy/permissions/site-agent scripts use the single shared function. Verified it returns a valid token via the CLI path and falls back correctly when AZ_CLI is invalid.

lukasdominms · 2026-06-15T11:53:03Z

npm run deploy rewrites generated assets under [.powerpages-site/web-files] and also normalizes [Home.webpage.copy.html]. These files are currently tracked, so a fresh deploy leaves the working tree dirty even when the user did not make source changes.

Can we avoid tracking generated Vite/PAC output here, or adjust the deploy flow so it does not mutate tracked metadata? If these files are meant to be generated from dist, adding .gitignore alone will not be enough because they are already tracked; they would need to be removed from the index as well.

Fixed. Untracked the generated Vite bundle web-files index.html, index.css, index.js, vendor-*.js and added them to .gitignore. Authored stock assets (favicon, theme, profile, etc.) stay tracked. Root cause is pac rewriting an environment-specific annotationid into each .webfile.yml on every upload — the bundle churn is now gone. If you want zero churn on the remaining authored .webfile.yml too, I can add a .gitattributes clean filter that strips annotationid on checkin — say the word.

lukasdominms · 2026-06-15T12:24:57Z

+
+For a fresh deployment, run `npm run deploy` after the target environment and prerequisites are ready. The command builds the SPA and uploads the code site by using `powerpages.config.json`.
+
+After the initial deployment, the site can appear in Power Pages under **Inactive sites** and does not have an assigned, usable URL until it is reactivated. In [Power Pages](https://make.powerpages.microsoft.com/), open the target environment, select **Inactive sites**, select the Volunteer Engagement site, and then select **Reactivate**. Do not run `npm run site:restart`, rely on PAC/API portal URLs, or start browser validation until reactivation is complete. For more information, see [Reactivate sites](https://learn.microsoft.com/en-us/power-pages/admin/reactivate-website).


Fresh pac pages upload-code-site creates the Dataverse website metadata, but it does not create/activate the running Power Pages host URL. After upload, the site exists as an inactive code site, so the Power Platform websites API can still return an empty list until the host is provisioned/reactivated.

The README mentions the manual Power Pages UI reactivation step, but for automated/test deployments we should document or script the Admin API equivalent:

POST https://api.powerplatform.com/powerpages/environments/{environmentId}/websites?api-version=2024-10-01

with the existing Dataverse websiteRecordId in the request body. That completes the second phase by creating the actual Power Pages host.

Looked into scripting this. Reactivation is intentionally a manual maker step: it's where the web address/subdomain is chosen, and there's no supported public API for it — the official create-code-sites and reactivate-website docs only describe the UI flow. The internal api.powerplatform.com/.../websites POST isn't documented for code sites, and in testing it created duplicate host instances for the same websiteRecordId. So we're keeping reactivation manual and documented rather than scripting a POST that risks duplicate hosts.

… web-files Get-DataverseAccessToken now prefers az CLI with an AZ_CLI override and Az PowerShell fallback, and the duplicated fallback helpers in the site-agent and permission scripts were consolidated to use it. Untrack the generated Vite bundle web-files (index.*, vendor-*) and gitignore them; npm run deploy recreates them from dist.

Add a Localization section to Portal-EDM README documenting the scripts/localization helpers, trim redundant deploy wording, and align the deployment checklist with the localized-site string check.

Roman-Pilip added 4 commits June 10, 2026 16:01

Update Volunteer Engagement v2 assets and documentation

d59d66c

Fix Portal EDM audit vulnerabilities

87754eb

Align Volunteer Engagement docs assets

978048a

Roman-Pilip assigned vuhrova and lukasdominms Jun 11, 2026

github-advanced-security AI found potential problems Jun 11, 2026

View reviewed changes

Comment thread VolunteerEngagement/Portal-EDM/src/services/apiClient.ts Fixed

Roman-Pilip changed the title ~~Users/romanpilip/v ev2~~ Users/romanpilip/VEv2 Jun 11, 2026

Roman-Pilip changed the title ~~Users/romanpilip/VEv2~~ Volunteer Engagement V2 - EDM + SPA Jun 11, 2026

Roman-Pilip added 2 commits June 11, 2026 17:00

Simplify bot setup: auto-provisioned and auto-bound after first deploy

42f8487

lukasdominms reviewed Jun 12, 2026

View reviewed changes

Roman-Pilip and others added 4 commits June 12, 2026 11:04

Potential fix for pull request finding 'CodeQL / Use of externally-co…

8419530

…ntrolled format string' Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>

Address PR #41 review: add new deploy path, remove Node.js cap

b764113

- Add new deployment section with instruction file references to README.md - Cross-reference deployment-validation.md from spa-development.md - Remove Node.js <25 upper cap from package.json and spa-development.md

Improve Volunteer Engagement setup and migration docs

5d1e5fc

lukasdominms requested changes Jun 12, 2026

View reviewed changes

lukasdominms reviewed Jun 12, 2026

View reviewed changes

Address PR 41 review feedback

5cd7b61

Roman-Pilip added 6 commits June 15, 2026 09:43

Add dynamic CSP patch for site agent

6a7e5ba

Avoid name fallback for site resolution

dce7dd8

Document first-session authorization validation

daf1ceb

Remove duplicate Home page shell

4c14d17

Allow PAC-generated Home page copy

9234270

Correct patching bot roles

7219e3e

lukasdominms reviewed Jun 15, 2026

View reviewed changes

Roman-Pilip added 3 commits June 15, 2026 15:40

Align auth prompts and portal metadata

3d95b91

docs: surface localization scripts and tighten deploy guidance

9c78a73

Add a Localization section to Portal-EDM README documenting the scripts/localization helpers, trim redundant deploy wording, and align the deployment checklist with the localized-site string check.

		@@ -0,0 +1,58 @@
		# Volunteer Engagement Documentation Improvement Plan

		Keep the Volunteer Engagement documentation simple, task-focused, and easy to maintain. The documentation should help a reader choose the right path, complete the setup, validate the site, and find official Microsoft guidance when they need more detail.


		For a fresh deployment, run `npm run deploy` after the target environment and prerequisites are ready. The command builds the SPA and uploads the code site by using `powerpages.config.json`.

		After the initial deployment, the site can appear in Power Pages under Inactive sites and does not have an assigned, usable URL until it is reactivated. In [Power Pages](https://make.powerpages.microsoft.com/), open the target environment, select Inactive sites, select the Volunteer Engagement site, and then select Reactivate. Do not run `npm run site:restart`, rely on PAC/API portal URLs, or start browser validation until reactivation is complete. For more information, see [Reactivate sites](https://learn.microsoft.com/en-us/power-pages/admin/reactivate-website).

Conversation

Roman-Pilip commented Jun 11, 2026

Uh oh!

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!

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!

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Roman-Pilip Jun 15, 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!

Roman-Pilip commented Jun 15, 2026

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!

lukasdominms Jun 15, 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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Roman-Pilip Jun 15, 2026 •

edited

Loading

lukasdominms Jun 15, 2026 •

edited

Loading