Thursday, May 04, 2017

APEX and ORDS up and running in....2 steps!

In January 2017, I had a meeting with Dr. Sriram Birudavolu from Hyderabad.  He got my attention when he said he would love to start a 1000-person APEX Meetup group in Hyderabad (gotta love aggressive goals!).  However, he spent much of December and January just trying to figure out how to get APEX installed, configured and running.  He won't profess to be an expert, but he's exactly the type of person we want to enable.  He was correct in saying that if a potential customer struggles to get APEX installed, we've already lost.

Recently, Gerald Venzl asked for some assistance in creating a Docker image for APEX.  His goal was to create an APEX Docker image on top of the base Oracle Database Docker image.  He knows a lot about Docker, but he won't claim to be an expert in APEX.  He wanted something that is scriptable and can result in APEX being installed, configured and up and running, along with ORDS, in as few steps as possible.  A "silent install", if you please. This was the final bit of motivation I needed for this blog post and video.

While the installation documentation is complete and detailed, it's also lengthy and sometimes confusing - especially for the new person.  Thus, I wanted to provide the simplest set of instructions with as few steps as possible to get APEX installed, configured and up and running, along with ORDS configured and up and running.  It can be done in two steps.  That's right, two.  While I explain the individual steps executed from SQL*Plus in detail below, you can combine all of these SQL commands into a single SQL script.  I prefer the name "hookmeup.sql".



  1. Download and unzip APEX http://www.oracle.com/technetwork/developer-tools/apex/downloads/index.html
  2. cd to apex directory
  3. Start SQL*Plus and ensure you are connecting to your PDB and not to the "root" of the container database (APEX should not be installed at all):
    sqlplus sys/your_password@localhost/your_pdb as sysdba @apexins sysaux sysaux temp /i/
    
  4. Unlock the APEX_PUBLIC_USER account and set the password:
    alter user apex_public_user identified by oracle account unlock;
    
  5. Create the APEX Instance Administration user and set the password:
    begin
        apex_util.set_security_group_id( 10 );
        apex_util.create_user(
            p_user_name => 'ADMIN',
            p_email_address => 'your@emailaddress.com',
            p_web_password => 'oracle',
            p_developer_privs => 'ADMIN' );
        apex_util.set_security_group_id( null );
        commit;
    end;
    /
    
  6. Run APEX REST configuration, and set the passwords of APEX_REST_PUBLIC_USER and APEX_LISTENER:
    @apex_rest_config_core.sql oracle oracle
    
  7. Create a network ACE for APEX (this is used when consuming Web services or sending outbound mail):
    declare
        l_acl_path varchar2(4000);
        l_apex_schema varchar2(100);
    begin
        for c1 in (select schema
                     from sys.dba_registry
                    where comp_id = 'APEX') loop
            l_apex_schema := c1.schema;
        end loop;
        sys.dbms_network_acl_admin.append_host_ace(
            host => '*',
            ace => xs$ace_type(privilege_list => xs$name_list('connect'),
            principal_name => l_apex_schema,
            principal_type => xs_acl.ptype_db));
        commit;
    end;
    /
    
  8. Exit SQL*Plus.  Download and unzip ORDS http://www.oracle.com/technetwork/developer-tools/rest-data-services/downloads/index.html
  9. cd to the directory where you unzipped ORDS (ensure that ords.war is in your current directory)
  10. Copy the following into the file params/ords_params.properties and replace the contents with the text below (Note:  this is the file ords_params.properties in the "params" subdirectory - a subdirectory of your current working directory):
    db.hostname=localhost
    db.port=1521
    # CUSTOMIZE db.servicename
    db.servicename=your_pdb
    db.username=APEX_PUBLIC_USER
    db.password=oracle
    migrate.apex.rest=false
    plsql.gateway.add=true
    rest.services.apex.add=true
    rest.services.ords.add=true
    schema.tablespace.default=SYSAUX
    schema.tablespace.temp=TEMP
    standalone.mode=TRUE
    standalone.http.port=8080
    standalone.use.https=false
    # CUSTOMIZE standalone.static.images to point to the directory 
    # containing the images directory of your APEX distribution
    standalone.static.images=/home/oracle/apex/images
    user.apex.listener.password=oracle
    user.apex.restpublic.password=oracle
    user.public.password=oracle
    user.tablespace.default=SYSAUX
    user.tablespace.temp=TEMP
    
  11. Configure and start ORDS in stand-alone mode.  You'll be prompted for the SYS username and SYS password:
    java -Dconfig.dir=/your_ords_configuration_directory -jar ords.war install simple --preserveParamFile
    

