Projects · Developer workbook
Building Provider Notices
A developer workbook for the provider notices implementation guide
A developer workbook for the provider notices implementation guide
All eight chapters are written and wait for the owner’s review; none is approved yet. Chapter 08, the deployment runbook, hasn’t been run against a live tenant, account, tenancy or project. No chapter has a narrated tour yet. Every external claim was checked against the provider’s own documentation (Microsoft Learn for Azure and Microsoft 365, Oracle’s documentation for OCI, AWS’s for AWS Health, Google Cloud’s for Personalized Service Health), NIST’s OSCAL catalog or fedramp.gov on November 9, 2026, and each chapter keeps its verification log in the repository. The code is illustrative. Its tests pass against fictional fixtures and stand-in tools; it has not been run against a production tenant.
The Provider Notices implementation guide runs one job as seven gates: collect the notices each cloud provider publishes about the agency’s own estate, hold each one as a single record, give every notice that needs action an owner with a due date, put the rest in a weekly digest, and keep the evidence. It says what to configure, what the ISSO keeps and what each government cloud offers. It doesn’t teach anyone to build the software that does the reading, the routing and the record keeping.
This workbook is for the developers who build that software. It is code first, and it starts from each provider. Every chapter begins with what the provider documents (the API, the least-privileged reader, the government cloud), then walks through the code in the repository’s examples/provider-notices folder that reads it, with tests. Each has a lab that runs on a laptop against fictional fixtures with no tenant at all, then a short step in a test tenant, account, tenancy or project with a way to back it out. Each lists the facts the code depends on, footnoted to the provider’s own page with the date it was read, then the federal requirement the step supports, the KSI it aligns to and what the ISSO keeps, the dangers and a checklist.
The kit already exists: phase 1 of this work built it with the guide. The chapters don’t rebuild it; they explain it, run it and say where it stops. Where a lab turned up a fault in the kit, the kit was fixed in the same change, with a test.
The target estate is a civilian agency at FedRAMP Moderate in Microsoft 365 GCC with commercial Azure, with workloads in Oracle Cloud Infrastructure and possibly AWS or Google Cloud. GCC uses the worldwide Graph endpoint, graph.microsoft.com; GCC High and DoD have separate hosts.1 An agency whose HR platform runs on Oracle Cloud Infrastructure reads that tenancy’s announcements in Chapter 03, so platform maintenance reaches the HR system’s owners before it lands. Every tool takes an explicit cloud name for each provider and has no default.
The pieces and how they connect
| Piece | What it is | Where |
|---|---|---|
| Implementation guide | The seven gates: steps, federal requirements and evidence, government-cloud availability, interim paths, Validate and rollback | Provider Notices: An Implementation Guide |
| This workbook | One chapter per gate: the code the gate needs, labs, verified facts, evidence; and a runbook for test and production | This page and its eight chapters |
| Code | examples/provider-notices: four entry scripts, one PowerShell module with a collector and normalizer per provider, the router, the digest and the evidence chain, the runbook’s deploy/ scripts, fictional fixtures for two weeks, and 165 Pester tests (140 in tests, 25 in deploy/tests) |
examples/provider-notices |
| The task pattern | Ticket-to-Machine: the typed task, its lanes and the five clauses of the request chain | Book 13, Chapter 10 and Appendix B; Building Ticket-to-Machine |
| Training path | Nine modules, one per gate plus the why and an optional runbook module, each with a chapter’s Lab 1 and a knowledge check | Learning path: Provider Notices |
| The operations view | Why notices go unread, who owns each kind, from notice to task to closure, the weekly digest and the evidence, for the people who run day two | Book 15, Chapter 14 |
| Where the email goes today | Service health email routed to the help desk supervisor, and why nothing is approved on the strength of an email | Book 15, Chapter 03 |
| Your routing | Neutral templates and Microsoft 365 Copilot Chat prompts to write the agency’s own routing at work | templates/ and copilot-prompts.md |
How each chapter is built
| Section | What it holds |
|---|---|
| Goal and audience | What you will build, and who should read it |
| Start with the provider’s documentation | What the provider gives you, and what it leaves to you, as a table of gaps the kit’s tests pin |
| The code | What the kit does for this provider or step, and the tests |
| Lab 1: fixtures, no tenant | Commands you can run anywhere, with the output they gave when the chapter was written |
| Lab 2: a test tenant | The smallest step a test tenant, account, tenancy or project needs, and how to back it out; not run by the authors |
| Verified facts | Endpoints, least-privileged permissions, government-cloud availability and plan requirements, each footnoted |
| Federal requirements and evidence | The step, the requirement it supports, the KSI it aligns to, and what the ISSO keeps |
| Dangers | What breaks in production, and the guard the code has for it |
| Checklist | What a reviewer checks before the code ships |
Chapter 08 is built differently: it is a runbook, not a gate, so it has no labs. It takes the kit from the seven chapters to a live test environment and then to production, every step a command block, with its outputs shown from fixture mode and its live results written as expectations.
Design guidance in this workbook is marked as such: it is the program’s position, not a provider’s statement. Where a provider’s documentation didn’t settle a fact, the chapter says not yet specified and its verification log lists it.
Chapters
The outline follows the guide’s gates, in order. Chapters 01 to 05 are independent: read the providers the agency uses. Chapter 06 routes what they collect, Chapter 07 reports and records it, and Chapter 08 runs all of it, first in a test environment and then in production.
| # | Chapter | Gate | Starts from | What you build or run | Status |
|---|---|---|---|---|---|
| 01 | The notice record and Azure Service Health | G1 Azure | Learn’s Resource Graph samples for Service Health; the Service Health alert policy | The common record and its fingerprint, the Azure collector, and the alert policy as a plan applied only with its approved hash | Written; review pending |
| 02 | Microsoft 365 Message center and service health | G2 Microsoft 365 | Learn’s service communications API | The Graph reader on the tenant’s own host, and who said action is required | Written; review pending |
| 03 | Oracle Cloud Infrastructure announcements | G3 OCI | Oracle’s Announcements CLI and policy reference | The announcement reader, latest in each chain, with affected resources, and the realm guard | Written; review pending |
| 04 | AWS Health | G4 AWS | AWS Health API and its GovCloud page | The event reader in batches of ten, the support-plan error, and the partition guard | Written; review pending |
| 05 | Google Cloud Personalized Service Health | G5 Google Cloud | Google’s Personalized Service Health API | The incident reader, and the gaps: no planned maintenance, not in the Assured Workloads FedRAMP or IL packages | Written; review pending |
| 06 | Routing to owners and Ticket-to-Machine tasks | G6 Routing | The finding contract and the request chain | The routing file and its checks, task payloads, de-duplication across runs and the re-read rule | Written; review pending |
| 07 | The weekly digest and evidence | G7 Digest and evidence | The guide’s evidence table | The digest’s five sections, hashed and chained evidence records, and a stage’s coverage check | Written; review pending |
| 08 | Deploying to test and production | G1 to G7 | The guide’s gate order and rollback table | One settings file per environment, a pre-flight (PF-01 to PF-07), Stage 1 in a test environment with a staged enable, a smoke test and a rehearsed rollback, the go/no-go, Stage 2 in production, and the evidence | Written; not run against a live tenant |
Reading paths
- Anyone new to provider notices: Book 15’s Chapter 14 for why and who, then the guide.
- Developers new to the kit: the guide’s path on one page, then Chapter 01 for the record every provider fills.
- Developers who own one provider: Chapter 01’s record, then that provider’s chapter.
- Whoever runs the service desk and change process: Chapter 06, with Building Ticket-to-Machine for the receiving side.
- ISSOs and reviewers of the code: each chapter’s federal requirements and checklist, then Chapter 07.
- Whoever runs the change: Chapter 08, after every chapter’s first lab.
- Learners: the Provider Notices learning path, nine modules in the order of the guide’s gates, each with a chapter’s Lab 1 as its exercise and a knowledge check.
Where this workbook sits
This is the developer workbook for the Provider Notices implementation guide, one of the developer workbooks under Projects in the Federal Modernization Workbook. The operating model is Book 15’s Chapter 14, Provider Notices in Day-Two Operations: why notices go unread, who owns each kind, and how a notice becomes a task and closes. Book 15’s Chapter 03 routes the provider’s email today, and the guide replaces the email with the provider’s own API. The routing it builds is the Ticket-to-Machine pattern of Book 13.
Chapters
| Title | Description |
|---|---|
| Chapter 01 — The Notice Record and Azure Service Health | The one record every provider’s notice becomes, and the first collector that fills it: Azure Service Health read through Azure Resource Graph with Learn’s own sample queries, every event type mapped to a kind, retirements and security advisories made action required by a stated rule, impacted resources joined by tracking ID, a fingerprint that changes when the provider changes the notice and not when the kit reads it again, and Service Health alerts at scale through the built-in Azure Policy definition as a plan that applies only with its approved SHA-256. Labs against fixtures and an Azure test subscription. |
| Chapter 02 — Microsoft 365 Message Center and Service Health | Microsoft 365’s Message center posts and service health issues read through the Microsoft Graph service communications API, on the tenant’s own Graph host (GCC on the worldwide endpoint, GCC High and DoD on their own), with the two read permissions Learn names: posts tagged Retirement as retirements, plan-for-change and prevent-or-fix posts as changes, the provider’s action-required date kept as the provider’s, the kit’s own rule labeled as a rule, paging that refuses a next link on another host, and a session guard that refuses another cloud or tenant. Labs against fixtures and a Microsoft 365 test tenant. |
| Chapter 03 — Oracle Cloud Infrastructure Announcements | Oracle Cloud Infrastructure announcements read with Oracle’s own CLI and the one policy statement Oracle documents for reading them: the latest announcement in each chain, the details call for affected resources, announcement types mapped to the record’s kinds, Oracle’s own ACTION_REQUIRED and ACTION_REQUIRED_BY kept as the provider’s word, a rescheduled maintenance window replacing the original, and a realm guard that knows the US Government Cloud (OC2) endpoints and refuses OC3, whose endpoint is not yet specified. For an agency whose HR platform runs on OCI, this is how platform maintenance reaches the HR system’s owners first. Labs against fixtures and a test tenancy. |
| Chapter 04 — AWS Health | AWS Health events read through the AWS Health API with a customer managed policy holding three read actions (AWS publishes no read-only managed policy for Health): open and upcoming events, then descriptions and affected entities ten events at a time, event categories mapped to the record’s kinds, AWS’s own actionability kept as the provider’s word, retirements recognized by a stated kit rule, the support-plan requirement and its error, and a partition guard that sends GovCloud (US) reads only to the single endpoint in us-gov-west-1. Labs against fixtures and a test account. |
| Chapter 05 — Google Cloud Personalized Service Health | Google Cloud’s Personalized Service Health read for a project (or an organization) with the viewer role Google documents: every event an incident, because the API has one category and no planned maintenance; products and locations from the event’s impacts; a summary from the latest update; and two gaps recorded honestly, the missing maintenance and the product’s absence from the Assured Workloads FedRAMP Moderate, FedRAMP High, IL4 and IL5 packages, plus an organization-level call the kit runs only when told it is unverified. Labs against fixtures and a test project. |
| Chapter 06 — Routing to Owners and Ticket-to-Machine Tasks | Turning notices into work: a routing file the agency writes at work, checked before it runs; rules tried in order, first match wins; a ServiceNow-shaped Ticket-to-Machine typed task for each notice that needs one, with the finding contract’s severity, priority and response window, the provider’s own date kept apart, a de-duplication key and the five clauses of the request chain; state across runs, so an unchanged notice never makes a second task and a notice the provider stops listing asks for the re-read; contingency plan reviews flagged for retirements and maintenance; and sending only from the scheduled run, only when the settings allow it. Labs against fixtures and a ServiceNow developer instance. |
| Chapter 07 — The Weekly Digest and Evidence | What the owners read and what the ISSO keeps: a weekly digest in five sections (open notices by provider and kind, action required soonest first with the owner the routing named, maintenance and changes starting soon, what is new and what closed), and an evidence chain in which every run folder is checked against its manifest, copied, hashed and recorded with the steps it covers and their NIST SP 800-53 controls and FedRAMP 20x KSIs, each record carrying the hash of the one before, with a SHA256SUMS file the ISSO can check and a stage check that says which steps still lack a passing record. Labs against fixtures and a test run folder. |
| Chapter 08 — Deploying to Test and Production | A deployment runbook that takes the provider notices kit from the labs to a live test environment, then to production, with the same commands and one settings file per environment: a settings file with no secrets, a read-only pre-flight (PF-01 to PF-07), Stage 1 in a test environment with a staged enable (one provider at a time, each cross-checked against the provider’s own command), a smoke test (ST-01 to ST-04), the Service Health alert policy applied with its approved hash, the weekly run on a schedule, the evidence and a rehearsed rollback; the go/no-go criteria; and Stage 2 in production, with routing as a dry run for the first week before sending, the alert policy at the management group, first-week monitoring and a rollback. Every step is a copy-paste command; the deploy scripts each have a dry run. Nobody has run it against a live tenant. |
Version and revision history
This workbook has not been published in an edition yet. Each edition is kept, with its Word editions, decks and videos, on the Archive page. Every change so far is in the commit history.
Footnotes
Microsoft Learn, “National cloud deployments” (GCC continues using the worldwide endpoints), https://learn.microsoft.com/graph/deployments (read November 9, 2026; carried from the provider notices guide’s verification log).↩︎