Oracle

APEX Scrip/ng 101: The Command

Line Is Your Friend

Dietmar Aust
Opal-Consul/ng, Köln
www.opal-consul/ng.de
Dietmar Aust

► Dipl.-Inform. Dietmar Aust, Freelance Consultant

▪  Master's Degree in Computer Science (MSCS)

► Building Oracle based Web Applica/ons since 1997

▪  Portal, Forms, Reports, OWA Toolkit, now APEX!

► 1997-2000: Consultant at Oracle Germany

► Since 09/2000: Freelance Consultant, Since 2006 – APEX

only!

► Blog: h\p://daust.blogspot.com/

► Regular presenter at Oracle conferences (ODTUG, DOAG,

OOW)

► Author of the JasperReportsIntegra/on toolkit

▪  h\p://www.opal-consul/ng.de/tools

Oracle APEX Scripting 101: The Command Line Is Your Friend 28.06.2016 Page 3
Dietmar Aust

► 2015 Database Developer of the year in the ORDS category

Oracle APEX Scripting 101: The Command Line Is Your Friend 28.06.2016 Page 4
 Agenda

Oracle APEX Scripting 101: The Command Line Is Your Friend 28.06.2016 Page 5
Agenda

► Exports and Backups

▪  Anatomy of an export file
▪  APEXExport, APEXExportSpli\er

► Deployment
▪  APEX_APPLICATION_INSTALL
▪  APEX_INSTANCE_ADMIN
▪  BUILD_OPTIONS
▪  APEX_LANG

► sqlcl

Oracle APEX Scripting 101: The Command Line Is Your Friend 28.06.2016 Page 6

Why Command Line Scrip/ng?

Why automate?
Quality Performance







•  Manual procedures => did I
miss anything?
•  Time pressure => I rather
sleep well

Oracle APEX Scripting 101: The Command Line Is Your Friend 28.06.2016 Page 7
Warum Scrip/ng?

► Principles
▪  80/20
▪  KISS

Oracle APEX Scripting 101: The Command Line Is Your Friend 28.06.2016 Page 8
Exports and Backups

Oracle APEX Scripting 101: The Command Line Is Your Friend 28.06.2016 Page 9
Exports and Backups
Anatomy of an export file

► Pure SQL text file, encoded as UTF-8

► Different components separated by comments

► even BLOBS are hex-encoded as text

Oracle APEX Scripting 101: The Command Line Is Your Friend 28.06.2016 Page 10
Exports and Backups
Anatomy of an export file

► Everything happens within a database transac/on

▪  First delete applica/on, then install again from scratch

► In case of a sql error, rollback happens automa/cally

► APEX is metadata-driven, thus each "object" in APEX (template, bu\on,

region, etc.) has its own unique ID

Oracle APEX Scripting 101: The Command Line Is Your Friend 28.06.2016 Page 11
Exports and Backups
Anatomy of an export file

► In order to avoid conflicts in the medatata repository during export/import

APEX works with numerical ranges for each applica/on using OFFSETs

► An OFFSET is derived numerically from the applica/on-id

► Each applica/on id is unique within the APEX instance

Oracle APEX Scripting 101: The Command Line Is Your Friend 28.06.2016 Page 12
Exports and Backups
Export from the applica/on builder

► Workspace export has two op/ons (as of APEX 5.0)

► Minimal:
▪  Workspace-defini/on
▪  Groups, Users

Oracle APEX Scripting 101: The Command Line Is Your Friend 28.06.2016 Page 13
Exports and Backups
Export from the applica/on builder

► The FULL workspace export now contains EVERYTHING (with the excep/on of
applica/ons, websheets and workspace sta/c files)
▪  --mail
▪  -- W O R K S P A C E
▪  --mail log
▪  -- G R O U P S
▪  --app models
▪  -- U S E R S
▪  --password history
▪  --Applica/on Builder Preferences
▪  --preferences
▪  --Click Count Logs
▪  --query builder
▪  --csv data loading
▪  --sql scripts
▪  --sql workshop history
► Why? Used for the Oracle Cloud to
move workspaces do a different ▪  Resqul service defini/ons, ...
instance transparent to the user.

► Export of the workspace sta/c files using APEXExport command line u/lity in
the apex/u/li/es directory (see the Readme.txt file there):
java oracle.apex.APEXExport -db localhost:1521:xe -user test

-password <pwdTest> -workspaceid 2614526486790575 -expFiles

Oracle APEX Scripting 101: The Command Line Is Your Friend 28.06.2016 Page 14
Exports and Backups
Export from the applica/on builder