That's it!!  You should now be able to go to http://localhost:8080/ords/, and login with:

Workspace: internal
Username:  admin
Password:  oracle





IMPORTANT, PLEASE READ:

By no means is this a recommended or secure installation.  These are minimal instructions to get someone from zero to up and running easily and quickly.  In a production instance, I would create different tablespaces for APEX and ORDS, I would use far more complex and distinct passwords, I would use HTTPS and not HTTP, I would deploy ORDS on a physically distinct server, and more.

The above steps were tested with Oracle Application Express 5.1.1.00.08, Oracle REST Data Services 3.0.9, and Oracle Database 12.2.0.1 running on Oracle Linux.


Wednesday, May 03, 2017

End users still on IE8? Upgrade them before upgrading to Application Express 5.1 or later

If you have end users of your Application Express (APEX) applications still using Internet Explorer 8, you should upgrade their browsers before upgrading to Oracle Application Express 5.1 or later.

The documented general browser compatibility for Oracle Application Express is N-1, where N is the latest production version of a browser, and N-1 is the major production version prior to that.  At the time of release of Application Express 5.1, Microsoft Edge was the current Microsoft browser and Internet Explorer 11 was the prior major version.

The Oracle Cloud Database Schema Service was recently upgraded to APEX 5.1.1, and a customer contacted me directly, saying that some of his end users who were still on IE8 couldn't even login to the application.  "We" (Anthony and John) reviewed these issues, but concluded that there really wasn't any practical way for us to resolve this for the customer.  We'll move heaven and earth to not impact a customer and avoid unplanned cost and work for them, but in this case, there simply wasn't anything we could do.

If you need a compelling reason to have your end users upgrade to a modern version of Internet Explorer, remember that Microsoft no longer supports or provides security patches for the older IE versions.

Thursday, April 20, 2017

Developing a training course or university curriculum for Oracle Application Express (APEX)? Start here!

While education in Oracle Application Express (APEX) is offered as a part of many university and secondary school courses around the globe, in most cases, the educators took it upon themselves to develop their own custom curriculum.  To lessen the burden on educators, we have developed and made available for public download a full course curriculum for Oracle Application Express.

This courseware, developed by our product manager Chaitanya Koratamaddi over the past year, includes 16 distinct lessons, complete with PowerPoint presentations, hands-on-labs, and all necessary SQL scripts and application export files.  You can use all or a portion of these materials in your own curriculum.

This same courseware was provided to the Oracle Academy team, who now also offer an Oracle Application Express course.  The Oracle Academy course is offered in a hosted interactive form, complete with quizzes, and it also includes both educator and student curriculum.  There are many other benefits to joining Oracle Academy.  For more information about Oracle Academy, go here.

To access the publicly available Oracle Application Express curriculum, go to:

https://apex.oracle.com/education



Tuesday, March 28, 2017

Oracle Application Express 5.1.1 now available

Just in time for APEX World 2017, Oracle Application Express 5.1.1 is now released and available for download.  If you wish to download the full release of Oracle Application Express 5.1.1, you can get it from the Downloads page on OTN.  If you have Oracle Application Express 5.1 already installed, then you need to download the APEX 5.1.1 patch set from My Oracle Support.  Look up patch number 25341386.

As is stated in the Patch Set Note that accompanies the Oracle Application Express 5.1.1 patch set:
  • If you have Oracle Application Express release 5.1 installed, download the Oracle Application Express 5.1.1 patch set from My Oracle Support and apply it.  Remember - patch number 25341386.
  • If you have Oracle Application Express release 5.0.4 or earlier installed, download and install the entire Oracle Application Express 5.1.1 release from the Oracle Technology Network (OTN).
  • If you do not have Oracle Application Express installed, download and install the entire Oracle Application Express 5.1.1 release from the Oracle Technology Network (OTN).

As usual, there are a large number of issues corrected in the Application Express 5.1.1 patch set (over 106!).  You can see the full list in the 5.1.1 Patch Set Notes.

Sunday, January 22, 2017

Oracle technologies used to analyze the Inaugural Addresses of the Presidents of the United States



The Oracle Database ships with a wonderful technology called Oracle Text.  Most people associate Oracle Text with the mere ability to index documents or data, perform text or phrase queries and get the results back.  But Oracle Text can do so much more.  One of the more interesting features of Oracle Text is the ability to analyze a document and generate a list of themes for the document along with a weight associated with that theme.

