Skip to main content

Quick Install Guide

Quick Install Guide​

This guide will install the PL/SQL packages and the Oracle APEX plug-ins for AOP​

  1. Unzip the file you downloaded from https://www.apexofficeprint.com

  2. Install the PL/SQL API.

    • Go in APEX to SQL Workshop > SQL Scripts > Upload
    • Select file /db/aop_db_pkg.sql
    • Give it a name and click the Upload button.
    • Click the run icon for the script you just uploaded, confirm that the schema in the upper right-hand corner of the screen is correct and click Run Now.
    • All statements should be successful.

    Repeat the above for /db/aop_modal_pkg.sql

  3. Import new versions of the plug-ins.

    • Go in APEX to App Builder > Your application > Shared Components > Plug-ins > Import
    • Be sure to select the directory that corresponds to the version of Oracle APEX you are using - NOT the version of AOP.
    • Select file /plugin/process_type_plugin_be_apexrnd_aop.sql (for the AOP Process type plug-in)
    • Select file /plugin/dynamic_action_plugin_be_apexrnd_aop_da.sql (for the AOP Dynamic Action type plug-in)
    • Select file /plugin/dynamic_action_plugin_be_apexrnd_aop_convert_da.sql (for the Convert Dynamic Action type plug-in)
    • Select file /plugin/dynamic_action_plugin_be_apexrnd_aop_modal.sql (for the Modal Dynamic Action type plug-in)
    • Enter the details of the AOP Server or in case the AOP Cloud is used the API key. If using the cloud version of AOP, make sure the API Key is set for each plug-in.
      An API Key is not necessary for on-premises installations.

That is it! On the page you want to use AOP, add the "APEX Office Print" Dynamic Action or Process.

Optional you can also install the sample application​

Install the AOP Sample Applications.

  • Import the AOP Sample Apps you find in /app
  • You can import them in any order.
  • Make sure that you install the Supporting Objects. This will install the necessary database objects to run the sample applications.

Testing the connection from PL/SQL to the AOP Server​

Depending your environment, only HTTPS connections might be allowed. This is the case for the Oracle Cloud for example.

You want to check your connection by running the following in SQL Workshop > SQL Commands:

-- HTTP
begin
  -- in case of an on-premises AOP Server, change the URL
  aop_api_pkg.send_aop_sample(
    p_url            => 'http://api.apexofficeprint.com',
    p_proxy_override => null,
    p_wallet_path    => null,
    p_wallet_pwd     => null);
end;

begin
  -- in case of an on-premises AOP Server, change the URL
  aop_api_pkg.is_aop_accessible(
    p_url            => 'http://api.apexofficeprint.com',
    p_proxy_override => null,
    p_wallet_path    => null,
    p_wallet_pwd     => null);
end;

-- HTTPS
begin
  -- in case of an on-premises AOP Server, change the URL
  aop_api_pkg.send_aop_sample(
    p_url            => 'https://api.apexofficeprint.com',
    p_proxy_override => null,
    p_wallet_path    => null,
    p_wallet_pwd     => null);
end;

begin
  -- in case of an on-premises AOP Server, change the URL
  aop_api_pkg.is_aop_accessible(
    p_url            => 'https://api.apexofficeprint.com',
    p_proxy_override => null,
    p_wallet_path    => null,
    p_wallet_pwd     => null);
end;

In order to connect to the AOP Cloud over HTTPS, you may need to install the SSL certificate in your Oracle Wallet. The Oracle Cloud has our certificate loaded by default. Here are the commands to install our certificate in your own Oracle Wallet. First make sure to copy the file /db/AmazonRootCA.cer to your database server e.g. in the directory /opt/oracle/admin/XE/.

orapki wallet create -wallet /opt/oracle/admin/XE/ -pwd YourWalletPasswd -auto_login
orapki wallet add -wallet /opt/oracle/admin/XE/ -trusted_cert -cert "/opt/oracle/admin/XE/AmazonRootCA.cer" -pwd YourWalletPasswd

