Using an authorization scheme for displaying a friendly "page under construction" message

Always check out the original article at http://www.oraclequirks.com for latest comments, fixes and updates.

In certain cases it can be useful to prevent users from entering a page while it is being updated or upgraded.
If you are not enthusiastic about the idea of delivering a generic page not found error page then read on.

Yesterday i had to upgrade a single page of a public application: oracle application express makes the life of the workspace administrator very easy from this point of view as it allows to export and import a bunch of components without the need of exporting and importing the whole application.
However the upgrade involved the underlying database objects, so, unfortunately, it was not just a matter of exporting Apex's definitions, but i needed to change the structure of tables, migrate some data and reload a big table from scratch and all these activities took a couple of hours, also because at a certain point an unforeseen problem happened...

In a case like this, if you don't prevent access to the page, the end user may get inconsistent results or obscure application errors while the job is in progress, so you might want to display instead a nicely formatted error message informing the user that the page is temporarily unavailable.



Clearly you may also opt for bringing down the whole application if necessary, but the approach i am suggesting is less drastic and it's tailored for the specific case of updating just a few pages.
Another option is to display a simple notification message across all pages (see the free notifier application...), but in case of an unhandled oracle error, the notification message won't be displayed, so i don't find it really effective in this case.

I'll show you how i created a simple authorization scheme called "UNDER_CONTRUCTION", whose goal was to prevent any user to access the page being updated as long as necessary.
A user attempting to enter this page will read a friendly warning message explaining the situation instead of getting some weird application error and possibly the indication of the time by which the upgrade will be terminated if you are really really cool ;-)

The method works equally well for public applications (no authentication) and for non-public applications, it certainly requires additional work when a page with an existing authorization scheme is involved.
Later on I'll also provide the details for a slightly more refined mechanism.

The steps for achieving this are:

1. create an authorization scheme called "UNDER_CONSTRUCTION";
2. pick the Item in expression 1 is NOT NULL scheme type;
3. write UNDER_CONSTRUCTION in the item1 attribute;
4. write a proper warning message (see below);
5. evaluation point set to: once per page view;
   
6. create an application item called UNDER_CONSTRUCTION with session protection;
7. assign this authorization to the relevant page(s);
8. seed the application if translations exist;
9. translate the message (*) in versions of Apex later than version 3.1.1;
10. publish the application (only if step 8 applied).
    

(*) While i was working on this tip, it turned out that Apex doesn't provide a slot for the translation of the authorization scheme violation message and this has been acknowledged as a bug, that's why i wrote a multilingual message directly. See the following OTN thread for the full story.

Steps 1-6 are only required the first time you use this technique, in the future you only need to repeat steps 7-9 on the desired pages because you don't need to remove these components from the application, you just need to unselect the authorization scheme once you've completed the upgrade.
If the application has been translated, you will need also to seed and publish the mapped applications, otherwise the translated versions may still run the authorization code while the primary language doesn't.

The application item UNDER_CONSTRUCTION must remain empty at all times.

I don't think is a good idea to keep the authorization scheme and initialize this item to re-enable the page for a couple of reasons:

• users who tried to open the page may still be using the same session ID, which means they could not see the updated item value (depending on how/when you initialize the item).
  
• authorization scheme checking requires additional resources, which in the end means slower page loading.

I think it's just much better to deselect the authorization scheme from the page and eventually seed and publish the application, if there are any translations attached.

But what if you want to have exclusive access to the page prior to opening up the doors to everybody?

Note that with some minor changes you may proceed in the following fashion:

1. define the UNDER_CONSTRUCTION application item as unprotected;
2. change the scheme authorization type from item in expression1 is NOT NULL, to value of item in expression1 equals expression2;
3. write a password in expression2.

This will allow you to enter the page by setting the application item from the browser with the given password.
In any case, remember to disable the authorization scheme once the page is working fine.

And the day you need to upgrade another page, you'll have all the necessary tools ready for showing your work in progress friendly message again.

See more articles about Oracle Application Express or download tools and utilities.