Installation Guide Version 3.1.0 @FOEXplugins Last updated: November tryfoexnow.com 1 of 3
FOEX Installation Guide, version 3.1.0 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 November 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
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
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.1.0 of the FOEX Plugin Framework requires Oracle APEX 5.0.x or 5.1.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
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
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
7. Once the above script is complete a new schema named FOEX_030100 will be created. You can lock the FOEX_030100 schema for added security. E.g. SQL> alter user FOEX_030100 account lock; This installation creates a new schema called FOEX_030100. 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
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 E.g. SQL> @foex_install USERS TEMP N 7. Once the above script is complete a new schema named FOEX_030100 will be created. You can lock the FOEX_030100 schema for added security. E.g. SQL> alter user FOEX_030100 account lock; 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_030100) ii. user_schema is the name of the user/schema the rights should be granted to tryfoexnow.com 5 of 17
Installing the License Key Starting with FOEX 3.1.0 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 support@tryfoexnow.com. 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
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-310 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) e.g. tryfoexnow.com 7 of 17
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
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.1.0.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_020000, FOEX_020200, FOEX_030000 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
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
Downgrade to an earlier FOEX version After installing a new version (i.e. V3.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.1.0 zip file 2. Locate the zip file of your previous installation (ie. V3.0.1) 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 S Q L > C O N N E C T S Y S A S S Y S D B A 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
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 3.1.0 on APEX 5.0.4 and after a while decide to upgrade APEX to 5.1.3. 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 S Q L > C O N N E C T S Y S A S S Y S D B A 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
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
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_310 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 November 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 S Q L > C O N N E C T S Y S A S S Y S D B A 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_030100) e.g. SQL> @foex_install_demos FOEX_DEMOS_310 FOEX_DEMOS_310 tryfoexnow.com 14 of 17
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
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 ALTER ANY INDEX ALTER ANY TABLE ALTER ANY TRIGGER ALTER SESSION ALTER USER CREATE ANY INDEX CREATE ANY PROCEDURE CREATE ANY SEQUENCE CREATE ANY SYNYM CREATE ANY TABLE CREATE ANY TRIGGER CREATE ANY TYPE CREATE ANY VIEW CREATE INDEXTYPE CREATE PROCEDURE CREATE PUBLIC SYNYM CREATE SEQUENCE CREATE SESSION CREATE SYNYM Admin Option YES YES YES YES tryfoexnow.com 16 of 17
CREATE TABLE CREATE TRIGGER CREATE TYPE CREATE USER CREATE VIEW DROP PUBLIC SYNYM DROP ANY PROCEDURE DROP ANY SEQUENCE DROP ANY SYNYM DROP ANY TABLE DROP USER EXECUTE ANY PROCEDURE GRANT ANY OBJECT PRIVILEGE INSERT ANY TABLE SELECT ANY TABLE UPDATE ANY TABLE YES YES YES YES 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