How to Put an Oracle APEX Application in Maintenance Mode

Deploying a new version, running a data migration, or fixing a production problem is safer when users cannot work in the application at the same time. Oracle APEX has this built in: every application has an availability status. Switch it to Unavailable or Available to Developers Only, and users get your maintenance message instead of the application, while developers can still test. This guide sets the status in App Builder and from PL/SQL, shows what users and developers see in each mode, and switches the application back.

The Availability Settings

In App Builder, open the application, click Shared Components, then Application Definition, and go to the Availability section:

Status has these values:

• Available, and Available with Developer Toolbar: normal operation. The second shows the toolbar to developers.
• Available to Developers Only: users who sign in with a workspace developer account can use the application; everybody else gets the message after signing in.
• Restricted Access: only the users in the comma-separated user list below the message can use the application.
• Unavailable: nobody can use it, developers included; even the sign-in page shows the message.
• Unavailable (Status Shown with PL/SQL) and Unavailable (Redirect to URL): unavailable, with the message produced by PL/SQL code, or a redirect to another page, such as a status page outside APEX.

Message for unavailable application accepts HTML. It is shown as a bare page, without the application's theme, so include your own styling in the message, as in this example:

Example:

<div style="max-width:560px;margin:80px auto;font-family:sans-serif;text-align:center">
  <h1>Scheduled maintenance</h1>
  <p>APEX Solutions is being updated and will be back at 18:00 UTC.</p>
</div>

Set the Status from PL/SQL

For a deployment script, set the status with APEX_UTIL.SET_APPLICATION_STATUS. Run it as the application's parsing schema, after setting the workspace:

Example:

begin
    apex_util.set_workspace(p_workspace => 'SOLUTIONS');
    apex_util.set_application_status(
        p_application_id     => 400,
        p_application_status => 'DEVELOPERS_ONLY',
        p_unavailable_value  =>
            '<div style="max-width:560px;margin:80px auto;font-family:sans-serif;text-align:center">'
         || '<h1>Scheduled maintenance</h1>'
         || '<p>APEX Solutions is being updated and will be back at 18:00 UTC.</p>'
         || '</div>');
    commit;
end;
/

select availability_status
from   apex_applications
where  application_id = 400;

Output:

PL/SQL procedure successfully completed.

AVAILABILITY_STATUS
_______________________________
Available to Developers Only

The change takes effect at once, without restarting anything. The other status values for p_application_status are AVAILABLE, AVAILABLE_W_EDIT_LINK, RESTRICTED_ACCESS, UNAVAILABLE, UNAVAILABLE_PLSQL, and UNAVAILABLE_URL. For Restricted Access, pass the allowed users in p_restricted_user_list.

What Users and Developers See

With Available to Developers Only, a business user, SALES_USER, signs in and gets the maintenance page:

The developer DEMO_DEV, a workspace developer, signs in to the same application and gets the normal home page, so the new version can be tested before users return. The tests in each mode gave these results:

• Available to Developers Only: the sign-in page is shown; SALES_USER gets the message after signing in, DEMO_DEV gets the application.
• Unavailable: the message is shown at once, even instead of the sign-in page, and also to DEMO_DEV while signed in to App Builder.
• Restricted Access with the user list SALES_USER: SALES_USER gets the application, and DEMO_DEV, not on the list, gets the message, although it is a developer account.

Users who are already working in the application get the message on their next page request. Warn them in advance, for example with the Global Notification in the same Application Definition, which shows a message on every page while the application is still available.

Switch the Application Back

After the work is done and tested, set the status back:

Example:

begin
    apex_util.set_workspace(p_workspace => 'SOLUTIONS');
    apex_util.set_application_status(
        p_application_id     => 400,
        p_application_status => 'AVAILABLE_W_EDIT_LINK');
    commit;
end;
/

select application_id, availability_status
from   apex_applications
where  application_id = 400;

Output:

PL/SQL procedure successfully completed.

   APPLICATION_ID AVAILABILITY_STATUS
_________________ ___________________________________
              400 Available with Developer Toolbar

Use AVAILABLE for a production application, so users do not see the developer toolbar.

Things to Know

• The status is per application. When a release touches several applications, call SET_APPLICATION_STATUS for each of them in the deployment script.
• Build Status, next to Status, is a different setting: Run Application Only prevents developers from editing the application in App Builder, which is common for production instances.
• In a deployment script, set the status at the start, run the changes, and set it back only when all steps succeeded, so users never work on a half-updated application.

Related Guides

• How to Export and Import APEX Applications with SQLcl
• How to Manage Users, Preferences, and Caches Using APEX_UTIL

Conclusion

To put an Oracle APEX application in maintenance mode, change its availability status: Available to Developers Only keeps it open for testing by developers, Unavailable closes it for everyone, and Restricted Access opens it for a list of users. Set it in Application Definition or with APEX_UTIL.SET_APPLICATION_STATUS in your deployment script, give users a styled HTML message, and switch back to Available when the work is done.