foex plugins installation guide - vireo.nwmhc.org plugins installation guide... ·...

Installation Guide

Release 2.2.0

May 2016

FOEX Installation Guide, Release 2.2.0 Copyright © 2015, FOEX GmbH. All rights reserved. Authors: Peter Raganitsch, Matt Nolan 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.

Contents REQUIREMENTS .............................................................................................................................. 4

ORACLE APPLICATION EXPRESS .................................................................................................................. 4 DATABASE CONNECTION .......................................................................................................................... 4 FOEX DEVELOPER ADDON ........................................................................................................................ 4 STORAGE REQUIREMENTS ......................................................................................................................... 4 BROWSER REQUIREMENTS ........................................................................................................................ 4

INSTALLING THE FOEX PLUGIN FRAMEWORK .................................................................................. 5 ALTERNATIVE: INSTALLING FOEX WITH PRIVATE SYNONYMS .......................................................... 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 FOEX INSTALLATION TO AN EARLIER VERSION ........................................................ 10 UPGRADING THE APEX SOFTWARE INSTALLATION ........................................................................ 11 INSTALLING ON ORACLE DATABASE 12C ........................................................................................ 11 INSTALL DEMO APPLICATIONS ....................................................................................................... 12 APPENDIX A: PRIVILEGES REQUIRED FOR FOEX INSTALLATION ...................................................... 14

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 2.2.0 of the FOEX Plugin Framework requires Oracle APEX 4.2.x to be installed or Oracle APEX 5.0.x. Lower or higher 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 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 “FOEX Developer Addon” (FDA) for Google Chrome and Firefox browsers. This means we only support Development of FOEX Applications within these 2 Browsers when using the FDA. See the “FOEX First Steps” guide for installation instructions.

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 installed are required to develop FOEX applications in Oracle Application Express:

• Mozilla Firefox 29 or later version • Google Chrome 30 or later version

FOEX applications can be executed (run) in these Web browsers:

• Microsoft Internet Explorer 9.0 or later version • Mozilla Firefox 11 or later version • Google Chrome 18 or later version • Apple Safari 5.1 or later version

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 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 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

7. Once the above script is complete a new schema named FOEX_020200 will be created. You can lock the FOEX_020200 schema for added security. E.g.

• SQL> alter user FOEX_020200 account lock; This Installation creates a new schema called FOEX_020200.

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: a. $ sqlplus /nolog

SQL> CONNECT SYS AS SYSDBA Enter password: <sys-password>

4. If you want to avoid using SYSDBA, please refer to 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 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_020200 will be created. You can lock the FOEX_020200 schema for added security. E.g.

a. SQL> alter user FOEX_020200 account lock; This Installation creates a new schema called FOEX_020200. 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


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_020200) ii. user_schema is the name of the user/schema the rights should be

granted to

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 in 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 Server 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 is used, FOEX Plugins require 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. 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 4.2.x)

(APEX 5.x)

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 V2.2.0 by following the instructions in the previous chapter Installing the FOEX Plugin Framework. After the installation of the new Version 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 log on to SQLPLUS and run the load_all_plugins_into_app_id.sql Script:

1. Unzip the provided FOEX Plugin Framework zip file


3. Change to sub directory:

a. APEX 4.2 i. cd apex/apex_42

b. APEX 5.0 i. cd apex/apex_50

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 To 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


2. Run the Uninstall Script • @foex_uninstall

3. Remove the files under your HTTP server

Downgrade FOEX Installation to an earlier Version After installing a new version (i.e. V2.2.0) you can roll back to a previous installed version of FOEX (if you have not unistalled the previous version(s)) following these steps:

1. Uninstall the current version by running the foex_uninstall.sql script located in your V2.2.0 Zip file

2. Now locate the Zip-‐File of your previous installation (ie. V1.2.4) and unzip it



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 in your application 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)

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 yet upgraded) 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 then 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 :



2. Run the Upgrade Script • @foex_upgrade_apex_installation

Note: 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.

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.

Install Demo Applications The FOEX Plugin Framework comes with several template applciations 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 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 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. Or alternatively reuse an existing workspace if you don’t mind mixing FOEX demo applications with other existing applications.


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


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_020200)

• e.g. SQL> @foex_install_demos FOEX_DEMOS_210 FOEX_DEMOS_210

6. Note: if your installation of FOEX does not use the default location of

#IMAGE_PREFIX#foex/ then please update the “FOEX Source Directory” attribute within “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;

Appendix A: Privileges required for 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 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 that 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.

foex plugins installation guide - vireo.nwmhc.org plugins installation guide... ·...

Documents