In order to test the connection manually, you can do in SQL:

select apex_web_service.make_rest_request(
        p_url         => 'https://api.apexofficeprint.com',
        p_http_method => 'GET',
        p_wallet_path => 'file:/opt/oracle/admin/XE/',
        p_wallet_pwd  => 'YourWalletPasswd') as r
  from dual

Connection issues to the AOP Server or AOP Cloud are most of the time due to an invalid configuration of the TNS, ACL or Wallet. If a call to apex_web_service works in SQL, but still not in your Oracle APEX application, it's most likely that the wallet path and password are not specified in the INTERNAL workspace of your Oracle APEX environment.

Runtime-only environment, install from SQL command line​

To install the AOP packages in a runtime-only Oracle APEX environment, connect with the Oracle database user/schema where you want to deploy AOP e.g. HR.

Run two files:

@/db/aop_db_pkg.sql
@/db/aop_modal_pkg.sql

This will create the AOP PL/SQL API that the Oracle APEX Plug-ins use. The plug-ins are part of your Oracle APEX application and don't need to imported manually.

Possible issues you might encounter​

ORA-29273: HTTP request failed ORA-06512: at "SYS.UTL_HTTP", line 1130 ORA-24247: network access denied by access control list (ACL)​

Make sure the APEX schema has the rights to connect to the AOP Server (http(s)://www.apexofficeprint.com for the Cloud version or your local URL in case of the on-premises version).

Here's an example how to allow the APEX_230100 schema to connect to any URL:

BEGIN
    DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
        host => '*',
        ace => xs$ace_type(privilege_list => xs$name_list('connect'),
                           principal_name => 'APEX_230200',
                           principal_type => xs_acl.ptype_db));
END;
/

ORA-29273: HTTP request failed ORA-06512: at "SYS.UTL_HTTP", line 1130 ORA-29024: Certificate validation failure​

This means you are trying to access an HTTPS URL, but the certificate is not loaded correctly in the Oracle wallet.

There're two ways to get around this:

  • Option 1: You can load our certificates in your Oracle wallet (the Oracle DB is doing the call to our server). See above for instructions using orapki.
  • Option 2: You can add an entry in your webserver so a local entry is called by the database (which doesn't need a certificate) and the webserver is doing the redirect to handle the https call.

Here's an example when in the plug-in you would specify a local address: http://apexrnd.localdomain/aop/

<VirtualHost *:80>
ServerName  apexrnd.localdomain
ServerAlias apexrnd.localdomain
RewriteEngine On
ProxyVia On
ProxyRequests Off
SSLProxyEngine On
ProxyPass        /aop/   https://api.apexofficeprint.com/
ProxyPassReverse /aop/   https://api.apexofficeprint.com/
</VirtualHost>

PLS-00753: malformed or corrupted wrapped unit​

There might be multiple reasons why you get this. There might be a permission issue, most likely on UTL_FILE. Another reason might be that during uploading of the script in SQL Workshop > SQL Scripts the File Character Set was not set to Unicode UTF-8.

ORA-20000: The AOP Server can not process your request. RequestID: xxxx-xxxxx Error while generating file. Please contact AOP for further inquiry​

This error means the AOP Server has difficulties full-filling your request. In this case it's best to debug the request to the AOP Server or AOP Cloud. You can get the debug JSON by inserting the following PL/SQL code in the Init PL/SQL section of the Dynamic Action or before you call the AOP PL/SQL API:

aop_api_pkg.g_debug := 'Local';

The next time you print, you should get a JSON. Once you have the local JSON file, go to https://www.apexofficeprint.com, sign-in with your registered email address and navigate to Support on the menu to contact us.

APEX Debugging​

When you run Oracle APEX in debug mode you can see how long a request took. In case you want to see more detailed debug information, run in LEVEL6 (=Application Trace) debug mode.

info

See this video how to set LEVEL6 debug on.