Installation
Guide
Version 3.0.1
@FOEXplugins
Last updated: May 2017
tryfoexnow.com
1 of 3
FOEX Installation Guide, version 3.0.1
Copyright © 2017, FOEX GmbH. All rights reserved.
Authors: Peter Raganitsch, Matt Nolan, Dietmar Gabauer
This software and related documentation are provided under a license agreement
containing restrictions on use and disclosure and are protected by intellectual property
laws. Except as expressly permitted in your license agreement or allowed by law, you
may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute,
exhibit, perform, publish, or display any part, in any form, or by any means. Reverse
engineering, disassembly, or de-compilation of this software, unless required by law for
interoperability, is prohibited.
The information contained herein is subject to change without notice and is not
warranted to be error-free. If you find any errors, please report them to us in writing.
tryfoexnow.com
2 of 3
FOEX Installation Guide
Version 3.0.1
Table of Contents
Requirements ........................................................................................................ 1
Oracle Application Express...................................................................................1
Database Connection ...........................................................................................1
FOEX Developer Addon ........................................................................................ 1
Storage Requirements ..........................................................................................2
Browser Requirements .........................................................................................2
Installing the FOEX Plugin Framework................................................................ 3
Alternative: Installing FOEX with private Synonyms.........................................4
Installing the License Key .....................................................................................6
Running multiple versions of FOEX .....................................................................7
Copying the HTTP server files ..............................................................................7
Upgrading a FOEX installation ............................................................................. 9
Loading plugins into an existing application ..................................................... 9
Uninstall FOEX Plugins........................................................................................ 10
Downgrade to an earlier FOEX version............................................................. 11
Upgrading the APEX software installation .......................................................12
Installing on Oracle Database 12c .....................................................................13
Installing demo applications.............................................................................. 13
Appendix A: Privileges required for the FOEX installation .............................16
tryfoexnow.com
3 of 3
FOEX Installation Guide
Version 3.0.1
Requirements
The FOEX Plugin Framework is a suite of plugins for Oracle Application Express.
Therefore, it requires Oracle APEX to be installed prior to installing the FOEX
Plugin Framework.
Oracle Application Express
The current version 3.0.1.0 of the FOEX Plugin Framework requires Oracle APEX
5.0.x to be installed. Lower versions of Oracle APEX are currently not permitted.
Database Connection
For the installation process a SYSDBA connection via SQLPLUS is required. If you
want to avoid using SYSDBA, please refer to the chapter Privileges required for
FOEX Installation to set up an alternative installation user.
FOEX Developer Addon
To assist with the building of FOEX applications we have written a browser
extension called the FOEX Developer Addon (FDA) for Google Chrome and
Firefox browsers. This means we only support development of FOEX
applications within these two browsers when using the FDA.
See the FOEX First Steps guide for installation instructions.
tryfoexnow.com
1 of 17
FOEX Installation Guide
Version 3.0.1
Storage Requirements
FOEX Plugins require less than 100MB in the DB and about 50MB on the HTTP
Server.
Browser Requirements
To run or develop FOEX applications, web browsers must have JavaScript
enabled.
The following browsers and the FOEX Developer Addon are required to be
installed in order to develop FOEX applications in Oracle Application Express:
•
•
Mozilla Firefox 29 or a later version
Google Chrome 30 or a later version
FOEX applications can be executed (run) in these web browsers:
•
•
•
•
Internet Explorer 9.0 or a later version
Mozilla Firefox 11 of a later version
Google Chrome 18 or a later version
Apple Safari 5.1 or a later version
tryfoexnow.com
2 of 17
FOEX Installation Guide
Version 3.0.1
Installing the FOEX Plugin Framework
Similar to Oracle APEX, FOEX installs into its own centralized schema and creates
public synonyms to be used by whichever schema and workspace you want
without any further action required.
It is advised to follow the same pre-installation tasks as described in the Oracle
Application Express Installation Guide.
To install the FOEX Plugin Framework, follow these steps:
1. Unzip the provided FOEX Plugin Framework zip file
2. Change your working directory to the unzipped folder
3. Start SQL*Plus and connect to the database where Oracle Application
Express is installed as SYS specifying the SYSDBA role.
For example:
$ sqlplus /nolog
SQL> CONNECT SYS AS SYSDBA
Enter password: <sys-password>
4. If you want to avoid using SYSDBA, please refer to the chapter Privileges
required for FOEX Installation to set up an alternative installation user
5. Disable any existing password complexity rules for the default profile.
See Configuring Password Protection in the Oracle Database Security Guide.
6. Run the install script
• SQL> @foex_install tablespace_foex tablespace_temp
• tablespace_foex is the name of the tablespace for the FOEX
schema user
• tablespace_temp is the name of the temporary tablespace
e.g.
SQL> @foex_install USERS TEMP
tryfoexnow.com
3 of 17
FOEX Installation Guide
Version 3.0.1
7. Once the above script is complete a new schema named FOEX_030000 will
be created. You can lock the FOEX_030000 schema for added security.
E.g.
SQL> alter user FOEX_030000 account lock;
This installation creates a new schema called FOEX_030000.
Alternative: Installing FOEX with private
Synonyms
If you want to install FOEX just for a single or a handful of schemas, or you
simply don’t want to have public synonyms for FOEX objects (views, APIs), then
you can also work with private synonyms.
To do this follow these steps:
1. Unzip the provided FOEX Plugin Framework zip file
2. Change your working directory to the unzipped folder
3. Start SQL*Plus and connect to the database where Oracle Application
Express is installed as SYS specifying the SYSDBA role.
For example:
$ sqlplus /nolog
SQL> CONNECT SYS AS SYSDBA
Enter password: <sys-password>
4. If you want to avoid using SYSDBA, please refer to the chapter Privileges
required for FOEX Installation to set up an alternative installation user
tryfoexnow.com
4 of 17
FOEX Installation Guide
Version 3.0.1
5. Disable any existing password complexity rules for the default profile.
See Configuring Password Protection in Oracle Database Security Guide.
6. Run the Install Script
• SQL> @foex_install tablespace_foex tablespace_temp N
i. tablespace_foex is the name of the tablespace for the FOEX
schema user
ii. tablespace_temp is the name of the temporary tablespace
iii. N stops the installer from creating public synonyms for FOEX
objects
7. Once the above script is complete a new schema named FOEX_030000 will
be created. You can lock the FOEX_030000 schema for added security.
E.g.
SQL> alter user FOEX_030000 account lock;
This Installation creates a new schema called FOEX_030000.
Additionally, you need to explicitly grant rights and create synonyms to all
schemas, which should be able to use FOEX:
1. Change directory to the sub-folder “db”
2. Start SQL*Plus and connect to the database where Oracle Application
Express is installed as SYS specifying the SYSDBA role.
For example
$ sqlplus /nolog
SQL> CONNECT SYS AS SYSDBA
Enter password: <sys-password>
3. Run the Install Script
• SQL> @fx_grant_foex_to_user foex_schema user_schema
i. foex_schema is the name of the FOEX schema user (FOEX_030000)
ii. user_schema is the name of the user/schema the rights should be
granted to
tryfoexnow.com
5 of 17
FOEX Installation Guide
Version 3.0.1
Installing the License Key
Starting with FOEX 3.0.1 the license key is no longer integrated directly into the
installation file of FOEX. Therefore, you must install your license key(s) in a
separate step on your development machine.
Download the License Key installation file
1. Log into the FOEX Support Portal with your login credentials.
If you haven’t received your credentials, please contact us on
[email protected].
2. Click on Licenses in the right side menu
3. Click on the download icon
of your license(s)
Install the License Key on your development machine
1.
$ sqlplus /nolog
SQL> CONNECT SYS AS SYSDBA
Enter password: <sys-password>
2. You can commit this step if you are using public synonyms in your FOEX
installation
SQL> ALTER SESSION SET CURRENT_SCHEMA = <Schema of your
FOEX installation>;
3. Execute the file(s) you downloaded before
e.g.
SQL> @FOEX_Plugin_Framework_1dev_123456789.sql
tryfoexnow.com
6 of 17
FOEX Installation Guide
Version 3.0.1
Running multiple versions of FOEX
Using private synonyms as described in the previous chapter means you can
have applications running multiple FOEX versions in the same database.
Additionally, you will need to version the files under the HTTP server defined in
Step 3 of the next section Copy the HTTP Server Files e.g. foex-200
Copying the HTTP server files
Oracle APEX can be configured using one of the three possible HTTP servers:
1. Oracle APEX Listener
2. Oracle HTTP Service and mod_plsql
3. The embedded PL/SQL Gateway
This installation guide doesn’t go into the details, but you can read that and base
your decision upon the Oracle Application Express Installation Guide
Whatever server you use, the FOEX Plugin Framework requires a number of
files/directories to be on the selected HTTP Server.
To copy the files, follow these steps:
1. Unzip the provided FOEX Plugins.zip file
2. Locate the /server folder within the directory created by unzipping the
file
3. Copy the /server folder (and all file/folders contained) to the HTTP
Server (Note: by default we expect the “server” folder to be renamed to
“foex” or “foex-[version number]” and be located in your images
directory, as you can see in the screenshot below)
tryfoexnow.com
7 of 17
FOEX Installation Guide
Version 3.0.1
e.g.
cp –r ./server /u01/app/apex/images/foex
4. For each application ensure that the FOEX Application Settings plugin is set
with the correct location for both the FOEX source and Ext JS source
APEX 5.x
tryfoexnow.com
8 of 17
FOEX Installation Guide
Version 3.0.1
Upgrading a FOEX installation
If you already have a version of the FOEX Plugin Framework installed (e.g. V1.2.x),
then you can easily upgrade that to the current version V3.0.1.0 by following the
instructions in the chapter Installing the FOEX Plugin Framework.
After the new version is installed you can drop all old FOEX Schemas (e.g.
FOEX_010000, FOEX_010200, FOEX_010204 and others not reflecting the
current version number if they are no longer in use. Since you can run multiple
versions of FOEX in the same database it would be a good idea to check that
they are no longer in use before dropping the schemas).
To update all your FOEX applications you have to update all the FOEX plugins
installed within them, after you have completed the install of the new FOEX
version.
You can update all the plugins using a single script as described in the following
chapter Loading plugins into an existing application.
Loading plugins into an existing application
You can do that either using the standard APEX Application Builder functionality
and upload each plugin file one by one, or you can log on to SQLPLUS and run
the load_all_plugins_into_app_id.sql script as follows:
1. Unzip the provided FOEX Plugin Framework zip file
2. Change your working directory to the unzipped folder
3. Change to subdirectory:
APEX 5.0:
cd apex/apex_50
tryfoexnow.com
9 of 17
FOEX Installation Guide
Version 3.0.1
4. Start SQL*Plus and connect either to your applications parsing schema or to
SYS
5. Execute the script load_all_plugins_into_app_id.sql and pass the
application ID you want to update to the new FOEX plugins as argument
SQL> @load_all_plugins_into_app_id 123
6. Repeat Step 5 for each application ID you created using FOEX plugins
Uninstall FOEX Plugins
Simply run the uninstall script and remove the files copied to the HTTP Server:
1. Start SQL*Plus and connect to the database where Oracle Application
Express is installed as SYS specifying the SYSDBA role.
For Example:
$ sqlplus /nolog
SQL> CONNECT SYS AS SYSDBA
Enter password: <sys-password>
2. Run the Uninstall Script
• @foex_uninstall
3. Remove the files under your HTTP server
tryfoexnow.com
10 of 17
FOEX Installation Guide
Version 3.0.1
Downgrade to an earlier FOEX version
After installing a new version (i.e. V3.0.1.0) you can roll back to a previously
installed version of FOEX (if you didn’t uninstalled the previous version(s) )
following these steps:
1. Uninstall the current version by running the foex_uninstall.sql script
located in your V3.0.1.0 zip file
2. Locate the zip file of your previous installation (ie. V1.2.4) and unzip it
3. Start SQL*Plus and connect to the database where Oracle Application
Express is installed as SYS specifying the SYSDBA role. For example:
$ sqlplus /nolog
SQL> CONNECT SYS AS SYSDBA
Enter password: <sys-password>
4. Re-create the public synonyms
@db/fx_grant_foex_to_public.sql
5. Copy the HTTP server files of your previous version to the server
6. Optionally (if you have upgraded the plugins in your application), please
run Loading plugins into an existing application from the source you are
rolling back to, for each application, to ensure you have the correct
version of plugins that match the FOEX installation.
After executing this script delete any new plugins that are not in use and
have a higher version number than the version you have rolled back to
(these plugins would have been introduced in the new version)
tryfoexnow.com
11 of 17
FOEX Installation Guide
Version 3.0.1
Upgrading the APEX software installation
If you upgrade your APEX installation you have 2 options:
1. Install the latest version of FOEX (if you have not upgraded yet) and
upgrade your applications by executing the script
load_all_plugins_into_app_id.sql to load the latest version of the
plugins into each upgraded application.
2. Or, if you want to stay on your existing version of FOEX or are on the latest
version, you need to run the foex_upgrade_apex_installation.sql script
located in the base folder of the FOEX Plugin Framework zip file.
Example: you install FOEX 2.2.0 on APEX 4.2.6 and after a while decide to
upgrade APEX to 5.0.0. In that case you need to tell FOEX about the new APEX
version by running foex_upgrade_apex_installation.sql:
1. Start SQL*Plus and connect to the database where Oracle Application
Express is installed as SYS specifying the SYSDBA role.
For example:
$ sqlplus /nolog
SQL> CONNECT SYS AS SYSDBA
Enter password: <sys-password>
2. Run the upgrade script
@foex_upgrade_apex_installation
If you run multiple versions of FOEX you will need to run the upgrade script for
each version of FOEX installed (i.e. you will need to locate the FOEX Plugin
Framework zip file for each of the versions, extract, and run the corresponding
foex_upgrade_apex_installation.sql file).
tryfoexnow.com
12 of 17
FOEX Installation Guide
Version 3.0.1
Installing on Oracle Database 12c
There are no special instructions for installing on 12c other than the
requirement that FOEX is installed into the PDB, not the root container.
Installing demo applications
The FOEX Plugin Framework comes with several template applications which you
will use as the basis to start each new project and a combined Documentation
and Demo Application which is very helpful in understanding the framework’s
features, capabilities and how to combine plugins together using dynamic
actions.
The Demo Application requires a number of supporting DB-Objects (Tables,
Triggers, Procedures, etc.)
Note: To upgrade an existing installation of the demos with a new version, simply run the
script again, it will replace the tables and applications.
Installing on a database with NLS-settings other than
AMERICAN_AMERICA.AL32UTF8:
Before calling SQL*Plus (Step 4) run following commands.
Linux/Unix:
export NLS_LANG=AMERICAN_AMERICA.AL32UTF8
Windows:
set NLS_LANG=AMERICAN_AMERICA.AL32UTF8
tryfoexnow.com
13 of 17
FOEX Installation Guide
Version 3.0.1
To Install the FOEX Demo Applications:
1. Unzip the provided FOEX Plugins zip file
2. Create a new APEX workspace and schema e.g. FOEX_DEMOS_210 to
house the demo and documentation application. We suggest that you do
this for each version of FOEX so you can refer to the docs that match the
version of your application since you may be running more than one
version in production.
Alternatively, reuse an existing workspace if you don’t mind mixing FOEX
demo applications with other existing applications.
3. Change your working directory to the unzipped folder
4. Start SQL*Plus and connect to the database where Oracle Application
Express is installed as SYS specifying the SYSDBA role.
For example:
$ sqlplus /nolog
SQL> CONNECT SYS AS SYSDBA
Enter password: <sys-password>
5. Run the Install Script
@foex_install_demos workspace schema
Where:
i. workspace is the name of the workspace the applications should be
installed at
ii. schema is the name of the schema of the workspace where the DB
objects should be installed i.e. your APEX application parsing schema (do
not install these in the FOEX_XXXXX schema i.e. FOEX_030000)
e.g.
SQL> @foex_install_demos FOEX_DEMOS_210 FOEX_DEMOS_210
tryfoexnow.com
14 of 17
FOEX Installation Guide
Version 3.0.1
6. If your installation of FOEX does not use the default location of
#IMAGE_PREFIX#foex/ then please update the FOEX Source Directory
attribute within the FOEX Application Settings component settings defined
in Step 4 of Copying the HTTP Server Files for each demo/template
application installed in the previous step.
Note: Some of the demos use DBMS_META_DATA to display Code of Public APEX Views. In
order to get that running via APEX you have to grant following rights to the database
schema you installed the demos into:
• GRANT SELECT_CATALOG_ROLE TO <schema>;
• ALTER USER <schema> DEFAULT ROLE SELECT_CATALOG_ROLE;
tryfoexnow.com
15 of 17
FOEX Installation Guide
Version 3.0.1
Appendix A: Privileges required for the FOEX
installation
This installation guide is using a SYSDBA connection for the installation
instructions. If that is something you want to avoid, you can set up an alternative
user which has the following privileges:
Privilege
Admin Option
ALTER ANY INDEX
NO
ALTER ANY TABLE
NO
ALTER ANY TRIGGER
NO
ALTER SESSION
NO
ALTER USER
NO
CREATE ANY INDEX
NO
CREATE ANY PROCEDURE
NO
CREATE ANY SEQUENCE
NO
CREATE ANY SYNONYM
NO
CREATE ANY TABLE
NO
CREATE ANY TRIGGER
NO
CREATE ANY TYPE
NO
CREATE ANY VIEW
NO
CREATE INDEXTYPE
YES
CREATE PROCEDURE
YES
CREATE PUBLIC SYNONYM
NO
CREATE SEQUENCE
YES
CREATE SESSION
NO
CREATE SYNONYM
YES
tryfoexnow.com
16 of 17
FOEX Installation Guide
Version 3.0.1
CREATE TABLE
YES
CREATE TRIGGER
YES
CREATE TYPE
YES
CREATE USER
NO
CREATE VIEW
YES
DROP PUBLIC SYNONYM
NO
DROP ANY PROCEDURE
NO
DROP ANY SEQUENCE
NO
DROP ANY SYNONYM
NO
DROP ANY TABLE
NO
DROP USER
NO
EXECUTE ANY PROCEDURE
NO
GRANT ANY OBJECT PRIVILEGE
NO
INSERT ANY TABLE
NO
SELECT ANY TABLE
NO
UPDATE ANY TABLE
NO
Additionally the user requires
• an EXECUTE Grant with Admin Option on SYS.UTL_HTTP
• an EXECUTE Grant with Admin Option on SYS.DBMS_CRYPTO
• a SELECT Grant on SYS.DBA_TABLESPACES
• and a grant on APEX_ADMINISTRATOR_ROLE
Note: The above will need to be granted to your schema by your database
administrator first before being able to install the FOEX Plugin Framework.
tryfoexnow.com
17 of 17