adm_context_api

This document contains the API documentation for the adm_context_api package.

Functions and Procedures

clear_context

Clears the ADM context: username, role and access source.

The context is session scoped, and an ORDS or APEX session is drawn from a pool - the previous request’s user is still set on the connection until something overwrites it. Any entry point that establishes its own identity has to clear first, so that a failure to establish one leaves no identity behind rather than inheriting the last one. Without this, an entry point whose session attach fails silently runs as whoever used the connection before, which may well have been an administrator.

Signature:

procedure clear_context;

---

restore_context

Puts a previously captured context back, or clears it when there was none.

For an entry point that has to elevate itself for the duration of its work, such as adm_job_automations_api.daily_job, and then owes the session its original identity back. Without it the caller keeps the elevated role for the rest of their session, and every audit row after that is attributed to the wrong user.

Signature:

procedure restore_context (
  p_username in varchar2,
  p_role in varchar2,
  p_access_source in varchar2 default null
);

Parameters:

Name	Direction	Type	Description
p_username	in	varchar2	The username to put back; null clears the context
p_role	in	varchar2	The role to put back; null clears the context
p_access_source	in	varchar2 default null	The access source to put back; defaults to DB when null

---

establish_from_session

Turns the CURRENT APEX session’s state into an ADM context.

Reading a session and deciding which identity it has happens only here, so that the knowledge lives in git rather than in a text field in the application definition. The application’s Initialization PL/SQL Code should be exactly:

begin adm_context_api.establish_from_session; end;

It also has to be called by every entry point that runs apex_session.attach, because ATTACH DOES NOT RUN THE INITIALIZATION CODE. To see it: establish an identity, clear it, attach the session you are already attached to, and the context comes back empty. A callback that clears without re-establishing destroys the only authority an embed session has.

The discriminator is AI_USER_ROLE, not the page id. An authenticated user always has one (it is an AFTER_LOGIN computation), so a stale AI_EMBED_TOKEN - an APPLICATION item that outlives the page that set it - cannot capture their session. A public embed session never has one, on any page, including inside an attached callback. Keying on APP_PAGE_ID instead does not work: the embed’s own document viewer runs on page 10, so the branch misses the case it exists for.

Signature:

procedure establish_from_session;

---

establish_for_callback

The single entry point for a callback that arrives OUTSIDE an APEX page request.

Plug-in callbacks and ORDS handlers - the PDF viewer, the Office editor’s external server, the e-mail viewer - are handed an app/page/session and have to turn that into an ADM identity themselves, because the application’s Initialization PL/SQL Code has not run for them. It runs three steps, in this order:

1. clear_context - ADM_CONTEXT is scoped to the DATABASE session and a pooled connection carries the previous request’s identity. Clearing first means a failed attach leaves the caller as nobody rather than as whoever used the connection before, which may well have been an administrator. (The application’s Cleanup PL/SQL Code also calls clear_context, but an ORDS request that never ran the cleanup code can still hand this connection over dirty.)
2. attach - joins the APEX session so v() and session state work.
3. establish_from_session - because ATTACH DOES NOT RUN THE INITIALIZATION CODE.

Step 3 is the one most often left out, and without it a callback runs as whoever last used the connection. Call this helper once per entry point rather than repeating the three steps.

Does NOT swallow an attach failure: a callback that cannot establish who it is must not proceed. It has already cleared, so it fails as nobody.

Signature:

procedure establish_for_callback (
  p_app_id in number,
  p_page_id in number,
  p_session_id in number
);

Parameters:

Name	Direction	Type	Description
p_app_id	in	number	The application the callback names
p_page_id	in	number	The page the callback names
p_session_id	in	number	The APEX session to join

---

system_login

Establishes a system-level session context The system user has full administrative privileges Run this procedure before any scripts that perform administrative operations

Signature:

procedure system_login (
  p_debug_level in apex_debug.t_log_level default apex_debug.c_log_level_warn
);

Parameters:

Name	Direction	Type	Description
p_debug_level	in	apex_debug.t_log_level default apex_debug.c_log_level_warn	The debug level to use for logging (increase to c_log_level_info or c_log_level_app_trace)

---

system_user_login

Establishes a user session context for system operations Use this to run scripts as a specific user and his permissions

Signature:

procedure system_user_login (
  p_username in varchar2
);

Parameters:

Name	Direction	Type	Description
p_username	in	varchar2	The username of the user to log in as (has to exist in the database)

---