► Applica/on-Export

Oracle APEX Scripting 101: The Command Line Is Your Friend 28.06.2016 Page 15
Exports and Backups
Export from the applica/on builder

► Applica/on-Export

Oracle APEX Scripting 101: The Command Line Is Your Friend 28.06.2016 Page 16
Exports and Backups
APEXExport

APEX Export Class – the command line alterna/ve

► Part of the APEX download:

► Requirements
▪  JDK 1.5
▪  Oracle JDBC library is found on the classpath, at least ojdbc5.jar

Oracle APEX Scripting 101: The Command Line Is Your Friend 28.06.2016 Page 17
Exports and Backups
APEXExport

► Typical Use Cases

► Backup
▪  the whole APEX instance
▪  a single workspace
▪  one or more applica/ons

► Propagate applica/ons
▪  Export applica/ons, so that they can be imported into other systems like Q/A or
produc/on automa/cally

Demo
Oracle APEX Scripting 101: The Command Line Is Your Friend 28.06.2016 Page 18
Exports and Backups

► We can build everything by ourselves … or?

▪  h\p://ischaicham.com/wiki/
Oracle_APEX_applica/on_and_workspace_backup_script
▪  h\p://sve.to/2012/03/12/automa/cally-backup-oracle-apex-applica/ons-to-
subversion/

► OraOpenSource / APEX Backup

▪  h\p://www.talkapex.com/2015/04/apex-backup-script.html
▪  h\ps://github.com/OraOpenSource/apexbackup

Oracle APEX Scripting 101: The Command Line Is Your Friend 28.06.2016 Page 19
Exports and Backups
APEXSpli\er

APEX Spli\er Class

► Part of the APEX download:

► Requirements
▪  JDK 1.5
▪  Oracle JDBC library is found on the classpath, at least ojdbc5.jar

Oracle APEX Scripting 101: The Command Line Is Your Friend 28.06.2016 Page 20
Exporte und Backups
APEXSpli\er

► Export hierarchical with subdirectories or FLAT

► Can see easily the differences (on a technical level) when coupled with version
control systems

Oracle APEX Scripting 101: The Command Line Is Your Friend 28.06.2016 Page 21
 Deployment

Oracle APEX Scripting 101: The Command Line Is Your Friend 28.06.2016 Page 22
Deployment

This is how it should be …

APEX Development APEX Test

APEX Production

Oracle APEX Scripting 101: The Command Line Is Your Friend 28.06.2016 Page 23
Deployment

... this is what it typically looks like ...

APEX Development / APEX Production

Test and Integration
Environment

Oracle APEX Scripting 101: The Command Line Is Your Friend 28.06.2016 Page 24
Deployment

... and unfortunately this is not really a rare case ...

Schema A Schema B

APEX Development /
Test and Integra7on APEX Produc7on
Environment

Oracle APEX Scripting 101: The Command Line Is Your Friend 28.06.2016 Page 25
Deployment

Prepara/on for the simplest approach

► Create iden/cal workspaces in all environments => iden/cal workspace ID
▪  Create them using export/import of the workspace (as sql script)
▪  Create them using the apex_instance_admin api
▪  Create them by cloning the instances

► Advantages
▪  SQL scripts can be run unmodified on all systems (DEV, TEST, PROD)
−  PARSING_SCHEMA
−  Applica/on ID
−  Workspace ID

▪  Single page or component export works without problems

Oracle APEX Scripting 101: The Command Line Is Your Friend 28.06.2016 Page 26
Deployment

What could these scripts look

like?

Oracle APEX Scripting 101: The Command Line Is Your Friend 28.06.2016 Page 27
 Deployment
Sample installa/on script
*) set NLS_LANG on the command line
set NLS_LANG=GERMAN_GERMANY.WE8MSWIN1252

*) run patch as user SHDB_JDA
@_patch_shdb_jda.sql


*) run patch as user SHDB_200
@_patch.sql

*) install APEX applications
set NLS_LANG=GERMAN_GERMANY.AL32UTF8

sqlplus shdb_200

DECLARE
l_workspace_id NUMBER;
BEGIN
l_workspace_id := APEX_UTIL.FIND_SECURITY_GROUP_ID ('WORKSPACE_NAME');
apex_application_install.set_workspace_id (l_workspace_id);
apex_application_install.set_application_id(104);
apex_application_install.set_schema('SHDB_200');
END;
/