Back in 2004, in the era of Oracle HTML DB, Jason Straub on the Application Express development team wrote a demonstration application named Presidential Inaugural Addresses, which used both Oracle HTML DB and Oracle Text.  This application actually shipped with Oracle HTML DB for a time.  This was a fascinating application, which enabled you to view all of the Inaugural Addresses of the Presidents of the United States, identify the top themes associated with those addresses, and even identify which past presidents delivered addresses that had similar dominant themes.

This demonstration application stopped shipping with Oracle Application Express in 2006.  But I thought it might be interesting to dust off this application and improve the UI using Oracle Application Express 5.1.  So that's how I spent this past weekend (let the good times roll).  Using the existing data structures, I was able to create a new Universal-theme based application which turned out pretty elegant.

Please understand - this application and everything associated with it is not a political statement.  Given the relevance of this data at the time of this writing, I simply thought it would be a fascinating way to demonstrate insights into this information, using the Oracle Database, Oracle Application Express, Oracle Text and Oracle JET!

You can run this application HERE.

Thursday, January 19, 2017

Details about this incident are available via debug id....



In Oracle Application Express, unexpected exceptions can occasionally occur.  Instead of communicating the technical details to an end user who is running the application, an error message will be issued of the form:

Contact your administrator. Details about this incident are available via debug id "NN".

But what actually happened?  Who is "your administrator"?  And what exactly are you supposed to do with this information?


What happened?

An internal exception occurred - it either wasn't properly handled by the application's error handler (or there was no handler in place), or an unforeseen exception occurred in the Application Express engine itself, which wasn't properly caught by the error handler of APEX.  If you're logged into the development environment as a developer and running the application, you should be able to see the full error stack and more details of what actually occurred.  But if you're a mere end-user of the application, you are shielded from those details - not only would the details be mystifying to an end user, but it could also be viewed as a security risk, to show the details.


Who is "your administrator"?

  • A developer of this application, who has access to SQL Commands in the APEX workspace?
  • A developer who can connect directly to the database where this error occurred, connecting as the database user associated with the workspace (commonly referred as the "workspace schema").
  • A database user who has been granted the APEX_ADMINISTRATOR_ROLE (or, beginning in APEX 5.1, also the APEX_ADMINISTRATOR_READ_ROLE).
  • Someone who can connect as SYS or SYSTEM to your database.

What can you do with this information?

The full details of the incident and the error stack at the time of the exception are written to the Debug Messages tables in the Application Express schema.  To view these details, you simply need to query the view APEX_DEBUG_MESSAGES:

select *
  from apex_debug_messages
 where page_view_id = NN
 order by message_timestamp asc;

This information is also accessible from the development environment of Application Express.
  • A developer can select their application in App Builder, and then navigate to Utilities -> Debug Messages.
  • A workspace administrator can navigate to Workspace Administration -> Monitor Activity -> Page Views By View.  You can then filter the output by the Debug ID column.

Tuesday, October 11, 2016

OTN Appreciation Day: Oracle Text

For OTN Appreciation Day, I was told that it wouldn't be appropriate to write about my favorite Oracle feature (APEX, obviously).  So I'll gladly promote my second-favorite Oracle Database feature...Oracle Text!

I've used Oracle Text for many years - from when it was SQL*TextRetrieval to Oracle ConText Option to Oracle interMedia Text to finally Oracle Text.  This was one of those products that used to be a for-cost option and was merged into the Oracle Database as native, no-cost functionality (how cool is that?).  You can use Oracle Text to index BLOB columns containing Microsoft Word or PDF documents, you can score the query results for relevance, you can perform a proximity search within the contents (find "Oracle" and "APEX" within 10 words of each other), you can search within sections of a document, you can do a fuzzy search, you can create a thesaurus to assist in searching for similar terms, you can create a text result with the matching words highlighted, and on and on.

The beauty of Oracle Text is that it's all completely accessible in SQL.  Any tool that can "talk" SQL can easily take advantage of this rich functionality in the Oracle Database - Java, .NET, PHP, Node, and of course, APEX!  I authored the PL/SQL functions and text indexes (and text queries) for AskTom back in 2001 - and they're still running as fast as ever today.  One of the most popular applications inside of Oracle, an employee directory (1.5M page views every day from 55,000 distinct users), is an APEX application that we're responsible for - and we are in the process of expanding this to use the fuzzy search capabilities of Oracle Text - what is more commonly misspelled than someone's name?  And it's easy, because this is all running inside the Oracle Database.  Whether your content is a string or BLOB or XML or JSON, once this content is inside the Oracle Database, it's accessible to Oracle Text and SQL, and the application development opportunities on top of this are easy.  I'm a big  fan of Oracle Text, and you should take a look at it too!