Highlighting the environment

In my presentation at APEX Connect 2017, I’ve discussed about Nearshoring development with APEX. One of the hints from the presentation was to highlight the different staged systems so that the developer can easily identify where he/she works. I’ve seen customers who had problems because of this. Often developers execute different tasks on TEST, QA and PROD environments. They could, without intention, do damage to the PROD environment because the URLs are usually very similar. There is a very easy solution to this potential problem that should be considered for every project.

 

In this blog article, I will show how this can be easily done for an APEX application. Firstly, we’ll need a place where to write the environment name and then to find the templates where to insert the HTML code which uses the environment name. For an APEX application, I usually use a substitution string at the application level. To do this, you’ll have to go to App Builder and click on the Edit Application Properties button:

Then, go to the Substitutions tab:

And define a substitution string with the name: ENV_IDENTIFICATION

Now, go to the page templates, which can be found under Shared Components, User Interface, Templates.

Search for the templates, which are used by your application, and add the following code in the Header part of the template (usually where the navigation is displayed); this depends very much on how you have designed your application:

<div style="
    font-size: 24px;
    margin: 10px;
    color: red;
    font-weight: 700; 
    float:left;
">&ENV_IDENTIFICATION.</div>

See that I used here the application’s ENV_IDENTIFICATION substitution string.

That’s all you have to do in APEX. Now, when you deploy your application on another system, you will have to change the value for ENV_IDENTIFICATION. It is not nice doing it manually each time because you might forget about it and then the user will wonder about the “new feature”. So, I propose an automatic way of setting this value via ANT. In my APEX projects, I like to use ANT to deploy them to different environments. Therefore, I have an ANT target that is executed after the deployment, which will set the right environment value for the application’s ENV_IDENTIFICATION substitution string.

The ANT target for this is:

<target name="xxinternal-update-environment">

    <sql userid="${db.username}" url="jdbc:oracle:thin:@${db.url}" keepformat="yes" 
                delimiter="/" password="${db.password}" driver="oracle.jdbc.OracleDriver" 
                classpathref="antclasspath" onerror="abort">
        <transaction>
            <![CDATA[
            declare 
               envName varchar2(500) := '';
            begin
                wwv_flow_api.set_security_group_id(
                    p_security_group_id=>${apex.workspaceid}
                );
                            
                if '${build.env}' <> 'PROD' THEN
                   envName  := '${build.env}';
                end if;
                
                 wwv_flow_api.set_static_sub_strings (
                    p_flow_id => ${apex.applicationid},
                    p_substitution_string_01 => 'ENV_IDENTIFICATION',
                    p_substitution_value_01 => envName
                );
            end;
                /
            ]]>
        </transaction>
    </sql>
</target>

I have used an environment variable, which I’ve set when running ANT: -Dbuild.env=QA

In the ANT target, I use the <sql> task to connect to the application schema and, with a PL/SQL function (wwv_flow_api.set_static_sub_strings), I’m able to set the value for the application’s ENV_IDENTIFICATION substitution string.

Now the systems are correctly and automatically highlighted and users can easily identify the systems where they work.