Downtime notifications

Last Updated: October 27, 2025

Downtime Notifications are a mechanism for handling outages of external services in the consuming front-end applications.

Overview

Downtime notifications allow VFS applications to display user-facing messaging when dependent external services are unavailable.

How it works

• A maintenance window is created in PagerDuty.

• vets-api polls PagerDuty for active windows and caches results.

• Frontend applications call /maintenance_windows/ to get this data.

• The DowntimeNotification component determines if any declared dependencies are affected.

  • If so, the UI displays a modal (approaching) or banner (active).

Common downtime states

• More than 1 hour before start → application renders normally.

• Within 1 hour before start → a dismissible modal shows upcoming downtime.

• While active → a banner replaces the app content to indicate maintenance.

Endpoints for scheduled and current windows

• Staging: https://staging-api.va.gov/v0/maintenance_windows/

• Prod: https://api.va.gov/v0/maintenance_windows/

System flow (end-to-end)

[PagerDuty Maintenance Window]
        ↓
[vets-api polls PD + caches data]
        ↓
[/v0/maintenance_windows endpoint]
        ↓
[Frontend DowntimeNotification component]
        ↓
[Banner or Modal shown to user]

Configure in code (no manifest)

Downtime notifications are configured directly in your app code.

Configuration sources

Frontend: configure downtime in code via DowntimeNotification (no app manifest flags).

Service IDs: add PagerDuty service IDs in vets-api. See: How to add a new PagerDuty service section below.

import DowntimeNotification, { externalServices } 
  from '@department-of-veterans-affairs/platform-monitoring/DowntimeNotification';

<DowntimeNotification
  appTitle="Example tool"
  dependencies={[externalServices.mvi, externalServices.vaProfile]}
>
  {children}
</DowntimeNotification>

Frontend guidance

• Choose services from externalServices.js that your feature depends on.

• Set appTitle to a clear name used in messaging (e.g., “Appointments tool”).

• Keep page headings and breadcrumbs outside DowntimeNotification so they remain visible during downtime.

• Optionally, use the render prop or a lightweight banner component (components/Banner.jsx) for custom display.

• Platform handles global downtime; apps typically specify only dependencies and appTitle.

Forms library applications

If your application is a Forms library app, add a downtime block to your form configuration.

import { externalServices } from 'platform/monitoring/DowntimeNotification';

formConfig.downtime = {
  dependencies: [externalServices.evss, externalServices.emis, externalServices.mvi, externalServices.vaProfile],
  requiredForPrefill: true,
};

Behavior

• When requiredForPrefill is true:

  • If logged in and any dependencies are down → downtime message is shown before form load.

  • Saved forms cannot be submitted during downtime.

• When false (default):

  • The downtime message only appears before submission.

To show downtime notices on both intro and review pages, wrap FormStartControls and SubmitController in DowntimeNotification.

Migrating from the legacy application-manifest setup

If your documentation or code still references adding PD service IDs in the application-manifest repo, migrate to:

1. Frontend → use DowntimeNotification in code (no manifest flags).

2. Service IDs → store PD service IDs in vets-api (settings.yml / Parameter Store) per environment.

- downtime: ['evss', 'mvi']
+ import { externalServices } from 'platform/monitoring/DowntimeNotification';
+ <DowntimeNotification dependencies={[externalServices.evss, externalServices.mvi]}>

Then, remove any downtime keys from your manifest once converted.

Staging PagerDuty service (why and when)

Use a staging PagerDuty service to safely test downtime banners in http://staging.va.gov without notifying real Veterans.

• Validate end-to-end alert flow and UI behavior in staging.

• Iterate quickly without risk to production.

How to add a new PagerDuty service

If your backend introduces a new external service, register it with PagerDuty and vets-api.

1. Create the service in PagerDuty

   • Log in to PagerDuty (requires ECC PagerDuty access).

   • Create a new service.

   • Use naming convention:

     • External: <ServiceName> for production

     • Staging: External: <ServiceName> for staging

2. Add the service to vets-api

   • If you only have a production service, add the service ID to settings.yml in the maintenance.services section. (Also add the key to development.yml and test.yml.)

     • In this case, it’s okay to hardcode the PagerDuty ID. See documentation for more info on adding settings in vets-api.

   • If you have both a production and staging service, add the IDs to Parameter Store. See documentation.

     • In this case, IDs are stored in Parameter Store and read via ENV in vets-api.

     • You’ll need a variable for each env (dev, staging, sandbox, and prod). Use the staging ID for dev and staging, and the production ID for sandbox and prod.

Verification

Local

• Stub /maintenance_windows/ to include your external_service.

• Confirm banner states for declared dependencies.

• Check that your external_service key matches the frontend’s externalServices key.

Staging

1. Create a short (15 min) maintenance window in your staging PD service.

2. Maintenance window is listed here: https://staging-api.va.gov/v0/maintenance_windows/

3. Verify the following behaviors:

   • Approaching: within = 1 hour → modal appears.

   • Down: during active window → banner appears, children hidden.

   • Clear: after end → normal render resumes.

vets-api cache may take up to 3 minutes to reflect new maintenance windows due to polling frequency.

What the notification looks like one hour before service goes down, with no custom content.

This is what the downtime notification looks like during the downtime period

Other examples

Below are a few VFS products currently using downtime notifications in production. These can serve as references for implementation patterns.

These examples demonstrate the typical pattern:

<DowntimeNotification
  appTitle="Letters"
  dependencies={[externalServices.evss, externalServices.letters]}
>
  <LettersApp />
</DowntimeNotification>

Common issues

• Mismatched external_service key vs externalServices constant.

• No data returned from /v0/maintenance_windows → UI shows no downtime.

• Headings or breadcrumbs placed inside DowntimeNotification → hidden during downtime.

• Forgetting to clear staging maintenance windows → banners persist unexpectedly.

• Expect up to 3 minutes of delay for new PD windows due to vets-api caching.

Help and feedback

• Suggest content changes to this page.

• Submit new Platform Website content.

• Get help from the Platform Support Team in Slack.

• Submit a feature idea to the Platform.