Created on 11 September 2020
icon_unfollowing
Login to follow
maintenance-manager

Maintenance Manager

Stable version 1.0.1 (Compatible with OutSystems 11)
Uploaded on 14 June 2022 by 
maintenance-manager

Maintenance Manager

Documentation
0.9.3

This guide is also available in the GUIDE page of the Maintenance Manager Portal.


1. Setup for first use

Maintenance Mangers require the MaintenanceManager role to access the portal.


Go to the Settings Page. On first access, the following default settings will be applied:
• Default Icon Settings: Application Icon
• Default Maintenance Title: Application is under maintenance
• Default Maintenance Message: This application is currently under maintenance, we apologise for any inconvenience caused. We will automatically redirect you back when maintenance is complete.
• Automatic Refresh Interval: 60 seconds
• Maintenance Screen URL: /MaintenanceManager

You always come back and change these values to suit your needs.


2. Installation of Components

Once the default settings have been set, all eSpaces which need to leverage this maintenance functionality would need to be integrated with this app. To achieve this, follow the instructions below:


2.1 Traditional eSpaces


CheckMaintenance_Traditional service action from the MaintenanceManager_Service module

  1. Create a new User Exception called Maintenance. Handle all exceptions of this type in your Global Exception Handler by redirecting to an External Link with the Exception Message passed in as the URL.\
  2. Navigate to component used in all pages of your application (e.g. Layout, Header or Footer etc.) and place the CheckMaintenance_Traditional action in the preparation. Pass the GetEntryEspaceId() function in the EspaceID parameter. Handle a positive scenario by raising a new Maintenance exception and pass the MaintenanceScreen output parameter as the Exception Message.

Since exception types are tied to specific eSpaces and can’t be made public, maintenance exceptions can be caught in other eSpaces by passing a unique string as the Exception Message and checking for that in the Global Exception Handler. The Get_MaintenanceLink_Traditional service action from the MaintenanceManager_Service module is used to determine the redirect URL.


2.2 Reactive eSpaces


Maintenance_Check_Reactive web block from the MaintenanceManager_Reactive module

In each of the Layout web block you wish the maintenance check to happen, place the Maintenance_Check_Reactive web block as the top-most component in the Widget Tree. For the EspaceName parameter use the GetEntryEspaceName() function.

There isn't only correct location to place the Maintenance_Check_Reactive web block. It is recommended that this web block is installed in the Layout block of the splash screen page, login page (could be the same Layout web block) and/or application dashboard. This'll insure that users are redirected to the outage page when needed.


2.3 Mobile eSpaces



  • Maintenance_Page_Mobile web block from the MaintenanceManager_Mobile module
  • Maintenance_Check_Mobile web block from the MaintenanceManager_Mobile module


  1. Create a new Empty page in the app and remove all default components from the Widget Tree. Place the Maintenance_Page_Mobile web block on that page. Parameters required:
    a. EspaceName: Use GetEntryEspaceName()
    b. Handler for MaintenanceEnded event: Create a new action which redirects the user back to the page of your choosing (e.g. Login page or Homepage).
  2. Create a new User Exception called Maintenance. Handle all exceptions of this type in your Global Exception Handler by redirecting to the page created in step 1.
  3. In each of the Layouts you wish the maintenance check to happen, place the Maintenance_Check_Mobile web block as the top-most component in the Widget Tree. Parameters required:
    a. EspaceName: Use GetEntryEspaceName()
    b. Handler for MaintenanceDetected event: Create a new action which raises the UnderMaintenance Exception. Set an Exception Message of your choice.


Yes you can however its good practice to use the exception handling mechanism because 
  1. Logging remains precise and reflects user behaviour more accurately
  2. Custom maintenance handling logic would be defined only once in the Exception Handler regardless the number of times Maintenance_Check_Mobile is deployed.


The LayoutBlank web block is used in the splash screen so deploying step 3 there ensures users are redirected to the maintenance screen before ever logging in/accessing the app. However its good practice to deploy step 3 to other Layout web blocks (like the Layout web block used by the dashboard) since the splash screen can be skipped in a few scenarios.


3. Portal Guide

Once the required eSpaces have been configured, the following actions can be taken:


3.1 Maintenance Mode


3.1.1 Enabling Maintenance Mode


3.1.1.1 For a single eSpace

  1. Go to the Applications page and search for the required application. Click on the application to access its settings.
  2. In the Applications Details page, click on the required eSpace. This will open the Maintenance Manage Properties popup.
  3. In the Maintenance Manage Properties popup, a preview of the default maintenance screen content is available. To modify these values, click on EDIT and select your icon preference, new title and new message. On completion click SAVE.
  4. Click on START MAINTENANCE to commence maintenance for this eSpace.

3.1.1.2 For a entire application

  1. Go to the Applications page and search for the required application. Click on the application to access its settings.
  2. In the Applications Details page, click on the MANAGE button under the Settings section. This will open the Maintenance Manage Properties popup.
  3. In the Maintenance Manage Properties popup, a preview of the default maintenance screen content is available. To modify these values, click on EDIT and select your icon preference, new title and new message. On completion click SAVE. These changes will overwrite any existing maintenance screen content of any of the eSpaces in this application.
  4. Click on START MAINTENANCE to commence maintenance for this application. This will make all eSpaces for this application Under Maintenance.


3.1.2 Disabling Maintenance Mode


3.1.2.1 For a single eSpace

  1. Go to the Applications page and search for the required application. Click on the application to access its settings.
  2. In the Applications Details page, click on the required eSpace. This will open the Maintenance Manage Properties popup.
  3. In the Maintenance Manage Properties popup click on GO LIVE to end the maintenance for this eSpace.

3.1.2.2 For a entire application

  1. Go to the Applications page and search for the required application. Click on the application to access its settings.
  2. In the Applications Details page, click on the MANAGE button under the Settings section. This will open the Maintenance Manage Properties popup.
  3. In the Maintenance Manage Properties popup click on GO LIVE to end the maintenance for this application. This will make all eSpaces for this application Live.

3.2 Maintenance Screen Content


3.2.1 Changing the default content of Maintenance Screens 

  1. Go to the Settings page.
  2. Under the Default section, icon settings, a default icon, title and message can be set. These values are used by default the next time maintenance mode is enabled.

3.2.2 Changing content of a live Maintenance Screen 

  1. Go to the Applications page and search for the required application. Click on the application to access its settings.
  2. In the Applications Details page, click on the required eSpace – the selected eSpace must be under maintenance. This will open the Maintenance Manage Properties popup.
  3. In the Maintenance Manage Properties popup, a preview of the live maintenance screen content is available. To modify these values, click on EDIT and select your icon preference, new title and new message. On completion click MAKE CHANGES LIVE.
  4. Click on EXIT.

Support options
This asset is not supported by OutSystems. You may use the discussion forums to leave suggestions or obtain best-effort support from the community, including from  who created this asset.
Dependencies
Maintenance Manager has no dependencies.