FOEX Plugins Installation Guide Plugins Installation... · 2020-02-07 · Application Express Installation Guide. To install the FOEX Plugin Framework, follow these steps: 1. Unzip

www.foex.at of 1 3

@FOEXpluginsLast updated: February 2020

Installation GuideVersion 4.2.0

https://twitter.com/FOEXplugins

https://twitter.com/FOEXplugins

http://www.foex.at

www.foex.at of 2 3

FOEX Installation Guide, version 4.2.0

Copyright © 2019, 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.

http://www.foex.at

Table of Contents

Requirements 1 ........................................................................................................

Oracle Application Express 1 ...................................................................................

Database and 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 .........................................

Alternative: Installing FOEX without PL/SQL compilation enhancements 6 .....

Installing the License Key 7 .....................................................................................

Running multiple versions of FOEX 9 .....................................................................

Copying the HTTP server files 10 ............................................................................

Upgrading a FOEX installation 12 ...........................................................................

Loading plugins into an existing application 12 ...................................................

Uninstall FOEX Plugins 16 ........................................................................................

Downgrade to an earlier FOEX version 16 .............................................................

Upgrading the APEX software installation 17 .......................................................

Installing on Oracle Database 12c 18 .....................................................................

Installing demo applications 18 ..............................................................................

Appendix A: Privileges required for the FOEX installation 21.............................

www.foex.at of 3 3

FOEX Installation Guide Version 4.2.0

http://www.foex.at

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 4.2.0 of the FOEX Plugin Framework requires Oracle APEX 5.1.4 or 18.x or 19.x to be installed. Lower versions of Oracle APEX are not permitted or supported.

Database and Connection

This version can be installed in Oracle Database versions that are supported by the current version of Oracle APEX you are running.

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.

www.foex.at of 1 22


http://www.foex.at

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

www.foex.at of 2 22


http://www.foex.at

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

www.foex.at of 3 22


http://www.foex.at

https://docs.oracle.com/cd/E59726_01/install.50/e39144/toc.htm


http://www.oracle.com/pls/topic/lookup?ctx=E23903-01&id=DBSEG

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

E.g.

SQL> alter user FOEX_040200 account lock;

This installation creates a new schema called FOEX_040200.

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:




For example: $ sqlplus /nolog

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


www.foex.at of 4 22


http://www.foex.at

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


E.g. SQL> alter user FOEX_040200 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”


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

granted to

www.foex.at of 5 22



http://www.foex.at

Alternative: Installing FOEX without PL/SQL compilation enhancements

As of v4.0 FOEX uses PLSQL_OPTIMIZATION_LEVEL = 3 and NATIVE compilation of all its PL/SQL code. This brings a bit better performance in processing, but can lead to ORA-0600 in certain DB setups as described in this MOS Note: https://support.oracle.com/knowledge/Oracle%20Database%20Products/1625010_1.html

So if you run into an ORA-600, as described in that Note, you can set argument 4 of foex_install.sql to N to avoid NATIVE compilation of PL/SQL Code.

To do this follow these steps:




For example: $ sqlplus /nolog



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

www.foex.at of 6 22


http://www.foex.at

https://support.oracle.com/knowledge/Oracle%20Database%20Products/1625010_1.html

https://support.oracle.com/knowledge/Oracle%20Database%20Products/1625010_1.html


• SQL> @foex_install tablespace_foex tablespace_temp Y 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. Y creates public synonyms for FOEX objects iv. N avoids NATIVE compilation of PL/SQL code and uses the default

optimization level E.g. SQL> @foex_install USERS TEMP Y N


E.g. SQL> alter user FOEX_040200 account lock;

Installing the License Key

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.

www.foex.at of 7 22


https://support.foex.at

mailto:[email protected]

http://www.foex.at

$ sqlplus /nolog SQL> CONNECT SYS AS SYSDBA Enter password: <sys-password>

2. You can omit 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

www.foex.at of 8 22


http://www.foex.at

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

www.foex.at of 9 22


http://www.foex.at

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. cp –r ./server /u01/app/apex/images/foex

www.foex.at of 10 22


http://www.foex.at


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.1.x



http://www.foex.at

Upgrading a FOEX installation

If you already have a version of the FOEX Plugin Framework installed (e.g. V4.0.x), then you can easily upgrade that to the current version V4.2.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, FOEX_030100, FOEX_040001, FOEX_040100 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

The easiest way to create a FOEX application from scratch is to copy our provided template application which can be found in apex/base/ftemp42.sql However you can use also FOEX in existing APEX Applications. To do this, you first need to install our plugins, and then perform some post-installation steps.

The pre-requisite before you get started is that you have installed our browser extension the FOEX Developer Addon (FDA) : https://www.foex.at/foex-developer-addon/

Once the extension has been installed in your browser, you can install our plugins by logging on to SQL*PLUS and run the load_all_plugins_into_app_id.sql script as follows:



http://www.foex.at

https://www.foex.at/foex-developer-addon/

https://www.foex.at/foex-developer-addon/



3. Change to subdirectory: APEX 5.1: cd apex/base

4. Start SQL*Plus and connect either to your application 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. Now for FOEX to function correctly there are some additional things we need to setup (one time only). To start, in the APEX Builder under SQL Workshop -> “SQL Commands” please run the following:

BEGIN

FX_P_DEVELOPER_ADDON.Check_Preconditions(652);

END;



http://www.foex.at

7. Edit a page in your application to navigate to “Page Designer” and enable the “FOEX Developer Addon” (FDA)

8. Under “Shared Components” Navigate to “Security Attributes” and change the “Browser Security” -> “Embed in Frames” setting to “Allow from same origin” e.g.

9. Change the “Database Session” -> “Runtime API Usage” to “Modify this Application” e.g.



http://www.foex.at

10.**IMPORTANT** In order to auto-create some required FOEX templates and text messages in your application. Please create a temporary FOEX Page by navigating to you application and clicking on "Create FOEX Page" button e.g.

11. Run the page you created in the previous step (and optionally delete it afterwards if you don’t end up using it). By running the page from the APEX Builder (a developer session is required to do this) we will automatically create all required text messages, templates etc.

12. Repeat Steps 5-11 for each existing APEX application you want to use FOEX plugins in



http://www.foex.at

Uninstall FOEX Plugins

Simply run the uninstall script and remove the files copied to the HTTP Server:


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

Downgrade to an earlier FOEX version

After installing a new version (i.e. V4.2.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 V4.2.0 zip file

2. Locate the zip file of your previous installation (ie. V4.1.0) 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



http://www.foex.at

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)

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 4.2.0 on APEX 5.1.4 and after a while decide to upgrade APEX to 19.2. In that case you need to tell FOEX about the new APEX version by running foex_upgrade_apex_installation.sql:





http://www.foex.at

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

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.


http://www.foex.at

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




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


http://www.foex.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_040200)

e.g. SQL> @foex_install_demos FOEX_DEMOS_420 FOEX_DEMOS_420

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;


http://www.foex.at

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

CREATE TABLE YES

CREATE TRIGGER YES


http://www.foex.at

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.

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


http://www.foex.at

Documents

FOEX Plugins Installation Guide Plugins Installation... · 2020-02-07 · Application Express Installation Guide. To install the FOEX Plugin Framework, follow these steps: 1. Unzip