Installation

What is in the delivery

The ADM archive contains three things:

File	What it is
install.sql	Every database object: tables, views, packages, triggers, jobs, seed data, and the database side of the bundled APEX plug-ins.
f215.sql	The APEX application export.
uc_pip.pkw	The wrapped body of uc_pluginspro, which licenses the bundled United Codes plug-ins.

The AI Pack, if you have licensed it, ships as a separate install_ai.sql and is installed after the base product — see AI Pack installation.

Prerequisites

• Oracle Database 19c or later. Developed and tested against 19c and 23ai.
• Oracle APEX 24.2 or later. The application export is created from 24.2; importing into an older APEX release will fail.
• ORDS, for the APEX application itself, and for the bundled plug-ins that call back into the database — APEX Office Edit needs a REST endpoint in your workspace.
• A dedicated schema. Install ADM into its own schema rather than alongside an existing application. Every object is prefixed adm_, but the schema also receives the plug-in support objects.

Grants

The ADM schema needs these grants, issued as a privileged user:

grant execute on dbms_crypto to your_user;  -- checksums, share-link password hashing
grant execute on ctx_ddl to your_user;      -- Oracle Text, for full-text search
grant create any context to your_user;      -- the ADM_CONTEXT security context
grant create job to your_user;              -- the scheduled maintenance jobs

create any context

ADM’s entire permission model hangs off an Oracle application context named ADM_CONTEXT (see The security model). Without create any context the install completes but nothing is authorised correctly. If a second schema in the same database also creates a context with that name, it takes ownership of the global name and ADM starts raising ORA-01031; re-run ADM’s context script as the ADM user to claim it back.

REST-enable the schema

begin
  ords.enable_schema;
  commit;
end;
/

Installing

1. Run the database install.

   Connect as the ADM schema owner and run the script from the directory it lives in:

   sqlplus adm/password@db @install.sql

   It writes install_adm.log next to itself. The script does not stop on the first error, so read that log:

   grep -iE "ORA-|PLS-|warning" install_adm.log

2. Confirm every object compiled.

   select object_type
        , object_name
     from user_objects
    where status = 'INVALID'
    order by object_type
        , object_name;

   This should return no rows. adm_oci is the one expected exception on a database without DBMS_CLOUD — see Object storage.

3. Compile the plug-in licensing package and license the plug-ins.

   sqlplus adm/password@db @uc_pip.pkw

   Then license each bundled United Codes plug-in with the API key from your licence e-mail. With outbound internet access from the database:

   set serveroutput on
   begin
     uc_pluginspro.auto_license(
       p_plugin  => 'UNITEDCODES_SEARCHBOX_PRO'
     , p_api_key => 'your-api-key'
     );
   end;
   /

   Without outbound access, call uc_pluginspro.manual_license with the same arguments, take the request key it prints, and call it again with the licence key you get back. The plug-ins that need licensing, and their exact names, are listed in your delivery notes; what is already licensed is visible in uc_pluginspro_license.

   Note

   Unlicensed plug-ins do not break the install — they render a licence warning in the application instead. If a region in ADM shows one, this step was skipped.

4. Import the APEX application.

   In the APEX workspace that owns the ADM schema: App Builder → Import, upload f215.sql, and install it. Keep application ID 215 unless it collides with an existing application; if you change it, also change it in any embedding you set up later.

   The application authenticates with APEX Accounts by default. Point it at whatever authentication scheme your organisation uses before letting real users in.

5. Create the first admin user.

   ADM keeps its own user list, and it starts empty. A database user who has authenticated into the APEX application is still nobody to ADM until they exist in adm_users.

   declare
     l_role_id number;
   begin
     adm_context_api.system_login;
   
     select role_id
       into l_role_id
       from adm_roles
      where role_name = 'ADMIN';
   
     adm_user_api.add_user('USERNAME', l_role_id);
   
     commit;
   end;
   /

   USERNAME must match what the authentication scheme puts into APP_USER — for APEX Accounts that is the account name in upper case. The adm_context_api.system_login call is what gives the anonymous SQL*Plus session the privileges to create a user; nothing administrative works without a context. See The security model.

6. Log in.

   Run the application, sign in as the user you just created, and you should land in that user’s home folder. The administration section is reachable from the navigation menu.

After installing

Nothing below is required for a working system.

• Review the settings — upload size limits, how long trashed files are kept, and which optional features are on.
• Enable full-text search — content search depends on Oracle Text and on the indexing queue being worked by the daily job.
• Move file content to OCI Object Storage — if you do not want BLOBs in the database.
• Connect the office editing services — APEX Office Edit and APEX Office Print are separate services with their own URLs and keys.
• Check the scheduled jobs are running — trash cleanup, retention deletion and content indexing all depend on them.

AI Pack

The AI Pack is optional, licensed separately, and installed on top of a working base installation. It has its own prerequisites — the uc_ai library, a vector database and an embedding provider.

→ AI Pack installation

Upgrading

Applying a new ADM release is a different procedure from a first install.

→ Upgrading