@apex/f104_Spots_v15.2.0.0.sql
Oracle APEX Scripting 101: The Command Line Is Your Friend 28.06.2016 Page 28
Deployment
APEX_APPLICATION_INSTALLATION

Install – varia/ons with apex_applica/on_install

► The basis is the applica/on export file, some hardcoded sesngs can be
overridden at install /me:

Oracle APEX Scripting 101: The Command Line Is Your Friend 28.06.2016 Page 29
 Deployment
APEX_APPLICATION_INSTALLATION

Installa/on: different workspace and different applica/on id

DECLARE
l_workspace_id NUMBER;
BEGIN
l_workspace_id := APEX_UTIL.FIND_SECURITY_GROUP_ID ('WORKSPACE_NAME');
apex_application_install.set_workspace_id (l_workspace_id);
apex_application_install.set_application_id(104);
apex_application_install.set_application_alias('F'
|| apex_application_install.get_application_id);
apex_application_install.generate_offset;
END;
/

@f100.sql

► A new OFFSET must be generated whenever the applica/on id changes

► Set new alias when the applica/on already exists in the target instance

Oracle APEX Scripting 101: The Command Line Is Your Friend 28.06.2016 Page 30
 Deployment
APEX_APPLICATION_INSTALLATION

Installa/on with generated applica/on id

BEGIN
apex_application_install.generate_application_id;
apex_application_install.generate_offset;
END;
/

@f100.sql

► A new OFFSET must be generated whenever the applica/on id changes

Oracle APEX Scripting 101: The Command Line Is Your Friend 28.06.2016 Page 31
 Deployment
APEX_APPLICATION_INSTALLATION

Installa/on with different parsing schema

BEGIN
apex_application_install.set_schema('SCHEMA_NEW');
END;
/

@f100.sql

Oracle APEX Scripting 101: The Command Line Is Your Friend 28.06.2016 Page 32
Deployment
APEX_INSTANCE_ADMIN

Package APEX_INSTANCE_ADMIN
► Command line equivalents for all func/onali/es provided by the INTERNAL
workspace administra/on GUI

► Especially important in an APEX RUNTIME ONLY environment since there is no

GUI available

► Requirements?
GRANT APEX_ADMINISTRATOR_ROLE to <Oracle Schema>;

► Read and write instance sesngs

► Manage workspaces and user

► Interac/ve reports (manage saved reports and subscrip/ons)

Oracle APEX Scripting 101: The Command Line Is Your Friend 28.06.2016 Page 33
Deployment
APEX_INSTANCE_ADMIN

► Create workspace using a script

BEGIN
APEX_INSTANCE_ADMIN.ADD_WORKSPACE (
p_workspace_id => 8675309,
p_workspace => 'MY_WORKSPACE',
p_primary_schema => 'SCOTT',
p_additional_schemas => 'HR:OE' );
END;

► Add workspace – schema mapping

BEGIN
APEX_INSTANCE_ADMIN.ADD_SCHEMA('MY_WORKSPACE','HR');
END

Oracle APEX Scripting 101: The Command Line Is Your Friend 28.06.2016 Page 34
Deployment
APEX_INSTANCE_ADMIN

► Read and write instance sesngs

► Display all current instance sesngs:

Script in directory
APEX-Install/apex/u/li/es

Oracle APEX Scripting 101: The Command Line Is Your Friend 28.06.2016 Page 35
Deployment
Build Op/ons

Build Op/ons
► Used to enable / disable parts of an applica/on

► Boolean switch: ON or OFF (APEX: Include or Exclude)

► Can be applied to almost every APEX “object”: page, tab, list element, lov,
bu\on, process, dynamic ac/on, …

► Configure features, which you might not want to deploy to produc/on

▪  All “objects” and code is always part of the exported file, it us just not enabled on
the produc/on system
▪  The build op/on will only be taken into account at run/me

► We can use a pl/sql api to determine the current state

and thus program against it

Oracle APEX Scripting 101: The Command Line Is Your Friend

Demo
28.06.2016 Page 36
Deployment
Build Op/ons

► Enable / disable a build op/on:

► Thus we can selec/vely enable / disable features at install /me or later on the
command line

Oracle APEX Scripting 101: The Command Line Is Your Friend 28.06.2016 Page 37
Deployment
APEX_LANG (version 4.2.3 and later)

► apex_lang.create_language_mapping
/ update / delete

► apex_lang.seed_application

► apex_lang.update_translated_string

► apex_lang.publish_application

Oracle APEX Scripting 101: The Command Line Is Your Friend 28.06.2016 Page 38
Deployment
APEX_LANG

