Maintenance Banner Lite | Forge Documentation
Maintenance Banner Lite
Component type
Forge documentation for a reusable full-screen maintenance blocker in OutSystems
Reactive Web applications
Target platform
OutSystems Forge component
Primary use
Version covered
Scheduled maintenance, downtime notices, environment
and application targeting
1.0.0 / 1.1.0 capabilities
Short summary
Maintenance Banner Lite displays a modern full-screen maintenance blocker with scheduled notices, severity themes,
application and environment targeting, priority-based notice selection, and optional dismissal.
Recommended Forge tags: Maintenance, Banner, Notification, Downtime, Environment, Application, Admin, SRE, Reactive Web,
OutSystems
1
Contents
1. Detailed summary
2. Features
3. Component structure
4. Data model
5. How the component works
6. How to integrate into any app
7. Creating maintenance notices
8. Recommended usage patterns
9. Admin screen usage
10. Testing checklist
11. Troubleshooting
12. Security recommendations
13. Best practices
14. Forge descriptions and version notes
2
Maintenance Banner Lite helps OutSystems teams communicate planned maintenance, temporary downtime,
emergency outages, environment-specific activities, or application-specific service interruptions through a polished
full-screen maintenance notice.
The component is intended for enterprise environments where multiple applications and multiple environments need
consistent maintenance communication without re-implementing the same logic in every application.
The banner appears only when an active maintenance notice matches the current application and environment. This
enables centralized configuration for one application, one environment, all applications in one environment, one
application across all environments, or all applications across all environments.
Enterprise value
A single reusable component can control maintenance communication across DEV, SIT, UAT, PREPROD, and PROD
while still allowing application-specific messages and strict production blockers.
• Full-screen maintenance blocker with modern animated UI
• Responsive design for desktop and mobile
• Scheduled start and end date-time
• Enable or disable maintenance notices
• Optional dismiss action using an I Understand link
• Reusable MaintenanceBanner block
• Admin-managed maintenance notices
• Demo screen for quick testing
• Application-specific targeting
• Environment-specific targeting
• Global targeting using the ALL keyword
• Priority-based notice selection
• Built-in severity themes: Info, Warning, Critical
Feature area
What it does
Example
Application targeting
Shows a notice only for matching ApplicationKey values. EMPLOYEEPORTAL
Environment targeting
Shows a notice only for matching EnvironmentKey values. UAT or PROD
Global targeting
Uses ALL to apply notices broadly.
ALL + ALL
Priority selection
Displays the highest priority matching notice. 100 beats 10
Severity themes
Changes visual theme based on notice severity.
Info, Warning, Critical
MaintenanceBannerLite
Data - MaintenanceNotice - MaintenanceSeverity
3
4 - MaintenanceNoticeItem
Logic - GetActiveMaintenanceNotice - SaveMaintenanceNotice - DisableMaintenanceNotice - IsMaintenanceActive
Interface - MaintenanceBanner - MaintenanceAdmin - MaintenanceDemo
MaintenanceSeverity static entity
The MaintenanceSeverity static entity stores available severity types and visual theme metadata.
Record Recommended purpose Theme
Info General notices with low or no impact. Blue
Warning Planned maintenance or temporary user impact. Orange
Critical Urgent downtime or strict blocking scenarios. Red
Attribute Purpose
Label Display label such as Info, Warning, or Critical.
ColorCode Optional background/accent color.
TextColor Optional text color.
SortOrder Controls display order in admin dropdowns.
IsActive Allows severity values to be disabled without deletion.
MaintenanceNotice entity
The MaintenanceNotice entity stores notice configuration, schedule, targeting, priority, and audit fields.
Attribute Description
Title Main heading displayed in the maintenance blocker.
Message Detailed maintenance message shown to users.
MaintenanceSeverityId Defines the visual theme: Info, Warning, or Critical.
ApplicationKey Target application key. Use ALL for all applications.
EnvironmentKey Target environment key. Use ALL for all environments.
Priority
Higher priority notice wins when multiple notices match.
StartDateTime
Date and time when the notice starts appearing.
EndDateTime
Date and time when the notice stops appearing.
IsEnabled
Controls whether the notice is active.
ShowCloseButton
Controls whether users can dismiss the blocker.
CreatedOn / CreatedBy
Creation audit fields.
UpdatedOn / UpdatedBy
Update audit fields.
MaintenanceNoticeItem structure
NoticeId
Title
Message
SeverityLabel
BackgroundColor
TextColor
ApplicationKey
EnvironmentKey
IsActive
The component checks for an active maintenance notice using the following matching logic:
IsEnabled = True
StartDateTime <= CurrDateTime()
EndDateTime >= CurrDateTime()
(ApplicationKey = CurrentApplicationKey OR ApplicationKey = "ALL")
(EnvironmentKey = CurrentEnvironmentKey OR EnvironmentKey = "ALL")
If multiple notices match, the component sorts by:
Priority Descending
StartDateTime Descending
The notice with the highest priority is displayed.
Targeting scenario
Notice configuration
Typical priority
Exact app and environment
Specific app, all environments
EMPLOYEEPORTAL + UAT
100
All apps, specific environment
EMPLOYEEPORTAL + ALL
70
ALL + UAT
50
Global notice
10
5
Step 1: Add dependency
In the consumer application, open Manage Dependencies and add a dependency to the producer module:
Add the MaintenanceBanner block. If the consumer app needs to create notices programmatically, also add
SaveMaintenanceNotice and MaintenanceSeverity.
Step 2: Place the block in the main layout
Place the MaintenanceBanner block in the main layout so the blocker can appear globally across the application.
Header
MaintenanceBanner
MainContent
Footer
Step 3: Configure block inputs
Input
Purpose
Current consuming application key. EMPLOYEEPORTAL
Current environment key.
UAT
AllowDismiss
Controls whether users can dismiss the blocker. True or False
ShowSeverityLabel
Controls whether severity text appears.
True
ContainerCssClass
Optional extra CSS class for customization.
MaintenanceBanner(
ApplicationKey: "EMPLOYEEPORTAL",
EnvironmentKey: "UAT",
AllowDismiss: True,
ShowSeverityLabel: True,
ContainerCssClass: ""
)
Recommended integration pattern
Create Site Properties named AppKey and EnvironmentKey in each consuming app. Pass Site.AppKey and
Site.EnvironmentKey to the MaintenanceBanner block. This keeps the integration configurable per environment without
changing UI logic.
Site.AppKey = "EMPLOYEEPORTAL"
Site.EnvironmentKey = "UAT"
ApplicationKey: Site.AppKey,
EnvironmentKey: Site.EnvironmentKey,
6
Example 1: Global platform maintenance
Title = "Platform Maintenance"
Message = "All applications will be unavailable tonight from 10:00 PM to 11:00 PM."
Severity = Warning
ApplicationKey = "ALL"
EnvironmentKey = "ALL"
Priority = 10
StartDateTime = Current time
EndDateTime = Current time + 2 hours
ShowCloseButton = True
Example 2: UAT environment maintenance
Title = "UAT Maintenance"
Message = "UAT environment is unavailable due to testing activity."
EnvironmentKey = "UAT"
Priority = 50
Example 3: Specific app production downtime
Title = "Critical Maintenance"
Message = "Employee Portal is temporarily unavailable due to urgent production maintenance."
Severity = Critical
ApplicationKey = "EMPLOYEEPORTAL"
EnvironmentKey = "PROD"
Priority = 100
EndDateTime = Current time + 1 hour
ShowCloseButton = False
Pattern
Recommended configuration
Informational notice
When to use
Planned maintenance
Severity = Info; AllowDismiss = True;
Users can continue but should be
informed.
Strict downtime blocker
Severity = Warning; AllowDismiss = True;
There may be temporary impact or
downtime.
Severity = Critical; AllowDismiss = False;
Users should not continue into the
application.
7
The MaintenanceAdmin screen can be used by authorized users to create, edit, enable, or disable maintenance
notices.
Field
Description
Main heading of the notice.
Detailed maintenance message.
Severity
Info, Warning, or Critical.
Application Key
Specific app key or ALL.
Environment Key
Specific environment key or ALL.
Determines the winning notice if multiple match.
Start DateTime
Start of the maintenance window.
End DateTime
End of the maintenance window.
Is Enabled
Enables or disables the notice.
Show Close Button
• [ ] No active notice: blocker should not appear.
• [ ] Active notice: blocker should appear.
• [ ] Disabled notice: blocker should not appear.
• [ ] Future notice: blocker should not appear yet.
• [ ] Expired notice: blocker should not appear.
• [ ] ApplicationKey matching works.
• [ ] EnvironmentKey matching works.
• [ ] ALL application targeting works.
• [ ] ALL environment targeting works.
• [ ] Priority sorting works.
• [ ] Info theme appears correctly.
• [ ] Warning theme appears correctly.
• [ ] Critical theme appears correctly.
• [ ] Dismiss link hides the blocker.
• [ ] Strict blocker hides dismiss link.
• [ ] UI remains centered on browser zoom in and zoom out.
• [ ] Mobile layout looks correct.
Priority test example
Create a global ALL + ALL notice with Priority 10 and an EMPLOYEEPORTAL + UAT notice with Priority 100. For
EMPLOYEEPORTAL UAT, the specific notice should appear.
8
Issue
What to check
Banner does not appear
Wrong notice appears
IsEnabled, start/end date-time, ApplicationKey, EnvironmentKey, and
ActiveNotice.IsActive.
Priority values and aggregate sorting by Priority Descending and StartDateTime
Descending.
Dismiss link does not appear
Notice appears in wrong
app/environment
AllowDismiss, ShowCloseButton, and ActiveNotice.IsActive.
Spelling and casing of ApplicationKey and EnvironmentKey. Use uppercase values.
Text is missing
Verify expressions for SeverityLabel, Title, and Message.
Link alignment issue
Use a Link widget with the maintenance-blocker-dismiss CSS class.
Create a role named MaintenanceAdmin and restrict the admin screen and management actions to authorized users
only.
Recommended protected elements: - MaintenanceAdmin screen - SaveMaintenanceNotice action - DisableMaintenanceNotice action
Only authorized maintenance administrators should create, update, or disable maintenance notices.
• Use uppercase keys such as EMPLOYEEPORTAL, UAT, PROD, and ALL.
• Use site properties in consumer apps to avoid hardcoding app and environment values.
• Use ALL carefully for global notices only.
• Use priority consistently: 100 exact match, 70 app-wide, 50 environment-wide, 10 global.
• For production blockers, use Critical severity and disable dismissal.
• Keep messages concise, clear, and user-facing.
Forge short description
Maintenance Banner Lite is a reusable OutSystems component for displaying full-screen
maintenance notices in Reactive Web applications. It supports scheduled notices, severity-based
themes, application/environment targeting, priority-based notice selection, and optional
dismissal.
Forge detailed description
Maintenance Banner Lite helps OutSystems teams communicate planned maintenance, downtime, emergency
notices, and service-impacting events using a modern full-screen maintenance blocker.
9
The component supports application-specific and environment-specific targeting, global notices using ALL, severity
based themes for Info, Warning, and Critical notices, configurable title and message, start/end date-time scheduling,
priority-based notice selection, enable/disable controls, and optional user dismissal.
It is ideal for enterprise applications that need a reusable and visually polished way to notify users about
maintenance windows, environment activities, temporary outages, or production downtime.
Version notes
Version
Notes
1.0.0
Initial release with full-screen MaintenanceBanner block, severity themes, scheduled notice support,
optional dismiss action, admin screen support, and demo screen support.
1.1.0
Added ApplicationKey support, EnvironmentKey support, global targeting using ALL, and priority
based notice selection.
Future enhancements
• Persist dismissal using browser local storage
• Support multiple stacked notices
• Role-based notice targeting
• Tenant-specific notices
• Environment auto-detection helper
• Notice history and audit log
• Preview mode in admin screen
• Email notification hook
• Microsoft Teams notification integration
• REST API for external maintenance triggers