► By using publish_applica/on a “shadow applica/on” is created

► During the applica/on export typically all translated strings for all languages
are included – the shadow applica/ons for the different translated are NOT
created on the target system automa/cally.

► Why? The basic idea was to be able to export/import each translated

applica/on by separately.

Oracle APEX Scripting 101: The Command Line Is Your Friend 28.06.2016 Page 39
Deployment
APEX_LANG

► Publish an applica/on on the new system into the target language

BEGIN
APEX_UTIL.set_security_group_id (
APEX_UTIL.find_security_group_id ('OPAL'));

apex_lang.publish_application (p_application_id => 109,
p_language => 'en');
END;
/

► Modifying texts without the regular XLIFF - procedure

▪  apex_lang.seed_transla/ons
▪  apex_lang.update_translated_string for all texts that have changed
▪  apex_lang.publish_applica/on

Oracle APEX Scripting 101: The Command Line Is Your Friend 28.06.2016 Page 40
 SQLcl

Oracle APEX Scripting 101: The Command Line Is Your Friend 28.06.2016 Page 41
Command Line – SQLcl

SQLcl – A Java based alterna/ve / replacement to SQL*Plus

► Developed by the SQL Developer Team => many features available

► h\p://www.oracle.com/technetwork/developer-tools/sqlcl/overview/
index.html

► Installa/on as a zip file, no install or setup neccessary

▪  13MB
▪  Uses Java, thus only a single version for Windows, Linux and OS X
▪  Requires Java 8 run/me environment, not a JDK
▪  No addi/onal licence required

Oracle APEX Scripting 101: The Command Line Is Your Friend 28.06.2016 Page 42
Command Line – SQLcl

► Currently s/ll early adopter (Version 4.2.0.16.131.1023, 13.05.2016)

► Planned release together with Oracle Database 12cR2

► Connect to Oracle DB:

▪  EZ Connect:

▪  If ORACLE_HOME is set then also:

−  TNS,
−  Thick OCI and even
−  LDAP connec/ons

► Display help using

▪  help
▪  help <command>

Oracle APEX Scripting 101: The Command Line Is Your Friend 28.06.2016 Page 43
Command Line – SQLcl
The editor

► Edi/ng of statements in the SQL buffer => VERY cool J

▪  ctrl-w , ctrl-s navigates to the beginning / end of the buffer
▪  Cursor up/down changes lines

► TAB-autocomplete
▪  Complete commands, table names, view names, etc.

► Aliases => Shortcuts for SQL or PL/SQL

► Extract DDL with dbms_metadata

► Export APEX applica/ons

► Export REST applica/ons

► Integra/on with mul/ple JVM based scrip/ng languages / JSR-223

Oracle APEX Scripting 101: The Command Line Is Your Friend 28.06.2016 Page 44
Sqlcl scrip/ng

Demo

Oracle APEX Scripting 101: The Command Line Is Your Friend 28.06.2016 Page 45
Sqlcl scrip/ng

► Gesng Started:
▪  h\ps://www.doag.org/formes/pubfiles/7535126/docs/Konferenz/2015/
vortraege/Oracle%20Datenbanken/2015-K-DB-Oded_Raz-
I_ve_seen_the_Future,_It_Is_Glorious__SQLcl_replace_SQLPlus-
Praesenta/on.pdf
▪  h\ps://www.youtube.com/watch?v=HApdy-o525A
▪  h\ps://www.doag.org/formes/pubfiles/7535126/docs/Konferenz/2015/
vortraege/Oracle%20Datenbanken/2015-K-DB-Oded_Raz-
I_ve_seen_the_Future,_It_Is_Glorious__SQLcl_replace_SQLPlus-
Praesenta/on.pdf
▪  h\p://www.oracle.com/technetwork/issue-archive/2015/15-sep/o55sql-
dev-2692807.html

► Blog von Kris Rice: h\p://krisrice.blogspot.de/search/label/sdsql

► Github – Beispiele aus dem Team

▪  h\ps://github.com/oracle/oracle-db-tools/tree/master/sqlcl/examples
▪  h\ps://github.com/oracle/oracle-db-tools/tree/master/sqlcl

Oracle APEX Scripting 101: The Command Line Is Your Friend 28.06.2016 Page 46
 Contact
Dietmar Aust
Opal-Consul/ng, Köln

www.opal-consul/ng.de
daust.blogspot.com
dietmar.aust@opal-consul/ng.de

Oracle APEX Scripting 101: The Command Line Is Your Friend 28.06.2016 Page 47