One of the first things you learn when building a useful AI agent is that the hard part is not calling the model. The harder part is deciding what the model should be allowed to see.

I recently ran into this while building an agent to manage Questions, Risks, and Issues (QRIs) in an Oracle APEX project management application. The agent can search existing QRIs, find people related to the project, create new QRIs, update existing ones, and help users navigate the project content.

That sounds straightforward until you remember that a project can contain a lot of data. Users naturally ask broad questions like:

• "Show me all open issues."

• "What are the risks for this project?"

• "Find anything related to payment terms."

Those are reasonable requests. However, if the agent responds by dumping every matching row into the prompt, the UI, or the conversation history, the experience quickly deteriorates.

In this post, I will walk through some of the context management lessons from building this agent, how Retrieval-Augmented Generation (RAG) helped limit the result set, and a few practical patterns I would recommend for anyone building agents inside APEX or database-backed applications.

More Context Is Not Always Better

A common early instinct with AI agents is to give the model as much context as possible and let it figure it out. If the model has more data, surely it can give a better answer.

For an application agent, context has a cost:

• it consumes tokens

• it slows down responses

• it gives the model more opportunities to focus on the wrong thing

• it makes debugging harder

• it increases the chance of exposing internal identifiers or unrelated business data

• it can overwhelm the user when the response mirrors the size of the input

In my QRI agent, I had two context problems.

First, the model needed sufficient information to answer questions and perform actions safely. If a user asked to update a QRI, the agent needed to resolve which QRI they meant, preserve the correct workflow status, and avoid using IDs supplied directly by the user.

Second, users often wanted to "see more" than was useful. A user may request all matching data, but that does not mean the agent should become an export feature. The agent's goal is to help the user act, not to replace every report in the application.

Start With Runtime Context, Not Database Dumps

The agent prompt includes a small runtime context block with values such as:

• logged-in user display name

• logged-in user person ID

• active project ID

• current date, time, and time zone

This is the kind of context that should always be explicit and controlled. The agent should not infer that the project is active from the user's message. It should not trust a project ID typed into the chat. It should not accept person IDs from the user.

In the prompt, I made the runtime context authoritative:

Always pass the active project ID from the runtime context. Never use a user-supplied project ID.

That may sound simple, but it is an important boundary. The model can be flexible with language, but the application must be strict with authority.

That said, in APEX applications, the session already knows who the user is and which page or business object they are working with. The agent tools should always use that server-side context. It should not let the chat box become a backdoor for switching tenants, projects, users, or source records.

In APEX terms, the model should not become the authority for session state. APEX session state should supply the active project context. Page items, authorization schemes, application context, and PL/SQL APIs should still define what the user can see and change.

Authorization schemes should guard the target pages and actions. PL/SQL APIs should validate access independently of the model. Opaque links such as qri:// can be resolved by the application into safe APEX URLs using APEX_PAGE.GET_URL. Debug logs should go into an application-specific AI interaction table, not just transient APEX debug output.

Use Tools as Context Gates

The QRI agent does not receive all project data up front. Instead, it receives tools that expose narrowly scoped slices of data:

• search subsections

• list project team

• search QRIs

• get project details

• create QRI

• update QRI

This is one of the most useful mental models for agent design: tools are not only capabilities but also context gates.

A tool defines what the agent can ask for, which filters it must provide, how many rows it can receive, and which fields are returned. That is much safer than letting the model query arbitrary SQL or injecting large JSON payloads into every conversation turn.

For example, the QRI search tool supports structured filters such as type, status grouping, owner, assignee, priority, section, subsection, and semantic search text. The prompt tells the agent to use the narrowest filters available before retrieval.

That instruction matters because users do not always phrase requests as filters, but the agent can often infer them:

• "open issues" means type_code = ISSUE and status_code = OPEN

• "high priority risks" means type_code = RISK and priority_code = HIGH

• "assigned to me" means the assignee should come from the runtime context

This keeps the prompt smaller and the answer more relevant.

RAG as a Limiting Mechanism

The most useful change was using RAG to limit QRI search results.

For semantic searches, the agent does not retrieve and return every QRI. It generates an embedding of the user's search text and compares it against vector chunks representing questions, risks, and issues in the active project. It then selects the closest candidates, applies a distance threshold, and passes only matching QRI IDs into the main relational query.

In the package, this is controlled with constants like:

gc_qri_vector_candidate_max CONSTANT PLS_INTEGER := 50;
gc_qri_vector_max_distance  CONSTANT NUMBER      := 0.55;   -- Cosine
gc_qri_search_result_max    CONSTANT PLS_INTEGER := 125;
gc_qri_content_max_chars    CONSTANT PLS_INTEGER := 300;

The exact numbers are application-specific, but the pattern is the important part.

The vector search is not the final answer. It is a narrowing step. Once the candidate QRI IDs are identified, the normal relational query still applies the project ID, QRI type, status, owner, assignee, priority, and section filters.

That combination is powerful:

• vector search handles fuzzy user language

• SQL filters enforce business rules

• row limits prevent oversized responses

• field truncation keeps each result compact

• the final ordering is predictable

This is where RAG is easy to misunderstand. It is not just a way to "make the AI smarter." In business applications, RAG is also a way to avoid giving the AI too much.

Return Counts, Not Just Rows

The QRI search result includes values like:

• total_count

• returned_count

• max_allowed

• has_more_matches

The prompt then asks the agent to state how many matches were made overall and how many were returned. If more matches exist, the agent should show the returned records and suggest narrowing the filters.

This avoids a poor user experience in which the agent silently drops results. It also avoids the opposite problem, where the agent tries to be helpful by offering pagination inside the chat.

For this agent, I explicitly told it not to paginate results or offer the next range. That was intentional. If a user needs to review a large result set, the application should provide a report. The agent should help narrow and act.

There is a difference between "I found 125 of 600 matching records; narrow by section, priority, or status" and "Here are the first 125, would you like the next 125?" The second version turns the agent into a slow report viewer.

Truncate Content Before It Reaches the Model

Another practical choice was truncating QRI content and responses before returning them to the model. In the tool logic, QRI content is capped to a small number of characters using DBMS_LOB.SUBSTR after stripping HTML.

This is not only about token savings. It also changes the agent's behavior.

When the model receives short result summaries, it is more likely to summarize, compare, and guide the user. When it receives full long-form content for many records, it is more likely to drown in details or repeat them back.

For search results, the agent usually needs sufficient information to identify the item and determine its relevance. It does not need every character of every answer.

If the user truly needs the full record, the application can provide a link. In this agent, QRI results include an opaque qri:// link that the UI converts into an APEX page URL using APEX_PAGE.GET_URL. The model can display the link, but it is instructed not to expose raw database IDs.

That gives users a way to drill down without sending the full payload to the chat.

Separate Model Context From UI Context

One design detail I liked in this implementation was the separation of what is stored, what is sent back to the model, and what is shown in the UI.

Tool results are stored in a log table, but the visible conversation only shows a reduced preview, such as "Tool result captured." The next model turn gets the structured llm_context, not necessarily the entire raw display payload.

The UI response also undergoes redaction to remove business IDs, including project, section, subsection, person, QRI, and client IDs.

That may seem defensive, but it is worth doing. Models are very good at repeating what they see. If internal IDs appear in tool results, prompts, or hidden messages, they will eventually make it into a user-facing response unless you actively prevent it.

A better pattern is:

• use internal IDs inside tool calls

• return user-facing references in responses

• expose links as opaque application links

• redact accidental ID leakage before rendering

• validate all IDs again in PL/SQL before writes

Redaction is useful, but it should be treated as a fallback. The better design is to avoid putting raw IDs into model-visible or user-visible text unless the model truly needs them.

Put Write Operations Behind Confirmation

Context management is not only about reads. Writes need even stricter control.

For create and update tools, the agent queues the requested action and returns a confirmation request to the UI. The write is only executed after the user confirms. The tools also prevent mixing create and update requests in the same batch.

This creates a clean boundary:

1. The model interprets the request.

2. The application prepares a pending action.

3. The user confirms.

4. PL/SQL executes the write after validating access, status, people, source location, and IDs.

That pattern reduces the risk of the model acting on ambiguous context. It also gives the user a compact preview of what will change without dumping the entire record set into the conversation.

Keep the Prompt Opinionated

The agent prompt is fairly detailed. It defines authority, tool rules, retrieval behavior, status mappings, people resolution, section targeting, QRI references, write safety, and response style.

This is necessary because agent behavior is partly application behavior. If you leave too much open-ended, the model will choose differently from one turn to the next.

A few prompt rules that proved useful:

• use runtime context as authoritative

• never trust user-supplied IDs

• ask one concise clarification when required fields are missing

• do not partially write a batch

• preserve tool result ordering

• state returned counts

• do not expose raw IDs

• use the narrowest retrieval filters

• do not invent statuses, people, counts, or document facts

These are not personality instructions. They are application rules.

Other Context Management Practices

First, treat conversation history as a liability after a certain point. Keep enough recent history to maintain continuity, but do not blindly send the entire conversation forever. Older tool results can be summarized, referenced, or re-fetched when needed.

Second, design tools around user intent, not tables. A project_qri_search tool is easier for an agent to use safely than a generic run_sql tool because it encodes the business boundary.

Third, return structured JSON to the model. The model can work with prose, but structured fields reduce ambiguity and make the prompt rules easier to enforce.

Fourth, use separate limits for different surfaces. A report may show 1,000 rows. A tool may return 125 compact rows. A confirmation message may preview only 8 items. Those are different jobs.

Fifth, log enough to debug the agent loop without storing more sensitive payload than necessary. In this package, each major step logs elapsed time: building chat messages, preparing prompt context, calling the model, parsing tool calls, and executing tools. When agents behave strangely, these timings and payload boundaries are extremely useful.

Finally, remember that security still belongs in the database and application layer. The model can be instructed to behave, but PL/SQL should still assert project access, validate people, check statuses, and reject invalid source locations.

Conclusion

Building this agent reminded me that context management is one of the core design skills for practical AI applications.

The goal is not to give the model everything. The goal is to give it the smallest useful slice of information, at the right time, through a tool that enforces the same business rules your application already depends on.

RAG helped because it limited broad semantic searches to relevant candidates before the relational filters and row limits were applied. But RAG was only part of the answer. The full solution also needed runtime authority, structured tools, truncation, count reporting, ID redaction, confirmation gates, and server-side validation.

That may sound like a lot of plumbing, but this is the difference between a demo agent and an application agent. A demo can be impressive with a large prompt and a few lucky examples. A real agent needs boundaries.

If you have spent any time reviewing traditional APEX export SQL, you know the problem. The application is there, but it is buried inside hundreds of calls to internal APIs. You can version it, search it, and deploy it, but reading it fluently is hard work.

To be fair, this is not the first time APEX has given us something better than one huge SQL export. Older versions of APEX could export an application using the Split into Multiple Files option, and APEX has also had a human-readable YAML export format. Those were useful, especially for review and source control, but the YAML format was read-only, and the split SQL export was fundamentally SQL export syntax.

APEXlang makes that structure easier to work with. It mirrors the APEX Builder mental model in a source format that is intended to be read as APEX metadata: applications contain pages, pages contain regions and components, shared components live together, and SQL, PL/SQL, JavaScript, CSS, and HTML still appear where you would expect them.

In this post, I will walk through the anatomy of an APEXlang .apx file and show how to build a mental model of an app quickly.

The Folder Structure

An APEXlang export is not one giant SQL file. It is exported as a zip file that expands into a folder structure.

For the customers sample app, the tree looks like this:

customers/
|-- application.apx
|-- page-groups.apx
|-- pages/
|   `-- p00001-dashboard.apx
|   `-- p00050-customer.apx
|-- shared-components/
|   |-- app-computations.apx
|   |-- app-items.apx
|   |-- app-processes.apx
|   |-- authentications.apx
|   |-- authorizations.apx
|   |-- breadcrumbs.apx
|   |-- build-options.apx
|   |-- classic-navigation-bar-entries.apx
|   |-- component-settings.apx
|   |-- legacy-data-load-definitions.apx
|   |-- lists.apx
|   |-- lovs.apx
|   |-- messages.apx
|   |-- plugins/region/APEXLANG-14855697926908483213/{custom-attributes.apx,plugin.apx}
|   |-- shortcuts.apx
|   |-- static-files.apx
|   |-- report-layouts/report-layouts.apx
|   |-- report-layouts/CUSTOMER-REPORT.rtf
|   |-- static-files/icons/app-icon-32.png
|   `-- themes/universal-theme/{template-option-groups.apx,theme.apx}
|-- supporting-objects/
|   |-- deinstall-script.sql
|   |-- install-scripts.apx
|   |-- install-scripts/activities.sql
|   |-- supporting-objects.apx
|   |-- substitutions.apx
|   |-- upgrade-scripts.apx
|   `-- upgrade-scripts/upgrade-eba-cust-spec-and-body.sql
|-- deployments/default.json
|-- .apex/apexlang.json
`-- workspace-components/app-groups/APEX-184853421316436653.apx

application.apx is the application-level definition. This is where you find the application name, version, authentication, authorization, navigation, theme, globalization, security settings, substitutions, JavaScript, CSS, and other global configuration.

pages contains one file per page. The filenames are practical: p00001-home.apx, p00003-event-details-p3-event-name.apx, p00050-customer.apx, and so on. You can usually tell the page number and purpose before opening the file.

shared-components contains the things you would expect from APEX Builder: LOVs, lists, breadcrumbs, authentications, authorizations, app items, app processes, themes, plugins, messages, build options, static files, and report layouts.

supporting-objects contains installation, upgrade, substitution, and deinstallation metadata. The actual SQL scripts can live under folders such as supporting-objects/install-scripts and supporting-objects/upgrade-scripts.

deployments contains deployment configuration. In the examples, default.json maps the app to an application ID.

.apex contains APEXlang metadata. In the examples, .apex/apexlang.json identifies the APEXlang metadata version.

This structure matters because it lets you navigate an app the same way you think about an app. That idea existed before APEXlang, but APEXlang makes the files easier to read. You can edit, validate, and import them back into APEX.

What Lives in application.apx

Open application.apx first.

It starts with an app block:

app TEAM-CALENDAR (
    name: Team Calendar
    version: 24.2.1
    authentication {
        publicUser: APEX_PUBLIC_USER
        authenticationScheme: @administration-rights
    }
    navigation {
        homeUrl: f?p=&APP_ID.:1:&SESSION.
    }
)

That reads much closer to a configuration file than an export script. You can scan it and answer basic questions quickly:

• What is this application called?

• What authentication scheme does it use?

• Is authorization configured globally?

• What is the home page?

• Which theme is current?

• Are there global substitutions?

• Is custom CSS or JavaScript included?

You will also see the same APEX ideas you already know: session management, security, globalization, navigation, Progressive Web App settings, and substitutions.

Read application.apx like the App Definition screen in APEX Builder. Do not try to understand every reference yet. Get the global shape first.

How Pages Are Modeled

Page files are where APEXlang becomes especially useful.

A page starts with a page block:

page 1 (
    name: Home
    alias: HOME
    title: &APPLICATION_TITLE. - Home
    appearance {
        pageTemplate: @/standard
    }
)

After that, the file is organized around page components. In the examples, pages contain:

• region

• item

• button

• dynamicAction

• validation

• computation

• process

• branch

Again, this follows the APEX Builder mental model. To understand a page, scan the top-level component blocks first.

Regions often contain their own nested configuration. A report region may include a source block, layout settings, template choices, columns, actions, conditions, and attributes.

region APEX$1553489748373581675 (
    name: Events Calendar
    type: calendar
    source {
        location: localDatabase
        type: sqlQuery
        sqlQuery:
            ```sql
            select e.event_id
            ,      e.event_name
            from   eba_ca_events e
            ```
    }
)

That is the key pattern: the declarative APEX component is modeled structurally, and the executable code remains embedded in a fenced block.

For form or dialog pages, I would scan in this order:

1. Page name, alias, template, and security.

2. Regions, especially the main form region.

3. Items and their source/default/session state behavior.

4. Buttons and button positions.

5. Processes and branches.

6. Validations and dynamic actions.

You can usually tell whether a page is display-only, a report, a modal form, or a complex transactional page in a couple of minutes.

Shared Components Become Readable

Shared components are split into focused files. That is one of the biggest readability wins.

For example, shared-components/lovs.apx contains lov blocks. A static LOV contains nested entry blocks. A SQL-based LOV contains a source block with the SQL query.

lov APEX$14836072312031628364 (
    name: USERNAME_FORMAT
    source {
        location: staticValues
    }

    entry APEX$14836072618328628365 (
        sequence: 1
        display: Email Address
        return: EMAIL
    )
)

Lists work the same way. shared-components/lists.apx contains list blocks, and each list contains entry blocks with labels, icons, links, current-page logic, and parent-child relationships.

App processes live in shared-components/app-processes.apx. Authentication schemes live in shared-components/authentications.apx. Plugins live under shared-components/plugins, separated by plugin type and id. Themes live under shared-components/themes.

This is much easier to review than a traditional SQL export because the file boundaries match the APEX Builder navigation, and the file contents are not wrapped in API calls.

Understanding References

APEXlang uses references heavily, and learning the reference style is what makes the files click.

You will see @... references in exported files. These are references to APEX components by generated identifier. For example, an application may point to an authentication scheme or navigation list using an @... value.

You will also see more readable references based on static IDs and names:

authentication {
    scheme: @oracle-apex-accounts
}
userInterface {
    currentTheme: @universal-theme
}
navigationMenu {
    list: @navigation-menu
}

That matters because APEX 26.1 adds static IDs across APEX components, and APEXlang uses those IDs to make references more stable and readable.

You will also see @/... references, especially for templates:

pageTemplate: @/standard
listTemplate: @/side-navigation-menu
buttonTemplate: @/text-with-icon

These are easier to read because the component is referenced by a friendly path-like name.

Page item references still look like APEX page item references. SQL and PL/SQL blocks use bind variables such as :P50_ID, :APP_ID, and :APP_USER. URL targets still use familiar APEX substitution syntax, such as f?p=&APP_ID.:1:&SESSION..

Named component references also appear naturally in places such as authorization checks, build option logic, template references, and links.

The practical rule is simple: if you see @..., you are looking at a declarative component reference. If you see :Pxx_ITEM, you are looking at the session state. If you see &APP_ID. or #COLUMN#, you are in familiar APEX substitution territory.

The Hybrid Reality

APEXlang structures the declarative layer, but it does not remove code from APEX.

SQL queries still live in report sources, LOVs, conditions, and supporting object scripts. PL/SQL still lives in processes, validations, conditions, computations, and application processes. JavaScript can still appear in page JavaScript settings, dynamic actions, and static files. CSS can still be inline on a page or stored as a static file. HTML still appears in help text, templates, report HTML expressions, and PL/SQL output.

APEXlang is not pretending APEX is something it is not. It provides metadata with a readable structure while preserving the hybrid nature of real APEX applications. Just as important, that structure supports real round-tripping: you can search and replace across files, generate apps with AI, validate the result, and import the application back into APEX.

How the Oracle APEXlang Skill Fits In

The APEXlang files are only half the story. Oracle also released an APEXlang AI skill package to help agents work with this format safely.

That package is not just a pile of examples. It includes routing metadata, component catalogs, templates, runtime helpers, SQLcl adapters, and validation tools. The skill provides an agent with a workflow for finding the app, loading the correct local context, choosing the appropriate templates, checking component properties against compiler-backed truth, validating the generated APEXlang, and importing only when explicitly approved.

That safety model matters. APEXlang is writable, but it is still application metadata. A good agent workflow should not guess table names, invent columns, silently pick a workspace, or import generated code because the prompt sounded confident. The skill expects authoritative context, such as table metadata, a data model, an API contract, or a live database connection, before it generates schema-dependent APEXlang.

For live validation or import, the practical requirements are also explicit: APEX 26.1 with APEXlang support, SQLcl 26.1.2 or newer, Java 17 or 21, a saved SQLcl connection name, and the corresponding APEX workspace name. The default workflow is check-only first. Import is a separate step that should happen only after the APEXlang check passes and the developer approves it.

For APEX 26.1, APEXlang import is an application import. Single-page APEXlang import is not supported in this release. That does not reduce the value of the format, but it does affect how you plan review, validation, and deployment workflows.

Conclusion

The most useful way to think about APEXlang is this:

APEXlang is a readable and writeable source format for an Oracle APEX application.

It builds on ideas APEX has already explored with split exports and readable YAML, but gives developers a practical source format for navigating application metadata without decoding traditional export SQL.

It is still APEX. Your pages, shared components, SQL, PL/SQL, JavaScript, CSS, and HTML are all still there. They are just arranged in a format that humans can read, search, diff, validate, and learn from before importing the application back into APEX.

Once you understand the folder structure, page model, shared component files, and reference syntax, .apx files become much less intimidating. You can open an unfamiliar application and start building a useful mental model quickly, which is exactly what a source format should help you do.

AI-assisted development for Oracle APEX work is moving beyond one-off prompts and into something much more structured.

We now have reusable skills, repo-level instruction files, agent configuration, project standards, prompt libraries, and more detailed tooling around code generation and review. That is useful. It also creates a new problem: your AI context can get messy very quickly.

In this post, I want to look at what I mean by AI hygiene, why it matters for APEX and PL/SQL developers, and where I have already seen it go wrong.

What I Mean by AI Hygiene

When I say AI hygiene, I mean keeping the instruction layer around the model clean, up to date, and free of conflicts.

For Oracle developers, that instruction layer can include:

• Oracle-provided skills: oracle-skills and APEXlang skills (when they are released)

• community-developed skills

• your own PL/SQL or APEX skills

• CLAUDE.md or AGENTS.md

• code that is already in the repo

• repo README files

• MCP tool descriptions

• prompt libraries

That is a lot of context for a model to reconcile. If those sources line up, the results can be very good. If they do not, the model will often produce something that looks plausible, compiles cleanly, and still doesn't do what you want it to.

That is why I think of AI hygiene as code hygiene for the instruction layer.

Reducing unnecessary or conflicting context can lower token usage (and therefore cost) and improve time to first token, especially as tools, skills, and repo guidance accumulate.

Why This Matters More for Oracle Work

Oracle development is unusually context-sensitive.

A decent answer is not just about knowing PL/SQL syntax or APEX component names. It also depends on version compatibility, security patterns, naming conventions, package structure, logging standards, deployment rules, and sometimes very specific local constraints around ORDS, APIs, and the database architecture.

For example, a generic Oracle skill might reasonably recommend things like:

• use packages for reusable business logic

• avoid dynamic SQL where possible

• prefer bind variables

• use clear exception handling

• account for version-specific syntax

None of that is wrong. The problem is that your project may also require:

• all business logic to go through package APIs

• no core logic in APEX page processes

• a specific logging package or wrapper

• compatibility with Oracle Database 19c

• compatibility with a specific APEX version until a future upgrade is complete

At that point, the question is no longer, "Is the model good at Oracle?" The real question is, "Which instruction wins?"

The Problem Is Not Bad Syntax

When people worry about AI-generated code, they often focus on whether it compiles. That is a fair concern, but it is not the one I worry about most. The more dangerous failure mode is plausible wrongness. In other words, code that is technically valid but wrong for your application.

That can look like:

• valid PL/SQL in the wrong package

• valid SQL that ignores tenant isolation

• valid APEX page logic placed in the wrong layer

• valid ORDS handlers with the wrong response structure

• valid exception handling that hides errors

In practice, that kind of output is more dangerous than obvious AI slop because it creates both review overhead and false confidence.

Where I Saw This Happen

One of the clearest examples I have seen was with a PL/SQL-focused skill I was using while developing APEX applications.

The skill itself was helpful. It pushed the model toward better package structure, cleaner SQL, stronger exception handling, and more Oracle-aware output. On its own, that was a net positive.

The issue was that I also had AGENTS.md files sitting in individual repositories, which had grown organically over time. Some predated AI skills entirely. Some reflected older project conventions. Some made sense for one app but not another. Some were simply too broad.

So I had two different instruction sources operating at once:

• the skill was trying to enforce general Oracle and PL/SQL best practices

• the repo-level AGENTS.md files were trying to enforce local architecture and workflow rules

That sounds fine until those two sources disagree.

I would get output that mixed conventions:

• package structure from the skill

• naming from the repo file

• exception handling from an old example

• architecture decisions from whichever instruction happened to dominate in that run

Nothing about that output was obviously broken. That was the problem. It was technically reasonable code, but it still required cleanup because the instruction environment was dirty. That kind of issue becomes more common as we add more reusable AI context, not less.

Why APEX Makes This Even More Interesting

This becomes even more relevant for APEX developers when APEX 26.1 (and APEXlang) is released, enabling us to use AI to generate APEX applications.

Once your application structure, component metadata, and declarative configuration are more accessible to AI-driven workflows, the upside is obvious. You can imagine better review tooling, better automation, better generation, and better assistance around large APEX applications.

However, that also increases the number of instruction surfaces that can conflict.

For example, you may end up balancing:

• a general Oracle skill

• an APEX-specific skill

• project architecture rules

• UI conventions

• security constraints

• task-specific prompts

That is exactly why AI hygiene matters. The more an AI can touch, the more important it becomes to control the rules that guide those changes.

A Better Mental Model: Instruction Layers

The cleanest way I have found to think about this is to separate instruction authority from repository reality.

Some things are explicit instructions. Some are evidence of how the application actually works today. Those are not the same, and treating them as the same is where much of the confusion starts.

Instruction Authority

    Vendor or ecosystem skills
                |
                v
      Internal reusable skills
       and community skills
                |
                v
             AGENTS.md
                |
                v
            Task prompt

Reality check

    Existing repository code
    (current implementation)

1. Vendor or Ecosystem Skills

These provide broad technology competence.

This is where I would want Oracle-focused guidance, SQL and PL/SQL best practices, documentation-backed patterns, and general platform knowledge to live.

These skills should make the model better at Oracle. They should not try to encode every project-specific convention you have.

This includes Oracle-provided skills when they exist, but I would not automatically assume vendor-provided skills are more authoritative than a well-maintained internal skill. The real distinction is between broad platform knowledge and local rules.

2. Internal Reusable Skills and Community Skills

This is where your own reusable skills and outside community skills usually sit.

For example, this layer may include:

• internal APEX architecture patterns

• shared package templates

• organization-specific API conventions

• approved approaches for ORDS, JSON, or security wrappers

• coding, logging, security, or naming standards reused across repositories

This is often the most important layer in practice because it bridges the gap between general Oracle competence and the needs of a real delivery team.

3. Project or Repository Instructions

This is where CLAUDE.md or AGENTS.md sits. The job of this layer is to explain how this specific application works:

• project context

• project naming conventions

• technology versions (APEX 26.1, Oracle DB 19c, etc.)

• project-specific architecture rules

• testing and deployment expectations

• approved exceptions to broader standards

This file should not become a junk drawer for every Oracle best practice you have ever liked.

Ideally, your AGENTS.md should be less than a dozen bullet points. The bulk of the instructions should come from skills that can be reused for all of your projects.

4. Existing Repository Code

This is not just another instruction file. It is an implementation reality.

The codebase shows:

• what patterns are actually in use

• what package boundaries already exist

• what naming is really present

• what versions and compatibility assumptions the project appears to follow

• where the written instructions may already be stale

If AGENTS.md says one thing and the repository consistently does another, that is not a simple question of precedence. It is a hygiene problem that needs to be resolved deliberately.

Vendor skills should teach the model the platform. Internal reusable skills should teach your conventions. AGENTS.md should teach the project. The codebase should teach reality.

5. Task Prompt

This is the immediate ask:

• review this package

• generate this API

• refactor this page process

• propose an APEX app structure

The prompt should clearly describe the job, but it should not be forced to restate everything already in the higher layers.

The rule I would use is simple:

Put instructions at the lowest stable layer where they belong.

And when written instructions conflict with the existing codebase, stop pretending the hierarchy is clean. That is the moment to decide whether the code needs refactoring or the instructions need updating.

Common Sources of AI Context Rot

Once you start looking for it, instruction drift shows up everywhere.

The usual problems are:

• stale AGENTS.md files that describe an older architecture

• older examples that teach the model outdated patterns

• duplicated rules spread across skills, READMEs, and agent files

• version assumptions that no longer match production reality

• copied prompt fragments nobody wants to delete

• unclear authority between skill guidance and repo guidance

Typically, the worst cases are not dramatic. They are subtle. You just start seeing output that feels slightly off. The model is not exactly wrong, but it is clearly pulling from incompatible instructions.

A Checklist for Better AI Hygiene

If you want to improve this without turning it into a process nightmare, I would start with a short checklist.

Inventory your instruction sources

List every place your AI tooling can pull guidance from:

• skills

• AGENTS.md

• README files

• coding standards

• templates

• prompt libraries

• examples

• existing code

Decide what wins

For each category, define the default source of truth and what counts as the reality check.

For example:

• PL/SQL style usually comes from internal reusable skills or shared templates

• generic Oracle best practice comes from a vendor, ecosystem, or internal skill

• cross-project architecture conventions come from your own reusable skills

• project-specific knowledge, software versions, and local constraints come from AGENTS.md

• output formatting comes from the task prompt

If you do not define authority, the model will improvise it for you. If you do not check that authority against the current codebase, you will miss drift.

Search for conflict words

Look for words like:

• always

• never

• must

• avoid

• required

• deprecated

• version

• exception

• security

• logging

Those words tend to reveal hidden conflicts very quickly.

In an APEX repo, a quick example is a project rule that says all business logic must live behind packaged APIs while the prompt or a reusable skill keeps generating logic directly in page processes. Both outputs may be valid. Only one matches the architecture.

Remove duplicate rules

If the same instruction exists in five places, it will eventually drift.

I would rather have:

• a skill that provides broad Oracle guidance

• an internal reusable skill or shared template that defines mandatory patterns

• a repo file that only documents local exceptions and architecture

That is much easier to maintain.

Test your instruction stack

This is the part I think many people will skip, and they should not.

Use a few repeatable prompts such as:

• generate a package for expense approval logic

• review this APEX page process for security issues

• create an ORDS GET handler for employee expenses

• write SQL compatible with Oracle Database 19c

Then check whether the output actually follows your standards.

If the same prompt produces different architectural decisions depending on which repo you run it in, you probably have an AI hygiene problem.

Conclusion

AI-assisted Oracle development is not just about better models and better prompts anymore. It is also about managing the instruction environment around the model.

That means skills, standards, repo rules, examples, and prompts all need to work together rather than compete for control. I have already seen how a useful PL/SQL skill can become less useful when it collides with inconsistent AGENTS.md files spread across repositories. The model was not the weak link there. My instruction layer was.

As Oracle-focused skills become more common and AI-driven workflows become more practical for APEX and PL/SQL teams, I think this only gets more important.

Your instructions are no longer just notes for the model. They are part of your development environment now, and they deserve to be maintained with the same care as code.

AI is changing how we build software. We are moving from a world where developers primarily describe systems in code to one where we increasingly describe intent in natural language. Prompts, instructions, specifications, and structured text are becoming part of the development process itself. In that sense, English is becoming a specification interface for software generation.

But English alone is not enough.

Natural language is flexible, expressive, and easy for humans. It is also messy. It drifts. It is inconsistent. It leaves room for interpretation. That is fine for conversation. It is less fine when you want an AI system to reliably generate an application, a page definition, a requirements document, or a presentation.

That is why Markdown matters.

If English is becoming the language of AI-driven development, Markdown is becoming one of the most practical formats for making that language usable. It gives natural language just enough structure to be repeatable, parsable, lightweight, and machine-readable without turning it back into code.

For APEX developers, this matters more than most people realize. APEX has always been about metadata, declarative development, and reducing friction between business intent and working software. APEXlang appears to push that same idea further. Instead of hand-building every artifact, we will increasingly define applications, pages, workflows, and requirements in structured natural language and let AI turn those definitions into implementation.

That is why Markdown is such a strong fit for the AI era, and especially for where APEX appears to be heading.

Markdown hits the sweet spot

Markdown is powerful because it is simple.

A heading is a heading. A list is a list. A table is a table. A code block is a code block. You can read it as plain text, write it quickly, version it easily, and transform it into other formats without carrying the overhead of a heavyweight document format.

That makes Markdown ideal for AI.

Large language models work best when the input is mostly meaning rather than formatting noise. Markdown preserves structure, but it does not bury the meaning inside layers of layout instructions, visual positioning, embedded objects, theme metadata, and export artifacts. The model sees the content clearly.

This is where Markdown has a big advantage over Word documents, slide decks, and PDFs. Those formats were designed primarily for human consumption and visual rendering. Markdown is much closer to an authoring format for both humans and machines.

For APEX, this is especially interesting because so much of what we build already begins as semi-structured intent: application descriptions, page definitions, data requirements, business rules, acceptance criteria, UX notes, and workflow descriptions.

Traditionally, those things are scattered across Word docs, slides, emails, tickets, and whiteboards. In an AI-driven workflow, that fragmentation becomes a real problem. AI works better when the source material is clean, consistent, and structured.

Markdown gives you that structure without forcing you into a rigid syntax that business users or developers will resist.

Structure

Large language models do not benefit from Markdown just because it removes formatting noise. They also benefit from the predictable hierarchy Markdown provides. Headings define topic boundaries, sections group related ideas, nested lists show parent-child relationships, tables make structured comparisons explicit, and code fences clearly separate executable or literal content from prose. That consistent structure makes the content easier for a model to parse, chunk, and reason over. In practice, Markdown works well because it preserves meaning in a form that is both human-readable and machine-readable.

APEXlang & Blueprints

APEXlang (available in APEX 26.1) will be the new syntax for APEX. At APEX World this year (also mentioned in the APEX statement of direction), we learned a little about another aspect of APEXlang called Blueprints.

Based on what was shown and what Oracle has signaled publicly, Blueprints are a move toward more structured, specification-driven app generation. Blueprints will likely depend on a defined Markdown structure or syntax. The fact that APEX Blueprints can be created in Markdown should mean they are both human and machine-readable.

Getting off to a fast start

Based on the information available, I assume Blueprints will help you accelerate version 1 of your app, and then you can iterate from there. Iteration on top of the initial build would then happen in APEX Builder, VS Code, or APEXlang.

A business analyst writes a Blueprint spec in Markdown. This is converted to a first draft of an APEX app, SQL objects, validations, and test cases. The developer reviews and refines. The Markdown spec remains the source of intent.

Benefits

This approach has several benefits:

• A blueprint-driven approach has the potential to be more deterministic than unconstrained AI generation.

• It could shift more early-stage specification work toward analysts and product owners.

• You can use version control and diffs on Blueprints as you evolve the first version of your app.

A Practical Example: Marp

A tangible example of this approach (which I recently started using) is the Markdown Presentation Ecosystem, or Marp. Marp is an open-source Markdown presentation ecosystem that lets you write slide decks in Markdown and turn them into presentation-ready output. It includes tools, a CLI, and can export decks to HTML, PDF, and PowerPoint. As with APEX Blueprints, you write the content, and the Marp CLI converts it to HTML, PDF, or PPTX.

Building presentations in Markdown allows you to focus completely on the content of your presentation rather than the format.

Using Marp

Using Marp is straightforward. You write a normal Markdown file, and each slide is separated by a horizontal rule (---). That means a deck is just a sequence of Markdown sections. You can then add Marp front matter and directives for things like theme selection, pagination, background images, layout tweaks, and presenter-friendly formatting. The official ecosystem includes the Marp CLI for converting Markdown files from the command line.

Simple Example

---
marp: true
theme: default
paginate: true
---

# My Presentation

A slide written in Markdown.

---

## Second Slide

- Bullet one
- Bullet two
- Bullet three

Generate Output

Once you have your markdown, you can convert it to PDF, HTML, or PPTX from the command line.

# Generate an HTML presentation using a custom CSS style
marp --theme nueva.css AI_Functions_Presentation.md -o AI_Functions_Presentation.html

# Generate a PDF presentation using a custom CSS style
marp --theme nueva.css AI_Functions_Presentation.md -o AI_Functions_Presentation.pdf

# Generate a PPTX presentation using a custom CSS style
marp --theme nueva.css AI_Functions_Presentation.md -o AI_Functions_Presentation.pptx

Markdown Saves on Tokens

The unit of measure of AI is tokens. Tokens are the small chunks of text that an AI model reads and generates, such as words, parts of words, punctuation, or symbols. They are the basic units of input and output, so token count affects cost, speed, and the amount of context the model can handle at once.

The fewer tokens you use, the less your AI costs and the faster it runs.

To test this theory, I used the Codex CLI to build a deck in Markdown and another in PPTX format. I ran both scenarios using the gpt-5.4-mini with high reasoning.

Results / Token Usage

The token savings are significant.

Now, let's see what happens to token usage when we summarize the outputs from the above...

Results / Token Usage

Again, this test showed a dramatic reduction in token usage.

Note: Much of the additional token usage likely comes from the extra processing needed to extract usable structure and text from a binary PPTX workflow.

Markdown for Specifications

A useful Markdown specification does more than describe an idea at a high level. It should define the feature's purpose, business context, data involved, required behavior, constraints, and acceptance criteria. In practice, that means clearly naming entities, inputs, outputs, rules, edge cases, assumptions, and non-functional requirements where they matter. The goal is to remove ambiguity without making the document heavy or unreadable. A good Markdown spec gives both humans and AI a structured source of intent that can be reviewed, versioned, and turned into implementation with less guesswork.

I have written before about providing AI with detailed specifications to improve AI outcomes. These specifications should be written in Markdown to allow the AI to focus on intent rather than formatting.

Markdown for Agents

Markdown is also emerging as a practical format for presenting content to AI agents. Although HTML is well-structured, it is bulky and includes tags and formatting that add noise for agent workflows. Markdown offers a cleaner interchange format when the goal is to expose content rather than presentation.

Cloudflare is at the forefront of this transition. You can read more in their blog post on the subject.

Caution

Markdown is not enough on its own

Markdown is useful because it adds structure without adding much friction. But on its own, it is still just text. If you want reliable AI output, Markdown usually requires conventions.

That may include standard section headings, front matter, templates, naming rules, required fields, examples, and acceptance criteria. Without that extra discipline, two Markdown documents about the same thing can still vary wildly in quality and completeness.

In other words, Markdown is not the full solution. It is the foundation. The real value comes when teams combine Markdown with consistent patterns that make intent easier for both humans and AI to interpret.

Where Markdown breaks down

Markdown works best when the goal is to capture meaning, structure, and intent. It works less well when the output depends heavily on precise visual layout or rich interaction.

For example, Markdown is not a great fit for pixel-perfect UI design, complex diagrams, drag-and-drop experiences, or documents that rely on detailed formatting and review features such as tracked changes. It can describe those things, but it cannot fully replace the tools built for them.

That is the tradeoff. Markdown is an excellent lightweight source format, but not every artifact should remain in Markdown forever. In many cases, it is most valuable at the intent stage, before being transformed into something more specialized.

Conclusion

Markdown matters because it separates intent from presentation. It gives natural language enough structure to be reused, versioned, reviewed, and processed reliably by AI.

That makes it useful well beyond note-taking. It is a strong format for specifications, blueprints, prompts, presentations, and agent-facing content. Not because it is perfect, but because it is simple, structured, and efficient.

For APEX developers, that matters. APEX has always been about turning metadata and intent into working software. As AI and APEXlang push that model further, Markdown looks like a practical way to define what we want before tools generate what we build.

This is not another post about creating an APEX app from a spreadsheet using the Create app Wizard. This post is about using AI to design and accelerate the build of an enterprise APEX system from a spreadsheet.

Background

A client recently asked me to build an APEX system to replace their existing spreadsheet-based expenses system. The goals were clear:

• Reduce the time from expense submission to payment

• Improve the accuracy of taxes calculated for expenses

• Allow management to track expenses

• Reduce errors caused by manually entering AP invoices into Oracle E-Business Suite

• Improve anomaly detection

• Improve user experience

The company’s expense rules were already embedded in the Excel template. The template included formulas for mileage reimbursement, Canadian tax calculations, and finance summaries used to enter AP invoices into Oracle EBS.

An AI First Approach

One of my goals for 2026 is to adopt an AI-first approach. It will not always work, but using it as the default starting point is helping me understand its limitations and get much more out of it.

One word of caution. Just because AI cannot do something well today doesn't mean it won't be able to when the next frontier model is released. It is important that we regularly re-evaluate our perceptions of what AI is capable of.

Architecture

At this stage, it is worth describing the client's APEX environment. They have an on-premises APEX instance running on the Oracle e-Business Suite (EBS) instance. This sits behind a firewall accessible only via VPN. They also have an OCI APEX Service instance running externally-facing APEX apps. The plan was to have expense report entry and approval run in the OCI instance, and then pull approved expense reports into the on-premises EBS instance for review and payment in Accounts Payable by finance.

• OCI owns the approval state of the expense reports

• EBS owns the payment state of the expense reports

• SharePoint owns receipt attachments

Design

Business Rule Extraction

The legacy expense report Excel template's tabs, tables, fields, and formulas essentially contained all the business rules. I started the design phase by asking Codex to analyze the Excel template and draft a Product Requirements Document (PRD) based on it. Codex produced a four-page Markdown PRD covering the business rules, entities, fields, data types, and lists of values.

Verification

I took the PRD and asked Codex to review it against business best practices and current Canadian tax rules. It augmented the design with rules not already in their spreadsheet. For example, Codex suggested additional mileage-rule considerations that were not explicit in the spreadsheet, which we then validated against current Canadian guidance and the client’s reimbursement policy.

User Interface

I then asked Codex to create graphical wireframes of the APEX pages needed for the solution. I attached several screenshots from existing APEX apps, so it could match the corporate look and feel. Codex created the wireframes using real data from an old expense report Excel. I incorporated screenshots into the design document.

Business Review

I then reviewed the PRD with business users to get their feedback. Being able to present the business rules in a clearly laid out document (instead of embedded in Excel formulas), and being able to show them what the new app was going to look like was significant. We made some minor updates to the design based on feedback from this review.

At this stage, we had an approved design document and a clear path forward after only 10 hours of effort.

Build

Using Codex, I attached the approved design document and provided an extensive prompt detailing what I wanted it to do. I split this into two prompts, one for the OCI expense entry side of the app (running on OCI) and a separate one for the on-premises side of the app. Each prompt requested:

• A comprehensive data model.

• Secure views and views that abstract table-join complexity from APEX.

• PL/SQL utility packages with APIs to manage email generation, REST integrations, workflow functions, and managing attachments in SharePoint.

• ORDS APIs to allow the On-Premises EBS environment to fetch approved expenses for payment, and to post back to let employees know when their expenses have been paid.

Along with the prompt, I included:

• Sample tables from previous apps to teach the model the table creation standards.

• PL/SQL code from previous apps that had APEX workflow approvals and that used a SharePoint attachments common package that we use.

• An AGENTS.md file to provide product versions, coding standards, formatting standards, etc.

The outcome was:

• A roughly 90% complete data model with foreign keys, constraints, appropriate data types (and sizes), and comments.

• Scripts to load the current tax and mileage rates from the template Excel into the new tables.

• Abstraction of Canadian Provinces and Territories into Jurisdictions applicable to mileage and tax rates, which is something I would not have thought of.

• Cloud and On-Premises PL/SQL packages with the helper procedures and functions that I requested.

• A SQL script to create an ORDS OAuth2 Credential, ORDS module, privilege, templates and handlers.

• Twenty unit test scripts to test both sides of the app.

There were a few issues which were resolved with another hour or so of follow-up prompts and clarifications.

APEX

All that was left was to build the APEX app. This part was less fun because, at the time of writing in March 2026, APEXlang was not yet available. Frankly it took longer to build the APEX app than all of the other artifacts created up to this point.

Overall, I would estimate that what would normally have been an 80-hour project was reduced to about 40 developer hours with the help of AI. We will have to see how much lower this can go when APEXlang comes along.

Keys to Success

The following points were key to the success of this project:

• 90% of the business rules were explicitly baked into the Expense Report Excel. This made it easy for the AI to extract the rules and for us to verify it had done it accurately.

• Presenting the business with a PRD within a few days of starting the project (with realistic wireframes) inspired confidence that we are heading down the right path with minimal investment of time.

• Splitting the build phase between on-premises and OCI allowed the model to focus on each build separately and reduced the risk of confusion between the different database versions, APEX versions, and EBS-specific coding standards.

• Models respond really well to examples. Pointing AI to a package and saying "create a procedure to do X that follows the same pattern as procedure Y from another package" works very well.

• Being specific about the output you expect is also key. For example, you need to specifically request test scripts, and request that they include edge cases as well as happy path tests. Combine this with SQLcl and its MCP server, and you can prompt the AI to run the test suite after every change.

Conclusion

AI did not build this system on its own, but it removed a large amount of the slow, repetitive work at the start of the project. The spreadsheet already contained most of the business rules. AI helped extract those rules, turn them into a usable design, and generate much of the database and PL/SQL foundation.

The real value was speed and clarity. We were able to review a proper design with the business early, make corrections before build started, and cut the overall development effort significantly. The parts that still needed the most hands-on work were the APEX application itself, validation of the generated output, and the final handling of edge cases.

For this type of project, AI worked best as a force multiplier, not as a replacement for experience. It was useful because the source material was structured, the prompts were specific, and every output was reviewed before being used.

I have been experimenting with using AI Skills as a thin layer on top of MCP-backed tools, and I think this pattern is more useful than it first appears.

At a technical level, MCP gives the model standardized access to external tools and context. That is valuable, but raw tool access is not always enough. A model may know that a tool exists, but still needs guidance on when to use it, how to use it, what the tool is for, and what “good usage” looks like in the context of a specific prompt.

That is where I am finding Skills useful.

Rather than thinking of a Skill as replacing an MCP server, I think of it as a focused instructional layer on top of one or more MCP tools. The Skill captures intent, usage conventions, and domain-specific behavior. In practice, that makes tool use more reliable and reduces the amount of prompting I need to do each time.

An example with Oracle ORDS

To make this more practical, I built a small STDIO MCP server that exposes an Oracle ORDS REST web service on a table called JD_SB_ENTRIES. This table stores records in a second brain app. By “second brain,” I mean the usual personal knowledge tasks: capturing notes, storing ideas, tracking follow-ups, organizing knowledge, and retrieving things later in a structured way.

The ORDS side is straightforward. I registered a template for the table with handlers for GET, POST, PUT, and DELETE that map to CRUD database operations. I secured the ORDS module that the template was created in using an OAuth 2.0 client.

I built an STDIO MCP Server in Python using the Codex desktop app. STDIO MCP servers run locally on your machine. The MCP server then exposes the REST APIs to the model through a tool interface.

The model can use the MCP tool to create, read, update, and delete rows through ORDS, without needing to know the low-level details of the HTTP call each time.

It works.

But I soon found that getting the MCP server to act on my prompts was erratic (at best). I also have Office 365 linked to my Codex desktop app setup, so the model would often choose Microsoft Planner over my tool. It would also conflict with Office 365 Calendar. It's understandable, really.

A request like "add a task for tomorrow to clean the car" would make sense for MS Outlook just as much as for my second brain.

This confusion from the LLM occurs despite clear instructions in the MCP server services definition on how to use the tool.

oauth:
  token_url: https://example.adb.us-chicago-1.oraclecloudapps.com/ords/demo/oauth/token
  scopes: ""

services:

id: jd_sb_entries
name: JD Second Brain Tasks, Notes, and Reminders
base_url: https://example.adb.us-chicago-1.oraclecloudapps.com/ords/demo/mcp/
description: "Manage second-brain entries from natural user requests. Use this service when the user wants to add, create, save, list, review, update, or delete notes, tasks, ideas, knowledge entries, or reminder-style entries with a due date. Create new entries at jd_sb_entries and update or delete existing entries at jd_sb_entries/{entry_id}. This stores reminders as second-brain tasks or notes; it does not create real Planner or calendar reminders. Infer the correct action from conversational requests whenever possible."
default_headers:
  Accept: application/json
timeout_seconds: 30
pagination:
  default_page_size: 100
  max_page_size: 250
  max_pages_per_call: 10
  max_items_per_call: 500
examples:

"Use rest_mcp_server to add a todo for tomorrow: clean car."
Add a new task reminding me to review the ORDS spec tomorrow.
Save a reminder for tomorrow to review the ORDS spec.
Create a note about MCP server pagination and save the full details.
"Add this to my second brain: review the ORDS spec tomorrow."
Show me my second-brain entries.
Update entry 123 to mark it high urgency.
Delete entry 456.
columns:
name: entry_id
data_type: NUMBER
nullable: false
writable: false
description: Primary key identity column.
name: subject
data_type: VARCHAR2(255)
nullable: false
writable: true
description: Short subject line.
name: entry_type
data_type: VARCHAR2(30)
nullable: false
writable: true
description: Entry classification.
enum_values:

IDEA
TASK
NOTE
KNOWLEDGE


name: ai_summary
data_type: VARCHAR2(32767)
nullable: false
writable: true
description: AI-generated summary.
name: user_content
data_type: CLOB
nullable: false
writable: true
description: Full entry body.
name: urgency
data_type: VARCHAR2(30)
nullable: true
writable: true
description: Optional urgency.
enum_values:

LOW
MEDIUM
HIGH


name: action_required
data_type: VARCHAR2(1)
nullable: false
writable: true
description: Whether action is required.
enum_values:

Y
N


name: due_date
data_type: DATE
nullable: true
writable: true
description: Optional due date in YYYY-MM-DD format.

The model still needs to understand what the API represents in business terms, how it should behave when used, and which requests should trigger a call. A generic CRUD interface is flexible, but also vague.

Using a Skill for a second brain workflow

To counter this vagueness, I decided to create a skill focused specifically on the second brain ORDS API.

Agent Skills are folders of instructions, scripts, and resources that agents can discover and use to do things more accurately and efficiently.

This turned out to be more useful than I expected.

The Skill did three important things.

1. It guided the use of the REST API

The MCP tool exposed the API's mechanics. The Skill explained how to use it.

That distinction matters.

The tool knew how to call the endpoint. The Skill told the model when to create a note, when to update an existing item rather than insert a new one, which fields mattered, and how to interpret user requests in the context of a second brain.

Without that layer, the model has to infer too much from the tool signature and endpoint description. Sometimes that works. Sometimes it does not. The more domain-specific the workflow becomes, the more that gap shows up.

In practice, the Skill reduced a lot of that ambiguity.

2. It documented second brain functionality

The Skill also became a compact form of documentation.

Instead of only documenting the REST API as a technical interface, the Skill documented the behavior around the API. It explained what the second brain supports, the kinds of operations it is intended for, and the conventions the model should follow.

That is useful for the model and for me.

It gave me a single place to describe the intended workflow in practical terms rather than just API terms. In other words, it documented capability, not just transport.

I think this is an underrated part of Skills. They are not only prompt helpers. They can also serve as executable documentation for an AI-facing workflow.

3. It allowed explicit invocation with $skill

This was the third benefit, and in some ways, the most practical.

Because the behavior was packaged as a Skill, I could explicitly invoke it with $skill_name.

That gave me a clean way to direct the model toward a very specific behavior package. I was not just hoping the model would choose the right MCP tool based on a vague request. I could point it at the exact Skill that I knew would work with that second brain API.

That explicit invocation made the interaction more predictable.

---
name: "second-brain"
description: "Use when the user wants to add, update, list, or delete second-brain notes, tasks, ideas, knowledge items, or reminder-style entries through the local rest-mcp server. Prefer this skill when the user explicitly says $second-brain."
---

Second Brain
Use this skill for second-brain CRUD work through the local rest-mcp MCP server.
Core Rules

Use service_id: "jd_sb_entries".
Use path: "jd_sb_entries" for create and list. Use path: "jd_sb_entries/{entry_id}" for a specific row.
For filtered GET requests, use ORDS q filter syntax, not ad hoc column query params.
Preferred form: pass query as a native object and pass query.q as a native object. The MCP server will JSON-encode q.
Accepted alternate form: pass query as a raw query string such as q={"entry_type":{"$eq":"TASK"}}&limit=25.
Do not send second-brain filters as top-level keys like "entry_type": "TASK" unless the service explicitly documents that parameter.
For structured arguments, verify body and headers are native objects before calling the tool. For query, prefer a native object unless a raw query string is more direct.
Use page_limit and item_limit for pagination.
If fields, enum values, or filter keys are unclear, call rest-mcp.describe_service once. Do not retry blindly with alternate query formats.
Use ORDS operators inside q as needed: \(eq, \)ne, \(instr, \)like, \(gte, \)lte, \(or, \)and.
Keep list results compact and results-focused.
Never paste raw MCP response JSON into the user-facing reply. Extract the needed fields and summarize.

Fixed Playbooks

If the user asks to show, list, pull, or review active todos/tasks/reminders, make exactly one GET call with:

{
  "service_id": "jd_sb_entries",
  "method": "GET",
  "path": "jd_sb_entries",
  "query": {
    "q": {
      "entry_type": {
        "$eq": "TASK"
      },
      "action_required": {
        "$eq": "Y"
      }
    }
  },
  "page_limit": "1",
  "item_limit": "25"
}


For that active-task flow, do not probe with alternative query formats, do not call describe_service, and do not say "retrying" unless an unexpected runtime error actually occurred.
After fetching active tasks, sort by due_date ascending before replying unless the user asks for a different order.
Reply with only the compact task list: #entry_id subject — due YYYY-MM-DD.

Batch Rules

Default to single-item mode.
Enter batch mode only when the user clearly asks for multiple items or refers to a concrete earlier list.
For prior-thread items, restate a compact working list in the current turn before writing.
If the earlier items are missing or ambiguous, ask the user to narrow the scope or restate them.
Process at most 5 items per turn unless the user explicitly asks for more.
Create or update sequentially, one request_resource call per item.
If a batch partially succeeds, report completed items and the first failure clearly.

Field Mapping

todo, task, reminder -> entry_type: "TASK"
note -> entry_type: "NOTE"
idea -> entry_type: "IDEA"
knowledge -> entry_type: "KNOWLEDGE"
For todos/reminders, default action_required to "Y".
Default urgency to "LOW" unless the user says otherwise.
Use title case for subject unless the user specifies exact casing.
Use the raw user text or a slightly cleaned version for user_content.
Create a short ai_summary from the request.
Convert relative dates like tomorrow into an absolute YYYY-MM-DD date using the user's locale timezone.
Treat returned due_date values as ISO timestamps and present them back to the user as dates when only the date matters.

Request Patterns
Create:
{
  "service_id": "jd_sb_entries",
  "method": "POST",
  "path": "jd_sb_entries",
  "body": {
    "subject": "Clean car",
    "entry_type": "TASK",
    "ai_summary": "Reminder to clean the car tomorrow.",
    "user_content": "clean car",
    "urgency": "LOW",
    "action_required": "Y",
    "due_date": "2026-03-15"
  }
}

List active tasks:
{
  "service_id": "jd_sb_entries",
  "method": "GET",
  "path": "jd_sb_entries",
  "query": {
    "q": {
      "entry_type": {
        "$eq": "TASK"
      },
      "action_required": {
        "$eq": "Y"
      }
    }
  },
  "page_limit": "1",
  "item_limit": "25"
}

Search for entries containing a phrase:
{
  "service_id": "jd_sb_entries",
  "method": "GET",
  "path": "jd_sb_entries",
  "query": {
    "q": {
      "$or": [
        {
          "subject": {
            "$instr": "ORDS"
          }
        },
        {
          "user_content": {
            "$instr": "ORDS"
          }
        }
      ]
    }
  },
  "page_limit": "1",
  "item_limit": "25"
}

Read one row:
{
  "service_id": "jd_sb_entries",
  "method": "GET",
  "path": "jd_sb_entries/32"
}

Bad query examples:
"query": {
  "entry_type": "TASK",
  "action_required": "Y"
}

"query": "{\"entry_type\":{\"$eq\":\"TASK\"}}"

Good raw query-string example:
"query": "q={\"entry_type\":{\"\(eq\":\"TASK\"},\"action_required\":{\"\)eq\":\"Y\"}}&limit=25"

Response Style

For simple creates, reply with the created entry_id, subject, and due date.
For list/read requests, return the concise result only. Do not echo tool payloads, headers, links, or pagination blobs.
Keep the response short.
If the request is ambiguous, ask one concise clarifying question.

Demo

This recording shows a brief interaction with my 2nd brain after introducing the skill.

Why this pattern matters

The broader point is that MCP and Skills solve different problems.

I like this analogy from the Anthropic "The Complete Guide to Building Skills for Claude".

The kitchen analogy.

MCP provides the professional kitchen: access to tools, ingredients, and equipment. Skills provide the recipes: step-by-step instructions on how to create something valuable.

If you only expose a tool, you are giving the model capability. If you add a Skill, you are giving it operating guidance. For simple tools, that extra layer may not matter much. For anything with workflow, conventions, or domain context, it matters a lot.

That is why I think Skills work well as a thin layer on top of MCP-backed tools.

• They do not replace the server.

• They do not replace the API.

• They do not replace good tool design.

What they do is close the gap between “the model can call this” and “the model knows how this should be used here.”

Conclusion

A lot of MCP discussions focus on exposing tools, which makes sense. But once you start building real workflows, raw tool exposure is only the starting point. You also need a way to shape behavior around those tools.

For me, Skills are proving to be a good way to do that.

In this case, a simple STDIO MCP server exposed ORDS REST APIs for CRUD operations on a table. The Skill sitting on top of one of those APIs made the setup much more usable by guiding the workflow, documenting the behavior, and providing an explicit invocation surface via $skill.

That is a small design choice, but it has made the overall system feel much more intentional.

In a previous post, Adding an AI Agent to an Existing APEX App, I described how I added an AI agent to an existing APEX app. The goal was to simplify the user interface by providing an agent driven by a simple text interface.

As an APEX developer, this got me thinking: Are we heading towards a future where there is less focus on building APEX pages and more focus on building AI agents and the controls they require? Could agents completely replace UI?

I do not think agents will replace the user interface. But I do think they will redefine it.

Why enterprise apps look the way they do today

For years, we have built APEX apps around a simple assumption: a user operates the app. They open a page. They find the right menu. They enter data into a form. They click save. Then they move to the next screen and repeat.

That model is so familiar that it feels permanent. But it is not. It is mostly a workaround for the fact that traditional software has needed humans to drive every step.

If an agent can understand an instruction, gather context, decide what steps are required, and carry them out across one or more systems, what exactly is left for the user interface to do?

That is no longer a theoretical question. It is becoming a practical one.

A lot of enterprise software still revolves around transaction entry, status updates, approvals, routing, and repetitive record management. In many cases, the interface is not valuable because it is a great experience. It is valuable because it is the mechanism the system uses to make the user do the work.

That is where agents become disruptive.

Instead of forcing a user to navigate five screens and populate twelve fields, the interaction could start with something much closer to natural intent:

Create a new customer for Acme (details for Acme can be found in the CRM system), generate a sales order for 1,000 Aztec 100's using standard new customer pricing, send it for approval, and remind me next Tuesday if it has not been signed.

We don't need many APEX pages to implement this!

From manual operation to delegated execution

The most important change is not that software becomes conversational. The real change is that software no longer requires the user to translate business intent into system steps.

That translation has defined enterprise UX for decades. Users have had to know where to go, what fields matter, what sequence to follow, what validations apply, and which screen comes next. The interface has been the place where human intention gets broken down into machine-friendly actions.

That means the APEX app no longer has to be organized primarily around pages. It can be organized around goals, actions, and outcomes.

That is a major shift.

Where the “single text box” idea becomes useful

Once you accept that agents can handle more of the operational work, the obvious next question is whether the app can be reduced to a simple prompt box.

Probably not, but for some tasks, that actually makes sense.

Routine work is a strong candidate:

• Create a new supplier using the attached Invoice.

• Open a support request for this issue...

• Summarize sales by cost center for last month and compare it to this time last year

• Put a credit hold on Acme Corp

• Inactivate Item ABC

In those cases, the old interface often exists only because the system required structured, manual interaction. If the agent can reliably handle that structure, the screen becomes optional.

That is why this topic is not far-fetched. It points to a real weakness in much current software: too much of the interface exists because the software is rigid, not because the user actually benefits from the interaction.

The future is probably not just a text box

A text box is excellent for expressing intent. It is weak for verification, comparison, supervision, and control. That matters.

It is easy to say:

Reconcile these transactions and close the period.

It is much harder to trust that outcome without seeing:

• What exceptions were found

• Which records were changed

• What assumptions were made where confidence was low

• What could not be completed cleanly

• What still needs human approval

That is why I do not buy the lazy version of the argument that “UI is dead” or that “everything becomes chat.”

The better argument is that AI agents may eliminate a large percentage of the UI that exists purely for manual execution, while making a different kind of UI more important than ever.

The UI does not disappear. Its job changes.

I think that is the real story. The interface of the future is less about entering data and more about supervising action.

That means the valuable parts of the UI become things like:

• previewing what the agent is about to do

• approving consequential actions

• inspecting reasoning or decision traces

• handling exceptions

• reviewing changes across systems

• enforcing policy and permissions

• reversing or correcting bad outcomes

• understanding what happened and why

That is still UI. It is just no longer centered on the idea that the user must manually drive every step of the workflow.

In fact, once agents take over more of the mechanical burden, the remaining interface becomes more strategic. It becomes the place where trust is earned.

Enterprise systems will change unevenly

Some interfaces are much more vulnerable than others.

Low-risk, repetitive, high-volume workflows are the easiest targets. Administrative tasks, routine service requests, report generation, standard approvals, record creation, and straightforward updates are all likely to be heavily compressed by agentic interaction.

Finance, healthcare, procurement, compliance, and regulated workflows require more than just correct execution. They need visibility, auditability, traceability, and control.

In those environments, the agent may do more of the work, but the interface is not going away. It is becoming the control surface.

That is a very different design challenge from building page flows and forms, and it is more interesting.

What does this mean for us?

For a long time, the default design question has been: What pages do we need? That question is starting to look outdated.

A better set of questions is:

• Which parts of this workflow truly require human judgment?

• Which inputs are genuinely necessary?

• Which fields exist only because the system cannot infer context?

• Where can intent replace navigation?

• Where can the agent act safely on the user’s behalf?

• What needs to be visible before a human will trust the result?

• How do we design for intervention, not just execution?

That changes how we think about app design.

It pushes us away from page-centric systems and toward systems built around delegation, observability, and recovery.

For enterprise platforms in particular, that is a serious shift. The future is not just better forms. It is designing the boundary between autonomous action and human control.

What happens to APEX?

If the future of enterprise software relies on agents executing tasks and humans supervising them, APEX is still positioned well; if we change how we build.

We need to stop thinking of APEX primarily as a rapid CRUD builder and start treating it as an Agent Control Plane. The infrastructure to build this supervisory UI already exists within the APEX ecosystem; it simply needs to be repurposed.

Here is how APEX architecture must adapt to an agent-driven model:

• From Page Processes to Agent-Ready APIs: An agent cannot click a button to fire an APEX Page Process. Business logic must be rigorously decoupled from the UI. We need to expose strict, deterministic Oracle REST Data Services (ORDS) or self-contained PL/SQL packages. These become the literal "tools" the agent invokes to interact with the database.

• Human-in-the-Loop via the Approvals Component: When an agent attempts a high-stakes action or encounters ambiguity, it should not fail silently. Instead, the agent's backend process can start an APEX workflow instance. The Unified Task List becomes the "Supervisory UI," where humans review the agent's proposed action, inspect its reasoning, and approve or reject the action.

• Handling Asynchronous Agent State: Many AI agents operate asynchronously, often taking seconds or minutes to multi-step through a problem. Traditional APEX pages are synchronous. To bridge this gap, we can use APEX Background processes and APEX Automations to run agents in the background and use push notifications to send status updates to the client.

• Auditability: In regulated environments, auditability requires more than a record of what changed. Future APEX apps will need dedicated agent log tables to capture the task, supporting evidence, tool invocations, confidence signals, performed validations, and a concise decision summary. That trace should surface alongside the business record in the APEX UI to establish trust and traceability.

Conclusion

If by “user interface” we mean page-heavy, form-heavy, navigation-heavy systems built around manual data entry and procedural interaction, then AI agents probably do mark the beginning of the end for that model in many cases.

But if by “user interface” we mean the layer where humans express intent, review actions, manage risk, resolve ambiguity, and stay in control, then no. The UI is not ending. It is being redefined.

I am sure many of you are already using the OCI Email Delivery Service to send emails from your APEX Applications. It offers a convenient and inexpensive way to handle emails that integrates easily with APEX. Matt Mulvaney wrote a step-by-step guide to setting it up here.

If you are using this service and have asked yourself these questions, then this post is for you:

• How do I know if my email was bounced?

• How do I know if my emails are getting marked as spam?

• Basically, did the recipient receive the email?

To answer these questions, you must enable logging for your OCI Email Service. In this post, we will:

• Enable Email Delivery logs (OutboundAccepted/OutboundRelayed)

• Query logs via Logging Search API

• Surface results in APEX (Interactive Report) and/or sync to a table for history

Suppression Vs Bounce

Before we start, it is important to understand what the two types of email delivery logs reveal.

A bounce is a downstream delivery failure reported by the recipient’s mail system after an attempt is made (typically seen in the OutboundRelayed log) and usually points to issues such as an invalid mailbox, a missing domain, or temporary recipient-side problems.

Suppression often happens before any delivery attempt; your send can look “fine” from APEX’s perspective, but Email Delivery may block or drop the message due to policy, reputation, or suppression-list conditions (often visible in OutboundAccepted and sometimes reflected in log messages indicating a suppressed recipient). Practically, this is the difference between “the destination rejected it” and “we never really tried,” and it changes your remediation: bounces drive address hygiene and retry rules, while suppression drives sender/domain configuration and suppression-list/deliverability review.

What Can I Learn

I use these logs for APEX Developer Blogs, which has over 300 subscribers. Here are some examples of errors from these logs:

Setup Logging

Let's start by setting up logging from the OCI Console.

Navigation: Developer Services > Email Delivery > Click on Your Domain

Then click on the 'Monitoring' tab and scroll down to the 'Logs' section, click the ellipses for the 'Outbound Relayed' log, and click 'Enable Log'.

If you don’t already have a log group set up, click 'Create new group':

Enter a log group name and description, and click 'Create':

Once back on the Enable resource log page, click 'Enable log':

After a few seconds, your log should be active:

Adjust the retention period to match your audit needs/cost constraints.

Test the Logs

Send a test email from your instance to make sure it shows up in the logs:

DECLARE
  l_body  CLOB;
BEGIN
  l_body := '<h1>Testing APEX Mail</h1>';
  apex_mail.send
   (p_to        => 'test@example.com',
    p_from      => 'info@example.com',
    p_body      => l_body,
    p_body_html => l_body,
    p_subj      => 'Testing APEX Mail');
  apex_mail.push_queue;
END;

After a few seconds, you should see the message in the logs:

If we send an email to an invalid email address, we can see the bounce from the destination email server. Note: I have changed the OCIDs in the sample JSON below to 'AAA' and the domains to example.com.

{
  "datetime": 1771705254189,
  "logContent": {
    "data": {
      "action": "bounce",
      "bounceCategory": "bad-mailbox",
      "bounceCode": "5.1.10",
      "errorType": "hard",
      "message": "Suppressed recipient sam@example.com for email from info@example.com: bad-mailbox hard bounce",
      "messageId": "4B5C41B678F782A0E063E815000AC99A@apps.example.com",
      "originalMessageAcceptedTime": "2026-02-21T20:20:39.614Z",
      "receivingDomain": "example.com",
      "recipient": "sam@example.com",
      "reportGeneratedTime": "2026-02-21T20:20:41Z",
      "sender": "info@example.com",
      "senderCompartmentId": "AAA",
      "senderId": "AAA",
      "smtpStatus": "550 5.1.10 RESOLVER.ADR.RecipientNotFound; Recipient sam@example.com not found by SMTP address lookup"
    },
    "id": "4e81ce60-b8c7-40be-8a19-79448a3f4f2d",
    "oracle": {
      "compartmentid": "AAA",
      "ingestedtime": "2026-02-21T20:20:56.815Z",
      "loggroupid": "AAA",
      "logid": "AAA",
      "tenantid": "AAA"
    },
    "source": "example.com",
    "specversion": "1.0",
    "time": "2026-02-21T20:20:54.189Z",
    "type": "com.oraclecloud.emaildelivery.emaildomain.outboundrelayed"
  },
  "regionId": "us-phoenix-1"
}

In the above example, we received a hard bounce, indicating that the email address was invalid.

Documentation

• Details for Email Delivery Logging - JSON Examples and field descriptions.

• Email Delivery Policies - Setting up access to view the logs.

• Email Log Searching - Syntax for searching the email logs.

• Using the Logging Search API.

• Logging Query Language Specification.

Access the Logs from a REST API

Even though the OCI console includes a deliverability dashboard and a UI to access logs, it would be much easier if we could get these logs into the database so we can view them from an APEX page. In this section, I will cover how to set up an OCI service account to access the OCI Logging REST API.

Create an OCI User

Navigation: Identity and Security > Domains > Select your domain > Click Create

Enter a username and click 'Create':

Click Actions > Edit User Capabilities:

Uncheck all options except 'API Keys' and click 'Save Changes':

On the user page, select the 'API keys' tab, then click Actions > Add API key

Download the public and private key, then click 'Add':

Create an OCI Group

Back under the User Management tab, scroll down to Groups:

Create a new Group:

Add the new user to the group:

Create an OCI Policy

Navigate to: Identity & Security > Policies > Click 'Create Policy':

Complete the Policy details and click the 'Create' button:

Policy Statements:

allow group apex_rest_api_access_grp to read log-groups in tenancy
allow group apex_rest_api_access_grp to read log-content in tenancy

The Logging REST API

The OCI logging service offers a REST API you can use to consume any logs. My instance is in the Phoenix region, so my endpoint is:

https://logging.us-phoenix-1.oci.oraclecloud.com/20190909/search

You can see a full list of Logging Endpoints here, and details on using the search API here. You will also need to understand the logging query language. This query language allows you to filter results to see only bounces if that is what you are interested in.

The endpoint requires that you send a POST request with a payload like this:

{
  "timeStart": "2026-01-19T01:02:29.600Z",
  "timeEnd":   "2026-01-19T02:02:29.600Z",
  "searchQuery": "search \"<tenancy_ocid>/<log_group_ocid>/<log_ocid>\" | sort by datetime desc",
  "isReturnFieldInfo": false
}

API Limits

The Logging Search API returns up to 1000 entries per call and supports paging via a next-page token/header (client-managed). Searches/exports are limited to a maximum 14-day time window per request.

Consuming the Logging API from APEX

Create an APEX Web Credential

You will need an APEX Web Credential of type 'OCI Native Authentication' to access the REST API from APEX.

Enter the details from your OCI user's 'Configuration file preview' above. For the OCI Private Key, copy and paste the value from the private key file downloaded above. Click Create to complete the creation of the APEX Web Credential.

Consumption Options

APEX REST Data Source

The obvious first choice for consuming a REST API is to use a REST Data Source. I won't get into the step-by-step, but here are a few things that tripped me up when I created one.

In the 'POST' Operation, set the 'Database Operation' field to 'Fetch rows':

Delete the GET, PUT, and DELETE Operations; we do not need them.

Set up the following parameters:

In the Data Profile, set the 'Row Selector' field to 'results'.

Once all the above is in place, click 'Rediscover Data Profile', then click 'Replace Data Profile'.

Unfortunately, REST Source Types for 'Oracle Cloud Infrastructure (OCI) REST Service' do not automatically walk OCI Logging Search paging tokens. If you are only expecting a few hundred emails a week, that should not be an issue, as you can fetch up to 1,000 log entries at a time. You could create an Interactive Report based on the REST Source, add some Start and End Date Time parameters, and you have everything you need.

If you expect higher email volumes, you could use APEX_WEB_SERVICE to retrieve the data and loop through the pages yourself, or build a REST Source Connector plug-in.

Syncing to a Table

If you expect to send fewer than 1,000 emails per hour, it may be easier to use a REST Source Sync to sync the last hour's logs to a local table. This has the advantage of circumventing the 14-day window limit of the logging API.

You will need to use the REST Source Sync 'Steps' feature to pass the limit, START_TS, and END_TS parameters. In the example below, I am looking back 1 day. You may need to adjust this based on the number of emails you expect to receive.

Conclusion

Enabling OutboundAccepted and OutboundRelayed logs gives you a reliable way to determine whether an email was delivered, bounced, complained about, or suppressed.

For low-volume use, a REST Data Source plus an Interactive Report is usually sufficient, as long as you stay within the 1,000 records-per-call limit. For higher volume or longer retention, use a REST Source Sync (or PL/SQL paging) to persist results to a table and work around the 14-day query window. Once the data is local, you can join it to your tables and build deliverability views and alerts that meet your requirements.

Modern frontier LLMs are now reliable enough to support practical agent workflows when paired with strong orchestration and guardrails. Adding an agent to an existing APEX app allows you to:

• Simplify user workflows

• Simplify the user interface

• Automate repetitive tasks

• Leverage your existing data model, views, APIs, etc.

• Get the experience of building agents with minimal investment

In this post, I will use an example of an APEX-based project management application I have been building for a client off and on over the past few years. Over time, it has grown to more than fifty pages and thousands of lines of PL/SQL. A month ago, we started on a project to introduce an AI agent to simplify the app.

Introducing AI Agents

By combining a frontier model with tools (PL/SQL APIs, Web Services) and strong governance (permissions, auditing, guardrails), you can build an AI agent that executes multi-step business tasks, not just chats, safely within defined constraints.

Agents built for APEX use a PL/SQL framework to manage the 'Agentic Loop'. That's right; when you boil it down, an agent is a loop. Within this loop, the LLM makes suggestions as to which tools it wants to run; your code decides whether to run them. Your code is in control.

The diagram below illustrates the agentic loop.

The orchestrator controls the agentic loop, maintains state (in a database table) between tool calls, and decides when to hand control back to the user and when the loop should finish. The dispatcher receives tool requests, checks what data the user is allowed to see, performs schema and business validations, calls the tool, and returns the response to the orchestrator to feed back to the LLM during the next iteration.

This table illustrates the differences between a standard APEX approach and an Agentic approach:

Simplifying Project Management

So, let's get back to the project management app use case. The app handles everything related to project management, including questions, risks, issues, requirements, design documents, emails, and meeting notes. As the app grew and we introduced new pages, fields, and buttons, users started to get frustrated by how long it takes to navigate to where they need to go. I am sure Jira users can relate!

Agent Scope

For phase one of this project, we decided to limit the scope to allowing users to inquire about, create, and update project questions, risks, and issues.

Too often, we try to cover every use case and end up shipping nothing. That risk is higher with emerging technologies, where outcomes are uncertain. Narrowing scope doesn’t mean lowering the bar, it means delivering a genuinely useful slice that also proves whether the technology will scale to the entire app.

Tools

We gave the Agent the following tools:

• Show the project structure. This tool provides the information about the project, such as the customer, the project's structure, the project lead, etc.

• List project team members. This tool provides details of all the people associated with the project. This is used by the LLM to assign tasks, return tasks for specific people, etc.

• Search questions, risks, and issues. This tool allows users to perform searches using assigned to, status, question, risk, or issues text (via Vector Search).

• Create questions, risks, and issues

• Update questions, risks, and issues

Each tool is a PL/SQL function or procedure that either returns some JSON or performs an action. Because we started with a fully functional App, we were able to leverage existing tables, views, and PL/SQL APIs.

One of the most underrated parts of designing tools is the descriptive tool metadata that you send to the LLM with your prompt. The tool call metadata must clearly describe each tool along with its parameters. You should also resist the urge to include too many tools with each request to the LLM. Only send the tools that are relevant to the activity you are trying to perform. This prevents the LLM from having to look through and 'understand' tools it will never need.

The Orchestrator

The orchestrator is a PL/SQL procedure that controls the agentic loop. Essentially, the process involves looping, calling tools, and providing results back to the LLM until the user's request is completed (i.e., no further tool requests from the LLM).

We use a database table to maintain state between tool calls. This table allows us to re-construct the chat history and pass it to the LLM with each API call.

The Brain

The orchestrator passes a system prompt to the LLM during each request. This acts as the agent's brain. The system prompt provides background about the Application, the agent's objectives, rules for tool use, required behaviors, and how responses should be formatted.

Dispatcher

When the LLM requests a tool, the dispatcher does the following:

• Verifies the tool exists

• Verifies the validity of the parameters the LLM requested

• Verifies the user has access to the action, and or data being requested

• Executes the PL/SQL Function or Procedure

• Shapes the JSON response and hands it back to the Orchestrator to pass back to the LLM

Creates and Updates

With an emerging technology like this, you may be nervous about allowing the AI to request tool calls that create or update records in your database. Sure, you write the tool so you can ensure whatever record is created is valid, but what if the AI decides it wants to create 100 valid records when it should have been just one? To allay fears, we set up the agent and the tools with a flag indicating if a particular tool call requires human approval before it can run. Initially, we set all the create/updated tools to require human approval. Down the road, we expect that we may want to turn this confirmation off for some write tools.

Vector Search

I briefly mentioned that the Search tool uses Vector search so users can perform semantic searches on the text from questions, risks, issues (and the associated answers/responses). This allows users to perform powerful searches from a prompt. e.g., 'Find Open questions assigned to Jon related to California'.

We established a queueing mechanism that queues new and updated content. An APEX Automation picks up the queued content every 15 minutes. The automation chunks the content using the SQL function VECTOR_CHUNKS. The chunks are then vectorized using the SQL function VECTOR_EMBEDDING. We use the ONNX model ALL_MINILM_L12_V2 (available here) in the database to create the embeddings (vectorize the chunks).

Instrumentation

One of the most useful things we included at the beginning is comprehensive logging and diagnostics. Every LLM API call, every tool request, and every tool response is logged for each conversation. This allows us to replay conversations for audit and troubleshooting purposes.

It even allows us to troubleshoot strange behaviors using AI. For example, using the Oracle SQLcl MCP tool connected to the Codex App. I can say something like, "Review conversation ID 123 and find out why only 1 of the 3 provided issues were created by the agent." Codex can then use SQLcl to query the conversations table, and iterate until it determines whether the issue is code-related or system-prompt-related.

Lessons Learned

• Never trust the model to handle security or data integrity. Your code (orchestrator and dispatcher) and your data model should handle them. Always!

• Log everything and make conversations replayable for audit and troubleshooting.

• Make tools configurable to easily toggle human-in-the-loop confirmations.

• When writing CRUD PL/SQL APIs, don't assume the consumer is APEX. Your PL/SQL APIs must be hardened to handle calls from unexpected future sources, such as agents.

• Watch the context. Each call to the LLM passes the completed conversation history. As a conversation builds (especially if you have multiple tool calls returning large amounts of JSON), the LLM has to wade through more and more context to figure out what the latest request is. Consider capping the number of turns or preventing further turns after the context reaches a certain size.

• Enable parallel tool calls when calling the LLM API to reduce turns (switching between the user and the model in the Agent Loop). For example, if you want to copy-paste 10 questions to add, enabling parallel tool calls allows the agent to request that the create tool be called 10 times in one turn rather than one at a time. This allows the user to confirm creation of the items once, not 10 times, and reduces token usage. Parallel tool calls also reduce the amount of time the user must wait for their request to complete.

• When something fails (e.g., you get a PL/SQL exception during a tool call), do not pass the Oracle error message back to the LLM. Instead pass something meaningful like "the project team tool is not responding". This allows the LLM to fail gracefully and inform the end user.

• Do not allow your agentic loop to run forever. Set a maximum number of iterations where you end the loop no matter what. Make this configurable so you can adjust it during testing.

• Each LLM API call takes between 2 and 10 seconds to run. If the agent has to call the LLM several times during a request, the overall duration can add up quickly. You can influence this by playing with the model and the reasoning level (the higher the reasoning level the more the model thinks and the longer it takes). Use the fastest model with the lowest reasoning level which still gives good results for your use case. You can also help by improving the user experience while they wait. As you will see in the demo below, we took the time to build a custom blocking spinner that is displayed while the agent is working.

Demo

A picture is worth a thousand words, as they say. This short video shows a typical session with the Agent.

• Projects are structured by sections and sub-sections.

• The context area provides context for the user's prompt.

• I did not show it in the demo, but the response includes links that let users open Questions, Risks, and Issues directly from the agent. This makes use of existing APEX pages.

As you can see, the user can take a question through its full lifecycle without leaving the page. This demo only shows you a fraction of what is possible with just five tools. Some other sample prompts:

• Find questions related to VAT Tax

  • The search tool uses vector search to find questions, risks, and issues related to VAT.

• Review the attached meeting transcript (copy-paste it into the Context field), extract all questions, risks, and issues, and organize them into subsection 20.

  • This is pretty powerful. We used the LLM to analyze the meeting transcript and extract all questions, risks, and issues raised during the meeting. The LLM extracted them and then invoked the create tool multiple times to populate the database with questions, risks, and issues.

Behind the Scenes

Privileged users can enable diagnostics. Diagnostics show all of the records tracked during the conversation, including requests for tool calls and responses from tool calls. In the screenshot below, you can see the diagnostics for one turn from the demo video. The diagnostic records are identified with the brown '...' avatar.

• We submitted a request, "answer question 110662 with yes"

• The model took the question along with the system prompt and broke out the answer "yes" from the request. It then looked at the provided tools and requested that we call the qri_search tool to find the question

• We ran the tool (after checking the user had access), and returned the JSON result containing details of the questions we found

• The LLM interpreted this tool response JSON, confirmed there is just one question, then requested we call the update_qri tool

• The update_qri tool requires a human confirmation, so the Orchestrator saved the tool request from the model and stopped to allow the user to click the Confirm/Reject button.

• After clicking Confirm, the Orchestrator called the LLM one last time with the result from calling the update_qri tool.

• The LLM decided it didn't require any more tool calls, which ended the turn.

Conclusion

Adding an AI agent to an existing APEX application is a practical way to introduce AI capabilities without rewriting your system. Most applications already have the hard parts in place: a data model, business APIs, validation logic, and security rules. An agent simply becomes another consumer of those APIs.

The key is to keep the architecture straightforward. Let the LLM interpret user intent and suggest actions, but keep control in your code. The orchestrator manages the loop, the dispatcher validates and executes tools, and your existing PL/SQL APIs enforce business rules and data integrity.

Start with a limited scope, a small set of well-defined tools, and strong instrumentation. Once the architecture is in place, you can expand the agent’s capabilities incrementally.

In our case, just five tools were enough to let users search, create, and update project questions, risks, and issues directly from a chat interface. The result was a simpler workflow for users and a new way to interact with the application without changing the underlying system.

For teams already building applications with Oracle APEX, agents are a natural extension of the platform. The important part is not the model, it is the architecture around it.

A few weeks ago, I started building an APEX 2nd brain to practice Agentic AI in APEX and PL/SQL, and hopefully create a useful tool to supplement my aging brain.

I am writing this post while Codex is rebuilding my APEX 2nd brain Application from scratch. This post is a cautionary tale about what happens when you go down the vibe coding rabbit hole.

The Rabbit Hole

The first version of my 2nd brain APEX App included a simple text box on a single APEX page. When the user clicks the submit button, I pass a predefined prompt that provides instructions for filing the entry, along with the entry itself, to an LLM for classification. There was also an APEX Automation, which ingested my personal and work emails and calendar entries from Gmail and MS Office.

It worked OK, but I soon found the features limiting (especially with all the news about what people we are achieving using Open Claw). For the record, I do not use Open Claw.

With the new Codex App and a prompt first strategy, I started making enhancements. It was going great… I would ask for feature after feature, and they would get built and work 90% of the time. After a couple of hours, I stepped back and looked at the actual code that had been written:

• I ended up with 800 lines of JavaScript in the main APEX page (that’s more JavaScript than I write in a year).

• Instead of using my AI config tables, which store system prompts, tool calls, etc., the AI wrote the system prompts and tool calls JSON and hard-coded them into the code.

• The quality of the data model had degraded over time as fields were added, removed, and repurposed, and tables were abandoned. Each new table or set of tables was very well thought out, but there was no consideration for tidying up the old tables.

• The AI was overly cautious about dropping old code. By the end, I was left with several views and packages that were no longer used. This amounted to more than 2,000 lines of unused code.

The other side effect was that the overall architecture had drifted and become overly complex and bloated. The issue isn’t the AI; it’s unbounded iteration without thought.

Essentially, it was the work of a competent and overly eager junior programmer. There were no egregious issues (other than not cleaning up old code), but it was not the way I would have done it.

Stepping Back & Resetting

Write a Specification

I decided to take a step back and reassess what I actually wanted, and spent an hour writing a detailed specification. You can read the specification here.

This produced two benefits:

1. It forced me to think about what features were important to me.

2. It provided the AI with much clearer guidance on what it was supposed to do. Instead of 10 disjointed prompts with feature requests, it had a single specification on which to build a solid architecture.

AGENTS.md

I also updated my AGENTS.md to include some additional instructions:

• Prefer PL/SQL over JavaScript. When JavaScript is necessary, prefer Dynamic Actions over Ajax Callbacks.

• Utilize AI Configuration tables gen_ai* to specify new prompts and tools.

• Tell me if I suggest changes that contravene APEX and PL/SQL best practices.

Lessons Learned

• Always write a spec first. However simple it is, writing it out first helps you organize your thoughts and provides valuable guidance and structure for the AI.

• LLMs ❤️ JavaScript more than PL/SQL. Unless you instruct them otherwise, they will generate far too much unnecessary JavaScript. They also love Ajax Callbacks; it’s not that they don’t know about Dynamic Actions, they just prefer Ajax Callbacks.

• AGENTS.md is a live document; every time the LLM does something you don’t like, tell it by updating AGENTS.md.

• After implementing a new feature, always follow up with a prompt to have the LLM check for unused code. More importantly, ask it to follow the entry points to your app and suggest entire branches of unused code. Also, run a check for data model drift. Codex is very good at doing this; it just needs to be told to do it.

• When using plan mode in Codex or Claude (which I highly recommend), read the plan! This may sound obvious, but when I started out, I would just skim the plan and hit Go. Providing input after the plan is produced is often the last chance to direct the LLM once implementation begins. Adjustments made at this stage can save you hours later on.

• If you start a thread with an LLM and get to around 5 turns, press pause ⏸️ to think. Ask yourself whether you are on the edge of the AI 🐇 🕳️❓ Ask yourself: Will the next prompt really get me there, or should I start again with a better spec? The answer is usually the second one, but it is hard to step back!

Time for Controversy

With the major improvements made to coding in Claude Opus 4.5/4.6 and Codex 5.2/5.3, I have been asking myself whether I really need to ‘know’ all the code I create. If AI generated it, then surely AI will be better at maintaining it than I am?

My answer (at least for now) is that I do need to understand the code I / the AI creates.

• I am responsible for the code, not the AI. It will be a dark day indeed when developers stop being responsible for the code they produce.

• I still feel that my taste/instincts/intuition are better than the AIs. This is the main advantage humans have over humans (at least right now); we should make the most of it.

• We are not close to finding all of the edge cases. Even for this personal project, I added three edge cases to my AGENTS.md and went back to my Spec a few times to guide the AI. We are still a long way off from a fire-and-forget approach to AI development.

Conclusion

Vibe coding is a superpower; right up until it quietly turns into your architecture.

The problem wasn’t Codex. It was me letting a long thread become the design process. The AI will happily keep shipping “reasonable” changes forever, but it has no instinct for simplicity, no taste, and no discomfort about leaving dead code and abandoned tables behind.

The fix also wasn’t “use less AI.” It was put the AI back inside guardrails: a written spec, a clear APEX-first strategy (Dynamic Actions over callbacks, PL/SQL over page-level JavaScript), and an AGENTS.md that I actually maintain. Once those constraints are in place, AI is great, not just at building features but at tracing entry points, finding dead branches, and calling out drift. It just needs to be told to do it.

And on the “do I need to know the code?” question: for now, yes. Maybe I don’t need to know every generated line, but I absolutely need to own the architecture, the data model, and the edge cases, because the day something breaks (or leaks), it’s my name on it, not the model’s.

When using single sign-on type authentication schemes like Social Sign-In, you need to define a Post-Logout URL in APEX so that the Authentication provider redirects your APEX App to a public page after it completes the logout. When you deploy your App to TEST and PROD, the Post-Logout URL (Public Page) changes with your instance URL. This introduces a challenge: the Post-Logout URL setup in APEX does not easily support dynamic values, so you must manually update it after deploying your App.

Background

The diagram below shows a typical logout flow for a Social Sign-In type Authentication Scheme. In my use case, I want the Authentication provider to redirect to a public page in my APEX App after the logout completes.

In the APEX Authentication Scheme, we can specify where we want APEX to go after logout is complete:

You can specify either:

• Home Page - Attempts to go to the home page after logout; because the session is invalid, it then redirects to the login page. This is not suitable for Social Sign-In because it will just trigger another login with the Authentication Provider.

• URL - You can specify a URL APEX should go to after the logout. Unfortunately, the Post-Logout URL field does not support APEX-style runtime substitution such as f?p=&APP_ID.:9999. On the surface, the best you can do is enter a hard-coded URL, e.g., https://example.com/ords/dev/logout-page. When deploying to TEST or PROD, we must change this URL manually (there is no API).

The Solution

The best workaround I have come up with is as follows.

1 - Create an Application Item

Create an Application Item to store the Post-Logout URL. Here is a screenshot of the Application Item, which, for my example, I have called AI_POST_LOGOUT_URL.

2 - Create an Application Setting

Create an Application Setting to store the Post-Logout URL. Here is a screenshot of an Application Setting named POST_LOGOUT_URL.

This means the first time you deploy your App to a new instance, you will need to change the URL to the appropriate URL for the target instance. Moving forward (as long as you have ‘On Upgrade Keep Value’ set to Yes), you will no longer have to change it.

3 - Populate the Application Item for New Sessions

You will need to set the application item AI_POST_LOGOUT_URL to the value of the Application setting when creating a new session. The easiest place to do this is in an ‘After Authentication’ Application Process. In the screenshot below, I am calling apex_session_state.set_value directly from the ‘After Authentication’ Process of my App.

BEGIN
  -- Copy the environment-specific setting into session state once per login
  apex_session_state.set_value 
    (p_item  => 'AI_POST_LOGOUT_URL', 
     p_value => apex_app_setting.get_value('POST_LOGOUT_URL'));
END;

4 - Set the Post-Logout URL to the Value of the Application Item

Finally, we must set the Post-Logout URL to the value of the Application Item AI_POST_LOGOUT_URL:

Alternatives

Of course, you do not have to use the APEX Application Setting to store the URL. You could store the URLs in your own table keyed on the instance SID/Service Name, but I think storing them in an APEX Application setting is more compact and standard APEX.

Because the Post-Logout URL ultimately controls the redirect, you should ensure it is fully trusted and not user-modifiable. Application Settings are ideal here because they are developer-controlled and not influenced by runtime user input.

Conclusion

This pattern has proven reliable and eliminates a common manual deployment step when using Social Sign-In in APEX.

I have been using AI to help me build APEX Apps for well over a year now, and I’ve shared a lot about the tools and workflows I use. But something happened this week that felt like a genuine shift.

Usually, I use AI for things like autocomplete, understanding a codebase, and code reviews. I even use it for creating new procedures and functions, but the results vary in quality. This week, on two separate occasions, I had the AI generate hundreds of lines of PL/SQL, resulting in production-ready code (after review and testing). It included validations, handled edge cases I hadn't explicitly listed, and followed my approach perfectly. In this post, I want to break down the specific factors that made these efforts successful, even as others failed.

Metadata: The AI’s Rosetta Stone

The first key to this success wasn't the prompt; it was the database schema.

• Clear, unambiguous column names.

• Tables and columns have clear, plain English comments.

• Foreign Key Constraints that clearly define the table relationships.

• Check Constraints to define valid values for columns, where possible.

• NOT NULL Constraints to identify which columns must be populated.

• Unique constraints / natural keys.

Because I provided the AI with the DDL (including this extra metadata), it didn't just see a table; it inferred far more of the business rules with fewer guesses. It knew that a column named STATUS_CODE wasn't just a string, but a state-machine driver. When the metadata is clean, the model makes fewer incorrect assumptions.

The Spec is the Work

If I spend all this time writing a detailed spec for the AI, I could have just written the code myself.

This is something that I used to think until I realized I was wrong on two counts:

1. In most cases, I have to write a spec anyway, so the client can review it and I can be sure I am on the right path.

2. A well-thought-out spec can make the difference between average and near-perfect results when an LLM is generating code.

I did change the way I write my specs. I now write them in Markdown (using Obsidian) and export to Word using an Obsidian plugin that runs Pandoc if the client needs a Word copy. I also annotate the spec with hints for the AI, such as table names and references to procedures that perform similar logic. I make these annotations using HTML comments, which Pandoc excludes when exporting to Word.

Here is an example excerpt using HTML comments for annotations:

The App should then create a child RFQ and RFQ lines for each supplier.
<!-- AI > Use tables: SPTL_RFQ_SPLR_HEADER and SPTL_RFQ_SPLR_LINE -->

Leveraging Existing Patterns

In my case, AI wasn't starting from a blank slate. I was adding code to an existing package, and I also had other packages in the repository that the AI could reference for context.

In one instance, I had a specific pattern established for processing file uploads:

1. Upload records from Excel into an APEX_COLLECTION using APEX_DATA_PARSER.

2. Run validations to check the uploaded records for errors.

3. Allow the user to review the validated records before final processing.

4. Perform the final import into the base tables.

I pointed the AI to two existing procedures that followed this pattern and said, "Follow the pattern in procedures X and Y, but apply the logic from the specification below…".

The Power of AGENTS.md

The final piece of the puzzle was the use of AGENTS.md. AGENTS.md is a file containing instructions that many coding agents, such as Codex, Cursor, and Claude, pass to the LLM along with your prompt. My AGENTS.md files are constantly evolving, but they typically include instructions like:

• Use APEX PL/SQL APIs where possible APEX_STRING, APEX_JSON, and APEX_DEBUG over custom logic.

• Use set-based logic where possible instead of FOR loops.

• Avoid Dynamic SQL wherever possible; if unavoidable, always use bind variables and validate identifiers (e.g., DBMS_ASSERT) to reduce SQL injection risk.

• The folder structure of the codebase.

• Prefer %TYPE and %ROWTYPE

• No hard-coded schema names.

• Always include APEX_DEBUG calls in exception handlers and major logic branches.

• Code formatting rules.

• etc.

Without this file, the AI defaults to "generic" PL/SQL. With it, the AI becomes an expert in my specific preferences and standards.

Warning!

As I’ve said before, AI is a tool, not a crutch. The code you build is your responsibility (not the AI’s). For now, at least!

• Understand the Output: Before committing the code, you should understand what it does and that it is doing what it is supposed to do.

• Security is Your Job: I still manually check security settings at the end of every project. AI can find vulnerabilities, but it shouldn't be the only one looking.

• Test, test, and test again: AI does not replace testing, though it can help with it.

The AI-Generated Code Checklist

• Clean DDL + constraints + comments included

• Markdown spec with rules + edge cases

• Reference 1–2 existing “golden” procedures

• Repo instructions (AGENTS.md)

• Run tests + security review + performance sanity check

Conclusion

This week proved that we are moving toward a world where the APEX Developer acts more like a conductor than a member of the orchestra. I think I am OK with this, but it does take some getting used to.

If your database design is solid, your patterns are consistent, and your requirements are clear, the actual coding becomes a commodity. The AI didn't just save me time; it allowed me to stay in the "flow state" of designing the solution rather than getting bogged down in the syntax of a 300-line package body.

If you haven't reached this inflection point yet, stop focusing solely on the "prompt" and start considering the context you provide to the AI.

Exciting times ahead!

If you, like me, have wondered why you would ever use Open Door Credentials, then this post is for you.

Open Door Credentials are a powerful tool when used for the right reasons and in the correct instance. They make testing and troubleshooting easier, especially for applications using Authentication Schemes like Social Sign-On, but they require discipline and restraint.

What are Open Door Credentials?

Open Door Credentials allow you to sign on to an APEX application using a username and a password. Nothing unusual there. The difference is that you can sign in using any username and password, even if they do not exist in your application. You can enter Username: ABC and Password: XYZ, and APEX will still let you in. This applies only to Authentication. Authorization, application logic, and security checks still apply and should be used to control what the authenticated user can actually do.

Once the user is signed in with Open Door Credentials, as far as your APEX App is concerned, there is nothing different:

• Once authenticated, the username behaves like any other value in :APP_USER. This means all authorization schemes, row-level security logic, VPD policies, and application-specific checks will execute exactly as they would for a real user, assuming you validate the username correctly.

• Any code you have in the Login Processing section of the Authentication Scheme (Pre-Authentication Procedure Name, Post-Authentication Procedure Name) is still executed.

Why are Open Door Credentials Useful?

Open Door Credentials are particularly useful during the testing phase of a project and for troubleshooting issues. They allow you to experience exactly what that user is experiencing.

An example of where Open Door Credentials are useful is when testing APEX Workflow. With APEX Workflow, you often need to log in as multiple users to test the process end-to-end. Getting all the participants on a call to test is impractical, and having their passwords is insecure. Open Door Credentials allow you to test the end-to-end process yourself.

Words of Caution

• It may seem obvious, but I will say it anyway. Never use Open Door Credentials in Production.

• Open Door Credentials should not be used (even in DEV) for applications that store personally identifiable information or any other data that requires security. That is, unless you mask this data when you clone from PROD to DEV/TEST.

• If your DEV APEX App is open to the internet, then you should either add an IP restriction to your load balancer or restrict access to the APEX App you are testing by IP Address while testing with Open Door Credentials.

• Validate the username. Open Door credentials will accept any username and password. You should validate that the username is a valid user of your application in the Application Level Authorization Scheme (hopefully, you were already doing this).

How to Create Open Door Credentials

Navigate to Shared Components > Authentication Schemes

Click Create and select ‘Based on a pre-configured scheme from the gallery’.

Select ‘Scheme Type’ as ‘Open Door Credentials’, and click ‘Create Authentication Scheme’.

Add your usual Pre and Post-Authentication logic:

Logging In

When you make the new Authentication Scheme, the current scheme and login, you will be presented with an APEX-generated login page like this:

Note: When using Open Door Credentials, the password value is ignored by the Authentication Scheme. Any password will be accepted.

Interestingly, some environments, e.g., https://oracleapex.com/, only show the username:

Deploying the App from DEV to PROD

Unfortunately, Authentication Schemes do not currently have Build Options. With a build option, you could set it so that APEX automatically excludes the Authentication Scheme whenever you export it for deployment to another instance.

Not having Build Options means you must manually delete the Open Door Credential Authentication Scheme before you deploy to PROD. There is an idea in the APEX Ideas App to add Build Options to Authentication Schemes. Even though it is flagged as on the Roadmap, it is over 4 years old, so I encourage you to vote for it.

Alternatives to Open Door Credentials

Another option is to use the Oracle APEX Accounts Authentication Scheme and create dedicated test users. This approach uses real credentials, but it requires you to build a login page and ongoing user management, which may be impractical for short-lived testing scenarios.

Conclusion

Open Door Credentials are a powerful tool when used for the right reasons. They make testing and troubleshooting simpler, especially for applications using external authentication, but they require discipline and restraint. Use them responsibly, lock them down properly, and remove them before deploying to production.

I have lost count of how many times I have developed an Excel Upload using APEX_DATA_PARSER. It provides users with a convenient way to mass-upload or update data using a tool they are familiar with. I usually include a link to a static Excel Template File that users can download to understand the structure they need to include in their upload.

Use Case

In a recent project, I was tasked with building a Hierarchy Management Application. This involved loading nodes (and their attributes), then loading hierarchies composed of those nodes. I’ll be focusing on the node (and attribute) upload.

The Nodes APEX UI looks like this:

• A Segment Type is a grouping of like nodes.

• The Bonus Eligible column is a custom node attribute. Users can specify up to 20 custom attributes for each Segment Type.

👉 Enter apex_data_export.

Goal

The goal is to download an Excel file containing the existing rows and columns for a Segment Type, make updates, and re-import it to apply those updates.

Approach

Build SQL

My approach was first to build a function to generate dynamic SQL for both the APEX page shown above and for apex_data_export to use. The function below is intended to show an approximation of the function (it is not the actual code).

FUNCTION get_node_sql 
  (p_segment_type_id IN apx_rdm_segment_type.segment_type_id%TYPE) RETURN CLOB IS

  CURSOR cr_segment_attributes 
   (cp_segment_type_id IN apx_rdm_segment_type.segment_type_id%TYPE) IS
    SELECT attr.attribute_code
    ,      attr.data_type_code
    ,      attr.attribute_name AS display_value
    FROM   apx_rdm_segment_type_attr sta
    ,      apx_rdm_attribute         attr
    WHERE  attr.attribute_id   = sta.attribute_id
    AND    sta.segment_type_id = cp_segment_type_id
    ORDER  BY sta.sort_order;

  (p_segment_type_id IN apx_rdm_segment_type.segment_type_id%TYPE) RETURN CLOB IS
  l_sql               CLOB;
  l_col_count         PLS_INTEGER := 0;
  lc_lf               CONSTANT VARCHAR2(1) := CHR(10);
BEGIN

  -- Build the base columns for the hierarchy node.
  l_sql := 'SELECT hnode.node_code, hnode.node_name, hnode.system_name, hnode.postable_flag, hnode.active_flag' || lc_lf;

  -- Loop through custom attributes and Append a MAX(...) expression per 
  --   attribute assigned to the segment type.
  FOR rec IN cr_segment_attributes (cp_segment_type_id => p_segment_type_id) LOOP
    l_col_count := l_col_count + 1;
    EXIT WHEN l_col_count > 20;
      l_sql := l_sql
        || ',      MAX(CASE WHEN attrval.attribute_code = '''
        || REPLACE(rec.attribute_code, '''', '''''')
        || ''' THEN attrval.attr_value_varchar END) AS "'
        || REPLACE(rec.attribute_code, '"', '""')
        || '"' || lc_lf;
  END LOOP;

  -- Add FROM and WHERE clauses.
  l_sql := l_sql ||
  'FROM   apx_rdm_hierarchy_node_svw hnode
  LEFT JOIN apx_rdm_node_attribute_value_vw attrval 
    ON     attrval.node_id = hnode.node_id
    WHERE hnode.segment_type_id = :SEGMENT_TYPE_ID' || lc_lf;

  -- Add Group By Clause.
  -- Attribute values are aggregated with MAX so they do not belong in the GROUP BY.
  l_sql := l_sql || 'GROUP BY hnode.node_code, hnode.node_name, hnode.system_name, hnode.postable_flag, hnode.active_flag';

  RETURN l_sql;

END get_node_sql;

Fetch SQL, Format Output, Generate & Store Excel

Next, write a procedure to generate the Excel Upload Template File. Again, the code below is an extract of the highlights from the actual code and is not complete.

PROCEDURE generate_node_upload_template
 (p_segment_type_id   IN apx_rdm_segment_type.segment_type_id%TYPE,
  p_segment_type_code IN apx_rdm_segment_type.segment_type_code%TYPE) IS

  -- apex_exec and apex_data_export types.
  l_xlsx_context        apex_exec.t_context;
  l_sql_params          apex_exec.t_parameters;
  l_xlsx_export         apex_data_export.t_export;
  lt_columns            apex_data_export.t_columns;
  l_print_config        apex_data_export.t_print_config;
  l_sql                 CLOB;

BEGIN

  -- Generate the SQL to retrieve the nodes and their attributes.
  l_sql := get_node_sql (p_segment_type_id => p_segment_type_id);

  -- Add Static Colummn Definitions and Headings.
  -- Note the use of p_is_frozen to the first three columns. This will freeze 
  --  these three columns in the Excel output. 
  -- The frozen columns must be the first contiguous columns.
  -- p_heading is the value used in the output Excel.
  apex_data_export.add_column
   (p_columns => lt_columns,
    p_name    => 'NODE_CODE',
    p_heading => 'Node Code',
    p_is_frozen => TRUE);
  apex_data_export.add_column
   (p_columns => lt_columns,
    p_name    => 'NODE_NAME',
    p_heading => 'Node Name',
    p_is_frozen => TRUE);
  apex_data_export.add_column
   (p_columns => lt_columns,
    p_name    => 'SYSTEM_NAME',
    p_heading => 'Source System Name',
    p_is_frozen => TRUE);
  apex_data_export.add_column
   (p_columns => lt_columns,
    p_name    => 'POSTABLE_FLAG',
    p_heading => 'Postable Flag');
  apex_data_export.add_column
   (p_columns => lt_columns,
    p_name    => 'ACTIVE_FLAG',
    p_heading => 'Active Flag');

  -- Loop through attributes for the Segment Type adding dynamic attribute columns.
  FOR lr_segment_attrs IN cr_segment_attributes (cp_segment_type_id => p_segment_type_id) LOOP
    apex_data_export.add_column
     (p_columns => lt_columns,
      p_name    => lr_segment_attrs.attribute_code,
      p_heading => lr_segment_attrs.display_value);
  END LOOP;

  -- Add SQL Parameters / Bind Variable Values
  apex_exec.add_parameter(l_sql_params, 'SEGMENT_TYPE_ID', p_segment_type_id);

  -- Add Branding Colors to the Heading and make Heading Font Size Larger.
  l_print_config := apex_data_export.get_print_config
                     (p_header_bg_color   => '#020381',
                      p_header_font_color => '#FFFFFF',
                      p_header_font_size  => 11);

  -- Open the Query Context, bind the parameters and execute the query.
  l_xlsx_context := apex_exec.open_query_context
                     (p_location       => apex_exec.c_location_local_db,
                      p_sql_parameters => l_sql_params,
                      p_sql_query      => l_sql);

  -- Export to XLSX format
  l_xlsx_export := apex_data_export.export
                     (p_context           => l_xlsx_context,
                      -- ⬇️ Determines the Export File Format
                      p_format            => apex_data_export.c_format_xlsx,
                      -- ⬇️ Defines the Columns and Headings in the Export
                      p_columns           => lt_columns,
                      -- ⬇️ Used for the Excel Tab Name
                      p_page_header       => p_segment_type_code,  
                      -- ⬇️ Text Appears at the top of the Excel Sheet
                      p_supplemental_text => 'This template is to be used for uploading Nodes into the [' || 
                                              p_segment_type_code || '] Segment Type. ',  
                      -- ⬇️ Name of the Exported File
                      p_file_name         => 'Node_Upload_Template',
                      -- ⬇️ Print Configuration to use for the Exported File
                      p_print_config      => l_print_config);
  apex_exec.close(l_xlsx_context);

  -- Store the Exported File in an APEX Collection for Later Use.
  apex_collection.create_or_truncate_collection(p_collection_name => 'NODES_TEMPLATE_COLLN');
  apex_collection.add_member
   (p_collection_name => 'NODES_TEMPLATE_COLLN',
    p_blob001         => l_xlsx_export.content_blob,
    p_c001            => l_xlsx_export.file_name);
END generate_node_upload_template;

• You don’t have to use apex_data_export.add_column. If you do not, then APEX will use the column names (or aliases) from your SQL for the column headers.

• The p_is_frozen parameter apex_data_export.add_column has to be applied to all of the columns you want frozen.

• For my use case, I call the generate procedure above from a Dynamic Action, temporarily store the Excel file in a Collection, and then download it using the Download Dynamic Action (check out this post from Louis Moreaux for more).

More on apex_data_export

In this post, I focused on a specific use case and some specific features of apex_data_export. In this section, I will cover additional key features and user cases.

Other Key Features

Column Grouping

The apex_data_export.add_column_group API allows you to organize columns into groups with group headings to generate something like this:

Aggregating

The apex_data_export.add_aggregate API allows you to calculate totals for numeric values. This can be used in conjunction with the p_is_column_break parameter of apex_data_export.add_column to generate group totals.

Highlights

The apex_data_export.add_highlight API allows you to highlight cells in your output based on columns in your data source. The way this works is a little different.

In your SQL, return the highlight ID based on the criteria you want to use. In the example below, I have two highlights with IDs 1 and 2.

SELECT order_number
,      order_total
,      due_date
,      CASE WHEN order_total > 1000 THEN 1 END AS order_total_highlight
,      CASE WHEN due_date > SYSDATE THEN 2 END AS due_date_highlight
FROM   orders

-- Define Highlight for Order Total
apex_data_export.add_highlight(
        p_highlights          => l_highlights,
        p_id                  => 1,         -- Order Total Highlight from SQL
        p_value_column        => 'ORDER_TOTAL_HIGHLIGHT',
        p_display_column      => 'ORDER_TOTAL',  -- Where to put the highlight
        p_text_color          => '#FF0000' );

-- Define Highlight for Due Date
apex_data_export.add_highlight(
        p_highlights          => l_highlights,
        p_id                  => 2,         -- Due Date Highlight from SQL
        p_value_column        => 'DUE_DATE_HIGHLIGHT',
        p_display_column      => 'DUE_DATE',  -- Where to put the highlight
        p_text_color          => '#FF0000' );

• If the SQL returns a 1 for the order_total_highlight column, then the highlight is applied; otherwise, it is not. The same goes for due_date_highlight, except it needs to return a 2 for the highlight to be applied.

Download

The apex_data_export.download API allows you to initiate a download of the file generated by apex_data_export (or any other BLOB for that matter). Check out this post from Haniel Burton for more.

Print Config

The apex_data_export.get_print_config API, when used in conjunction with the p_print_config parameter of apex_data_export.export, is used to drive print formatting for your export. Here are the settings applicable to Excel exports:

• Page Header (p_page_header) is used for the tab name, unless overridden in the parameter with the same name in the call to apex_data_export.export.

• Page footer-related parameters (p_page_footer_…): add and format text below the last cell in the Excel output.

• Heading-related parameters (p_header_…): apply formatting to the Excel column headings.

• Body-related parameters (p_body_…): apply formatting to the rows in the Excel output.

• Border-related parameters (p_border_…): apply formatting to the cell borders in the Excel output.

Other Use Cases for APEX_DATA_EXPORT

In this post, I focused on a specific use case, but there are many others for apex_data_export.

• Exporting Setup Data in JSON for import into other systems or moving setups from DEV > TEST > PROD.

• Generate downloads of data triggered from a button press, where you don’t have an Interactive Report or Grid to handle the download.

• Generate a report from an APEX Automation and attach it to an email for distribution.

• Generate specialized “operational snapshot” files for downstream teams or auditors: Use the API to produce point-in-time exports (with highlights, aggregates, or formatting) from PL/SQL jobs, ideal for monthly financial freezes, audit cycles, or HR snapshots.

APEX_EXEC

Part of the flexibility of apex_data_export stems from its use of the powerful apex_exec API. This allows you to generate exports from REST APIs just as easily as from database tables.

Conclusion

Dynamic Excel template generation is one of those APEX features that solves a real problem: keeping users aligned with data structures that aren’t static. By pairing apex_data_export with apex_exec, you eliminate the maintenance headache of versioning static spreadsheets and give users templates that consistently reflect the current configuration; columns, attributes, sample values, instructions, everything.

I have been using AI to help me build APEX Apps for more than a year, and the pace of change during that time has been amazing. In this post I will review the tools and workflows that that have helped me to improve as an APEX Developer.

I won’t be getting into how to set up these tools, just how I use them.

AI Subscriptions

I currently have the following AI Subscriptions:

• Open AI Chat GPT Business ($300/year)

  • I use this subscription for ChatGPT, APIs, and Codex

• GitHub Co-Pilot Pro ($100/year)

AI Tools

These are the AI tools I am using today:

Auto-Complete / Ghost Text

I estimate that Ghost Text accounts for about 50% of my overall productivity gains with AI. This is the feature where the AI predicts your next step based on the surrounding code and provides a suggestion you can accept with the Tab key. It is especially useful for repetitive tasks, such as:

• Writing MERGE and INSERT INTO statements. The AI leverages the schema and table structure currently open in the IDE (e.g., the columns and data types) to accurately auto-complete the statement after just a few initial lines.

• Automatically adding comments and apex_debug entries.

• Autocompleting the EXCEPTION WHEN OTHERS block of a procedure or function.

• Applying a required change across multiple related code blocks.

Here is a short video showing me creating a new procedure.

Code Reviews

I use AI to do three different kinds of code reviews (of my own work):

• End of Day Review of all changes made during the day

• Ad-Hoc review of a PL/SQL package

• Full Code Review

End of Day Review

At the end of every day, I like to run an automated code review of the changes I made that day. The Codex CLI makes this easy with the /review command.

Change to the root folder of the GitHub repository and start Codex, then type /review

Then choose what kind of review you want to do; option 2 is what I do.

Codex will then compare the last committed version with the changes and perform a review.

Ad-Hoc Review (PL/SQL Package)

Every so often, I like to do a complete review of a package. I use the Codex CLI for this so that I can run it in the background. The key here is to develop a prompt that reviews the code the way you would like it reviewed.

Here is the prompt I currently use:

# Code Review Objective
Perform a code review for the following files:
- `PLSQL/XXFN_RFQ_UTL_PKB.sql`
- `PLSQL/XXFN_RFQ_UTL_PKS.sql`

Begin with a concise checklist (3-7 bullets) of the sub-tasks required to complete this review; keep items conceptual, not implementation-level.
# Tasks
Review each file for:
- Logic errors
- Unused variables
- Lack of code reuse
- Security Concerns
- Poorly performing code

For each identified issue, state your assumptions and verify the potential impact before assigning severity.
# Output Instructions
- Document all findings in `RFQ_CODE_REVIEW.md`.
- Use a Markdown table with the columns:
    - **File**
    - **Line(s)**
    - **Issue Type**
    - **Description**
    - **Severity** (Low/Medium/High)
    - **Suggested Fix**
- Group issues by file and list findings sequentially within each file.
- If a file has no issues, include a row stating "No issues found" in the **Description** column, leaving the other columns blank for that row.
- Assign **Severity** based on the potential impact of the issue; if uncertain about severity or affected lines, specify your assumption and reasoning.
- For each finding, specify the affected line(s) precisely. For multi-line or file-wide issues, indicate the corresponding range or "entire file" as needed.

After reviewing and documenting, validate that all findings are clearly described and all required fields are filled in; if any instructions are ambiguous or criteria unmet, highlight them at the end of the output for clarification.

Complete Code Review

I run a code review of the complete codebase about once a week. Once again, I turn to the Codex CLI to run this so I can work on something else while it runs.

Here is the prompt I currently use:

You are acting as a senior Oracle APEX / PL/SQL architect and code reviewer.

Context:
- The repository contains one or more Oracle APEX applications, shared components, PL/SQL packages, functions, procedures, triggers, views, and other database objects.
- Assume it is used in a production or near-production environment.
- Focus heavily on correctness, security, performance, maintainability, and APEX best practices.

Your task:
Perform a **comprehensive code review** of the entire repo (APEX export files, PL/SQL packages, views, triggers, utility scripts, etc.) and then produce a **single Markdown report** as your only output.

General review focus:
1. **Correctness & robustness**
   - Logic errors, edge cases, null/empty handling, and error handling.
   - Transaction handling and commit/rollback discipline.
   - Concurrency issues (locks, race conditions, serialization).
2. **Security**
   - SQL injection risks (dynamic SQL, concatenated where clauses, using NVL with parameters, etc.).
   - XSS / output escaping issues in APEX (unescaped substitutions, htp.p/owa_util.showpage usage, missing server-side validation).
   - Session and authorization handling (APEX authorization schemes, access control logic).
   - Sensitive data handling (logging PII, passwords, tokens, or secrets).
   - Use of APEX substitution strings, bind variables, and item values in queries and PL/SQL.
3. **Performance & scalability**
   - N+1 query patterns, repeated queries in loops.
   - Missing or misused indexes, non-selective predicates, full table scans where dangerous.
   - Inefficient PL/SQL patterns (unnecessary row-by-row processing, missing BULK COLLECT / FORALL where appropriate).
   - Heavy computations in views vs. materialized views or caching strategies.
   - APEX-specific performance concerns (expensive queries in report regions, interactive report/grid filters, LOVs with slow queries).
4. **APEX application design**
   - Page process and branch logic clarity.
   - Proper use of shared components (lists, LOVs, templates, authorization schemes).
   - Hard-coded values vs. configuration tables/application items.
   - Use of APEX APIs (APEX_APPLICATION, APEX_UTIL, APEX_PAGE, APEX_SESSION, APEX_DEBUG, etc.) and any risky or deprecated calls.
5. **Code quality & maintainability**
   - Naming conventions for packages, procedures, variables, constants, and views.
   - Comment quality and accuracy (misleading or outdated comments).
   - Module boundaries and cohesion (what should be refactored into separate packages).
   - Reusability and DRY violations (duplicate logic that should be centralized).
   - Error logging and instrumentation (APEX debug, custom logging tables, structured error messages).
6. **Database design & views**
   - View complexity and readability.
   - Security of views (exposing too much data, missing filters, relying on client-side filters).
   - Use of synonyms, grants, and schema separation.

Output requirements:
- Only output a single Markdown document called CodeReview.md
- No explanation or actions outside of the Markdown.
- Structure the report so that issues are easy to scan and the related code is easy to find.

Markdown structure:
1. # APEX Repo Code Review
   - Short overview of the overall health of the codebase.
   - 2–3 key strengths.
   - 3–5 top-priority concerns.

2. ## Summary by Severity
   - A bullet list showing counts:
     - `Severe issues: N`
     - `Moderate issues: N`
     - `Low issues: N`

3. ## Detailed Findings
   - Group by logical area, for example:
     - `### PL/SQL Packages`
     - `### APEX Pages & Processes`
     - `### Views & SQL`
     - `### Security`
     - `### Performance`
   - Under each area, list issues as subsections:

   Example structure for each issue:
   #### [Severity] Short issue title
   - **Severity:** Severe | Moderate | Low
   - **Location:** `path/to/file` (and object name, page number, or line range if available)
   - **Description:**
     - Clear explanation of what is wrong and why it matters.
   - **Impact:**
     - Security / correctness / performance / maintainability impact in 1–3 lines.
   - **Recommendation:**
     - Specific and actionable guidance on how to fix it.
   - **Code snippet (before):**
     - Show only the relevant lines, minimal but sufficient context
   - **Suggested fix (after or pseudo-code):**
     - Show improved version or a clear pseudo-code template

4. ## Pattern-Level Recommendations
    - Describe any recurring patterns that should be globally fixed (e.g., unsafe dynamic SQL patterns, repeated logic for auditing, repeated branching logic in APEX).
    - Provide 2 to 5 concrete "refactoring themes" that would significantly improve the codebase.

5. ## APEX-Specific Recommendations
    - Suggestions for:
        - Better use of shared components.
        - Improved authorization and authentication handling.
        - Performance tuning for heavy pages, reports, and LOVs.
        - Hardening against XSS and misuse of substitution strings.
6. ## Quick-Win Checklist
    - A concise bullet list of the most important fixes (in priority order) that the team should implement next.

Severity rubric:
Use the following rubric consistently:
- **Severe:**
    - Can cause data corruption, security vulnerabilities, major logical errors, or severe performance degradation in realistic conditions.
- **Moderate:**
    - Risky or inefficient patterns that can cause noticeable issues under load or over time, but not immediately catastrophic.
- **Low:**
    - Style, readability, minor performance improvements, or best-practice alignment that helps maintainability but is not urgent.

Additional rules:
- Prefer **precision over volume**: do not list 100 trivial issues; focus on the most impactful ones, while still giving enough detail to be useful.
- When in doubt, **show code**: include short but focused code snippets in fenced blocks so developers can quickly locate and fix the problem.
- If something looks dangerous but you are not fully sure (based on the visible context), call it out as a **potential issue** and clearly say what assumptions you are making.

Now, perform this review and output only the Markdown report described above.

Oracle SQLcl MCP Server

Please see this post for more on how I use the Oracle SQLcl MCP Server.

Writing New Code

You will have noticed that, so far, I have not discussed writing brand-new code based solely on a prompt. This is where I start to get nervous about AI.

Lately, I have started having AI write individual PL/SQL functions and procedures. I have noticed a significant improvement here with the latest models (OpenAI 5.1). I see even better results when I am adding procedures and functions to existing packages. I am sure this is because the additional context helps AI write better code.

This, along with writing SQL statements (using the MCP server), is the sweet spot when it comes to generating new code with AI.

What About APEX

At the moment (before the release of APEX 25.2, 26.1), AI is quite capable of reviewing and providing feedback on APEX Apps. This can be done via SQL using the SQLcl MCP server (and the right prompts), or based on AI extracting information from an APEX export file.

When I run the code reviews (mentioned above), AI checks the exported APEX Apps, and I get just as many findings from APEX as from PL/SQL.

I find AI especially useful for:

• Checking APEX security settings (SSP, Authorization Schemes Applied to Buttons, etc.).

• Building custom UI Components (e.g., template components).

APEX AI Wizard

APEX 24.2 does have a Wizard that allows you to create basic Apps from a prompt (and or a spreadsheet). This is OK for one-off Apps, but I don’t think it is the long-term answer for building APEX Apps with AI (nor does Oracle).

APEXlang

APEXlang will be the future of building APEX Apps with AI. It is not out yet, but I saw a demo at this year’s Oracle AI World, and it looks very promising. Having a formal syntax (that an AI can learn) will unlock the ability to build brand new Apps and perform major refactors on your APEX Apps.

AI Controlled Browsers

When ChatGPT Atlas was released, I immediately logged into my https://oracleapex.com/ords instance and asked AI to write an App to track the service history for my car. I was pretty impressed, it used QuickSQL to generate a data model and then built a fully functional App (albeit relatively simple).

I think the future of AI-controlled browsers and APEX lies in automated testing. You can turn your test scripts into prompts and have the browser run them. Google’s AntiGravity IDE takes this a step further and can capture screenshots of the testing along the way.

How do I?

The final use of AI for me is asking ad hoc questions. I work for myself, so I don’t have colleagues to ask questions of around the watercooler.

AGENTS.MD

I encourage you to spend an afternoon (or two) developing a robust AGENTS.md file for each of your code repositories. AGENTS.md gives you the ability to tell the AI what your naming conventions are, how you like to structure SQL statements, and general guidelines for how you want it to behave when generating code. Without it, it relies on your existing code base, and you will often end up spending as much time formatting your code as the time the AI saves you to start with.

I am not sure if AGENTS.md will become the de facto standard, but it is a better alternative than having AI coding agents use their own files to instruct the AI (.github/copilot-instructions.md, cursor.json, etc).

Warning!

There are a few things that I think you must keep in mind when using AI to help you code:

• AI is a Tool, not a Crutch - There is no substitute for knowing what the code is supposed to look like. We all write the odd JavaScript snippet using AI without really understanding the output, but this should not be the default. If you are building code and getting paid for it, you'd better understand what it does!

• Never Leave Security Entirely Up to AI - I mentioned above that AI does a good job of checking security settings in APEX. Even though it does, I always manually check security settings at the end of a project (using my own SQL statements or tools like APEX-SERT, ApexSec, or APEX Project Eye).

• AI is Making me Dumber - There is no doubt in my mind that AI is making me dumber. When you rely on any tool for a period of time, your body adapts. When you buy a snow blower, the muscles you had from shoveling snow atrophy. The same can be said of AI. Does it really matter as long as you are getting the job done? It wasn’t a big deal when we adopted the calculator over mental math, but this may be different. Only time will tell.

AI Overload/Fatigue

Phillipp Hartenfeller recently posted the below comment in a LinkedIn thread, which really struck a chord with me.

I realized that I, too, am about 20% more efficient with AI than without. This productivity improvement, however, is both a blessing and a curse. I am now able to work on more projects at the same time, which means dealing with more people, more project constraints, more meetings, etc. There is also increased context switching (not just between projects, but also between my coding and checking the code that the AI is generating for me). This leaves aside the time it takes to learn and keep up with the latest AI developments.

Conclusion

Much is being said about the hype surrounding AI and the AI bubble. For developers, however, I believe the promise/threat (depending on which way you look at it) of AI is real. I see AI as an adapt or die situation for programmers. Having said that, we are still IT professionals, and it is incumbent on us to use AI professionally.

In a few months, most of this article will be out of date (not least because APEX 26.1 will likely have been released along with APEXlang).

With so many emerging technologies inside and outside the Oracle database ecosystem, it might seem trivial, even old-fashioned, to talk about database views in APEX.

A recent project reminded me of the importance of getting the basics right, so I thought I would share this insight in a brief post.

Use Case

Recently, a project reminded me why views are still critical. I was building an inventory count application with three core tables: items, count_sheets, and item_categories. Several pages in the APEX app displayed similar data combinations, initial count, verified count, administrative adjustments, and extended values.

Here’s a simplified version of one of those queries:

SELECT ctgy.category_name
,      ctlg.part_number
,      ctlg.part_description
,      ctlg.uom
,      ctlg.price
,      ROUND(ctlg.price / NULLIF(ctlg.qty_conversion, 0), 2) AS unit_price
,      csh.counter_count                                     AS counter_count
,      csh.reconcile_count                                   AS reconcile_count
,      csh.adjustment_count                                  AS adjustment_count
,      COALESCE(csh.adjustment_count, 
                csh.reconcile_count, 
                csh.counter_count)                           AS final_count
FROM   inv_count_sheet csh
,      inv_catalog     ctlg
,      inv_category    ctgy
WHERE  csh.item_id      = ctlg.item_id
AND    ctlg.category_id = ctgy.category_id;

There is nothing overly complicated about the SQL. If I use it in the four or five pages, you may not think it is a big deal to replicate the SQL.

💡 What if the calculation for final_count needs to change?

If you’ve repeated this SQL across several APEX pages, even a small change means hunting down and updating each instance, then testing every affected page.

By encapsulating the query in a database view, that same change takes seconds to apply and test.

Of course, this approach is not a panacea. If I needed to add columns or remove columns, I still need to make some code changes. Also, be mindful of performance implications. While views simplify code maintenance, they can sometimes hide expensive joins or aggregations.

Other Benefits

Re-use and encapsulation of complex logic is the primary benefit of using views, but there are others:

• Elegant APEX Apps - Instead of embedding complex joins or aggregations in multiple APEX pages, you define them once in a view. This centralized logic makes your APEX pages much simpler and easier to maintain.

• Security - You can limit the scope of views and expose the views instead of the underlying tables to consumers. When combined with APEX_SESSION.SET_TENANT_ID, and SYS_CONTEXT('APEX$SESSION', 'APP_TENANT_ID'), you can use views to limit access in Multi-Tenant Applications.

• Consistent Data Model for APEX Components - Interactive grids, reports, and charts all query the same logical layer. This ensures uniform results across the application and reduces data inconsistency issues.

• Reusability Across Consumers - The same view can serve multiple APEX apps, RESTful services, AOP Reports, and Document Generator Reports, promoting modular design and avoiding duplicated SQL definitions.

SQL Macros

For even more flexibility, Oracle provides SQL Macros (introduced in Oracle Database 19c). SQL Macros let you encapsulate reusable SQL logic, either as scalar or table macros, that expand at parse time. Unlike static views, they can accept parameters. This makes them a powerful complement to traditional views when you need more adaptable query definitions.

In the table SQL Macro example below, I can pass in the Business Unit ID (p_bu_id) as a paremeter:

CREATE OR REPLACE FUNCTION example_sql_macro (p_bu_id IN NUMBER) RETURN CLOB SQL_MACRO AS
BEGIN
  RETURN q'{
SELECT ctgy.category_name
,      ctlg.part_number
FROM   inv_count_sheet csh
,      inv_catalog     ctlg
,      inv_category    ctgy
WHERE  csh.item_id      = ctlg.item_id
AND    ctlg.category_id = ctgy.category_id
AND    csh.bu_id        = p_bu_id
  }';
END example_sql_macro;

You use table SQL Macros in a SELECT statement just like a regular view:

SELECT *
FROM   example_sql_macro (p_bu_id => 1);

Parameters are substituted at parse time, and then the SQL is executed.

Conclusion

This post is a reminder to myself and others that views are an essential part of thoughtful APEX Application Development. Even though there are plenty of shiny new tech tools out there, there is no excuse not to do the basics right.

This is a quick post to show you how to display different-colored icons in the nodes of an APEX Tree Region. This is one of those things that should be easier than it is!

Goal

I am building an App to maintain corporate hierarchies. These could be cost center hierarchies, job hierarchies, etc. A key piece of functionality is the ability to upload changes to the hierarchies via Excel and provide a Diff between the original hierarchy and the newly uploaded hierarchy. The diff should show:

• Added Nodes (node added to the hierarchy)

• Removed Nodes (node removed from the hierarchy)

• Moved Nodes (node moved from one parent to another)

The UI needs to show changes in the hierarchy and clearly distinguish between the above changes.

The Solution Part 1

Clearly, an APEX Tree region would be a great choice to illustrate changes to the hierarchy. Using the Oracle CONNECT BY clause, we can construct a hierarchical query that compares the hierarchy in the main table to the hierarchy being uploaded. We will skip the diff logic, but you can see the SQL here if you are interested.

In APEX, we set up a Tree Region and reference the columns in the outer SQL:

We end up with something like this:

This looks great, but for larger hierarchies, it will be challenging for users to spot changes to the newly uploaded hierarchy.

Ideally, we could do something like this in the CASE statement, which determines the icon:

  ,      CASE status
           WHEN 'Added'   THEN 'fa-plus-circle u-success-text'
           WHEN 'Removed' THEN 'fa-times-circle u-danger-text'
           WHEN 'Moved'   THEN 'fa-arrows-alt u-info-text'
           WHEN 'Changed' THEN 'fa-exchange u-info-text'
           ELSE 'fa-circle-o'
         END AS icon_css

• The icon_css column above is referenced in the APEX Tree Region Attribute called ‘Icon CSS Class Column’. Navigation: Tree → Attributes → Appearance → Icon CSS Class Column.

Unfortunately, this does not work. If we inspect the HTML and CSS in the page, we can see why:

• Even though we see the u-success-text class that we added, APEX is using a CSS variable --a-treeview-node-icon-color to determine the icon color. We could, of course, override that color, but the override would apply to all nodes, and we are back where we started.

The Solution Part 2

Ideally, APEX would allow you to pass your own color class in the SQL like this:

  ,      CASE status
           WHEN 'Added'   THEN 'fa-plus-circle icon-green'
           WHEN 'Removed' THEN 'fa-times-circle icon-red'
           WHEN 'Moved'   THEN 'fa-arrows-alt icon-blue'
           WHEN 'Changed' THEN 'fa-exchange icon-blue'
           ELSE 'fa-circle-o icon-grey'
         END AS icon_css

On the page level, Inline CSS, we would style the above color class.

Unfortunately, this does not work either, as the APEX class overrides ours.

The Solution - Part 3

We can work with APEX and set the --a-treeview-node-icon-color CSS variables based on our own custom CSS classes. Add the following to the page level Inline CSS attribute. Page → CSS → Inline (or Theme → Custom CSS if you want it app-wide).

.a-TreeView .fa.icon-green,
.a-TreeView .a-Icon.icon-green,
.a-TreeView .t-Icon.icon-green { --a-treeview-node-icon-color: var(--ut-palette-success); }

.a-TreeView .fa.icon-red,
.a-TreeView .a-Icon.icon-red,
.a-TreeView .t-Icon.icon-red { --a-treeview-node-icon-color: var(--ut-palette-danger); }

.a-TreeView .fa.icon-blue,
.a-TreeView .a-Icon.icon-blue,
.a-TreeView .t-Icon.icon-blue { --a-treeview-node-icon-color: var(--ut-palette-info); }

.a-TreeView .fa.icon-grey,
.a-TreeView .a-Icon.icon-grey,
.a-TreeView .t-Icon.icon-grey { --a-treeview-node-icon-color: var(--u-color-29);}

Add the custom CSS classes icon-grey, icon-blue, icon-green, and icon-red to our SQL, along with the icon classes.

,      CASE status
           WHEN 'Added'   THEN 'fa-plus-circle icon-green'
           WHEN 'Removed' THEN 'fa-times-circle icon-red'
           WHEN 'Moved'   THEN 'fa-arrows-alt icon-blue'
           WHEN 'Changed' THEN 'fa-exchange icon-blue'
           ELSE 'fa-circle-o icon-grey'
         END AS icon_css

If we take a look at the HTML and CSS generated in the page now, we can see the UT u-success-green color class has been used in the --a-treeview-node-icon-color CSS variable for the specific node.

The result is colorized node icons, which make it easier to see what is being added, removed, or moved:

Conclusion

I could have written this post with just the solution, but I thought it would be useful to see my thought process in solving this problem.

📣 Call to Action

I have created an Idea in the APEX Ideas App, suggesting it would be easier to pass a color class along with the icon class. Unfortunately, the idea has been closed 😞

I have been using GitHub Copilot with Oracle’s SQLcl MCP server since its release in July 2025. The combination of Generative AI and databases is a powerful pairing that can help APEX developers build better products in less time. This statement comes with some caveats, which I will cover in this post.

In this post, I will describe how to set up the SQLcl MCP server in SQL Developer for VS Code, utilizing both OpenAI’s Codex and GitHub Copilot. I will also review several use cases and provide example prompts, which will help you get more out of this technology.

Configuring the SQLcl MCP Server

First, you will need to install the latest version of the SQL Developer Extension for VS Code and the latest version of SQLcl on your machine. You will also need to know the path to your SQLcl install.

In the following sections, I will describe how to set up Codex and GitHub Copilot to utilize the SQLcl MCP Server. Which tool to use is up to you. I currently use both, but am leaning toward Codex as my go-to development assistant.

Configuring GitHub Copilot

See the ‘Appendix 1 - Configure & Test GitHub Copilot with SQLcl MCP Server’ for details on how to set up and test the SQLcl MCP Server with VS Code.

Configuring OpenAI Codex

Install the OpenAI Codex Extension for VS Code

• Install the Codex Extension for VS Code.

• Log in to your OpenAI / ChatGPT account

  • Open the Codex extension > Click the settings gear icon > Log in

Configure Codex to use the SQLcl MCP Server

• Open the Codex extension > Click ⚙️ > MCP Settings > Open config.toml

• Once the file opens, copy and paste the below text into it (adjust your SQLcl path accordingly).

[mcp_servers.sqlcl]
command = "/opt/homebrew/Caskroom/sqlcl/25.3.0.274.1210/sqlcl/bin/sql"
args = ["-mcp"]
startup_timeout_ms = 60000

Testing the Setup

For the rest of this post, I will be using a saved connection called ‘DEMO’ in SQLDeveloper for VS Code:

Test from Codex with VS Code

Open the Codex Extension and type the following in the chat Window:

Once connected, ask:

You should end up with something like this:

Test from the Codex CLI

The SQLcl MCP Server also works with the OpenAI Codex CLI.

How it Works

Before reviewing the examples, it’s important to understand how the SQLcl MCP Server interacts with the Large Language Model (LLM).

When you type a prompt in Copilot Chat or Codex, VS Code sends that prompt, along with prior context and a list of available tools, to the LLM. One of those tools can be the SQLcl MCP Server.

The LLM analyzes the prompt and determines whether SQLcl is the appropriate tool to assist in fulfilling the request. If it is, the LLM instructs VS Code to run a command through SQLcl and return the output. The LLM then uses that output to decide the next step, continuing this exchange until the request is resolved.

AGENTS.md

Adding a file called AGENTS.md to the root of your GitHub repositories allows you to pass on guidelines to the LLM. Both Codex and GitHub Copilot recognize this file. You can include details such as:

• APEX and DB Versions

• Folder Structures of your Repo

• Coding Standards and Conventions

• Formatting Rules

• Agent behaviors and guidelines (don’t drop my tables)

SQLcl MCP Use Cases

Now that we are set up, it’s time to go through some use cases. I think this is the best way to understand why the SQLcl MCP server is so helpful.

Create a Query

Let’s start by having the MCP Server create a query for us to use.

Result:

SELECT so.order_number
     , so.order_date
     , so.total_amount         AS order_total
     , so.status               AS order_status
     , c.name                  AS customer_name
     , c.email                 AS customer_email
     , sol.line_number
     , sol.quantity
     , sol.unit_price
     , sol.line_total
     , p.sku
     , p.name                  AS product_name
FROM   sales_orders       so
     , customers          c
     , sales_order_lines  sol
     , products           p
WHERE  so.customer_id    = c.customer_id
AND    sol.order_id      = so.order_id
AND    sol.product_id    = p.product_id;

• The first thing you may notice is that the SQL is formatted. This is because of the formatting instructions in the AGENTS.md file. It also uses the old Oracle SQL syntax, again, because this is in my AGENTS.md (and because I am old 👴).

• The LLM requested details of the tables in the database, SQLcl provided them, and the LLM generated the query. It correctly identified the tables based on my prompt, even though I did not use exact table names.

Tune the Query

Now that we have a query, let’s tune it for optimal performance when we want to view orders with an order date within the past month.

Here is an excerpt from the LLM’s “model reasoning trace” and its back and forth with SQLcl:

Here is the final response from the LLM:

Tuning Results

• Captured the original plan: full scans on SALES_ORDERS and SALES_ORDER_LINES, cost 12 (plan hash 1363380163), so the date filter wasn’t selective without supporting indexes.

• Added index sales_orders_ord_dt_idx on (order_date, order_id) to allow the optimizer to apply the last-month filter via an index range scan.

• Added index sales_order_lines_ord_idx on (order_id, product_id) so line lookups now use range scans instead of scanning the entire detail table.

• Regathered stats on both tables (DBMS_STATS.GATHER_TABLE_STATS) to make the new access paths visible to the optimizer.

• New plan hash 1931885458: both SALES_ORDERS and SALES_ORDER_LINES now use index range scans with batched rowid lookups; plan cost dropped to 9, and the query no longer performs storage full scans.

• Executed the tuned SQL (ANSI JOIN form) and confirmed it returns no rows for the past month in this sample dataset, indicating the plan runs without error.

Next Steps

1. Validate the change against production-scale volumes (SQL Monitor/ASH) to quantify real runtime gains.

2. Keep table stats current after large data loads so the optimizer continues to choose the new indexes.

Combining Context from Your DB and Your Codebase

Sometimes it is helpful to ask questions about your codebase in GitHub and what is actually in your database.

I have a folder open in VS Code with a GitHub Repo:

Now, I can ask questions that span the DB and my file system.

Here is an excerpt from the “model reasoning trace”:

Here is the Response:

Connected to the DEMO database via SQLcl and cross-referenced every SQL/PL/SQL source in the repo. The query select distinct table_name from all_tables where table_name in (...) returned twelve matches, and each has live references in the codebase:

GenAI Schema Tables

• GEN_AI_CONFIGS – defined in cn_utils/ai/TABLES/GEN_AI_CONFIGS_CRTB.sql:1, used in cn_utils/ai/PLSQL/GEN_AI_UTL_PKB.sql:18.

• GEN_AI_LOGS – defined in cn_utils/ai/TABLES/GEN_AI_LOGS_CRTB.sql:2, logged through cn_utils/ai/PLSQL/GEN_AI_UTL_PKB.sql:8.

• GEN_AI_TOOLS – created in cn_utils/ai/TABLES/GEN_AI_TOOLS_CRTB.sql:1, referenced by cn_utils/ai/PLSQL/GEN_AI_TOOLS_UTL_PKB.sql:1.

• GEN_AI_TOOL_PARAMS – documented in cn_utils/ai/TABLES/GEN_AI_TOOL_PARAMS_CRTB.sql:1, queried in cn_utils/ai/PLSQL/GEN_AI_TOOLS_UTL_PKB.sql:66.

• SALES_ORDERS – DDL/comments in cn_utils/ai/SELECTAI/SELECT_AI_DEMO.sql:19, accessed in cn_utils/ai/PLSQL/GEN_AI_EXAMPLE_TOOLS_PKB.sql:26.

• CUSTOMERS – table metadata in cn_utils/ai/SELECTAI/SELECT_AI_DEMO.sql:28, queried in conference_material/KSCOPE25/Built with LOV Using APEX/f777.sql:7176.

Content & Reference Tables

• CNBA_BLOG_POSTS – synchronized in cn_utils/ai_demo_app/APEX/f110.sql:334, selected in cn_utils/ai_demo_app/PLSQL/CN_AI_UTL_PKB.sql:36.

• CNBA_POST_CHUNKS – inserted in cn_utils/ai_demo_app/APEX/f110.sql:2765, joined in cn_utils/ai_demo_app/PLSQL/CN_AI_UTL_PKB.sql:88.

• CN_DOCUMENTS – queried in cn_utils/ai_demo_app/APEX/f110.sql:1580, retrieved in cn_utils/ai_demo_app/PLSQL/CN_AI_UTL_PKB.sql:176.

• CN_DOCUMENT_CHUNKS – read in cn_utils/ai_demo_app/APEX/f110.sql:3860, maintained in cn_utils/ai_demo_app/PLSQL/CN_AI_UTL_PKB.sql:252.

• PRODUCTS – LOV definition in cn_utils/ai_demo_app/APEX/f110.sql:1572, included in cn_utils/ai/SELECTAI/SELECT_AI_DEMO.sql:10.

• COUNTRIES – created in conference_material/KSCOPE25/Built with LOV Using APEX/countries.sql:2, queried in conference_material/KSCOPE25/Built with LOV Using APEX/f777.sql:2462.

Other names appeared in the source scan but are not tables in the DEMO schema (e.g., views like CNDEMO_ADDRESSES_V or package calls such as TABLE_FN_PK.EVS_SOLD_BY_YEAR). Let me know if you want to repeat the check against another connection or extend it to views/synonyms.

Full Agent Mode

Q&A questions are great, but can we create code in the DB? Let’s try!

Notice the table names are not quite right. I have orders instead of sales_orders and order_lines instead of sales_order_lines.

Here is an excerpt from the “model reasoning trace”:

Here is the response:

Created table APIs for customers, orders, order lines, and products in DEMO so each table now has consistent insert/update/delete/fetch routines with APEX debug logging and error propagation.

• AIDEMO_CUSTOMERS_PK uses customers%ROWTYPE for CRUD, returning generated IDs and logging apex_debug.error on failure.

• AIDEMO_PRODUCTS_PK mirrors the same pattern for PRODUCTS, defaulting created_at to SYSDATE when absent.

• AIDEMO_ORDERS_PK targets SALES_ORDERS (no plain ORDERS object exists) and fills defaults for order_date, total_amount, and status during inserts.

• AIDEMO_ORDER_LINES_PK targets SALES_ORDER_LINES, recalculating line_total when not provided.

• Verified all specs/bodies compile cleanly (USER_OBJECTS shows each package and body VALID).

Next steps:

1. Exercise the new TAPIs from your APEX flows or unit harness to confirm business logic/defaults behave as expected.

2. If you need deployment artifacts, export these CREATE OR REPLACE statements into your /SCRIPTS folder for source control.

It figured out the correct tables and created a create/update/delete package for each table:

A few notes:

• It included the apex_debug call in the WHEN OTHERS exception, which I had specified in my AGENTS.md

What about APEX?

Because APEX lives in the database, it is an obvious candidate for interrogation by LLMs.

Example response (not my apps 😊):

• Application 103 has 45 pages where PAGE_ACCESS_PROTECTION = 'Unrestricted' (apex_application_pages), leaving session state open to tampering; switch these pages to checksum-protected or require re-authentication. 🫢

• Browser caching remains enabled for application 103 (BROWSER_CACHE = 'Enabled'), risking sensitive data leakage on shared machines; disable caching for authenticated apps.

Example response (again, not my apps 😊):

• apex_release.version_no reports 24.2.9 as the current APEX version; four applications (100, 101, 102, 110) already use compatibility_mode = '24.2' and Universal Theme 24.2 (apex_application_themes).

• Application 103 is still on compatibility_mode = '4.2' 🫢 (apex_applications), so its runtime features are constrained to an obsolete APEX release.

• The same application 103 runs Universal Theme version 1.2 with file_prefix = '#IMAGE_PREFIX#themes/theme_42/1.2/' (apex_application_themes), which predates the current 24.2 delivery.

Other Prompts

• Identify tables in the DEMO schema that are missing foreign keys. Add each missing foreign key to a script called MISSING_FOREIGN_KEYS.sql for my review.

  • Not only did the LLM do a good job of identifying missing foreign keys and creating the respective ALTER TABLE scripts, but it also identified orphaned records in one table!

• Review database objects in the DEMO schema and files in my codebase to identify unused tables. Create a script called POTENTIAL_TABLE_DROPS.sql with DROP statements for each. Do not execute the drop statements.

• Look at SQL queries that have run in the DEMO schema and list the top three poorly performing SQL statements. You may need to run this as a privileged user.

• You are an expert technical author with specialist knowledge in Oracle APEX, Oracle Database, PL/SQL, and SQL. You have been assigned to the ‘XYZ project’. The goal of the project is to migrate from a legacy APEX version to the latest version (24.2) while enhancing security and adding the required business functionality. Connect to the 'XYZ' connection using the sqlcl mcp server. Review all of the database objects and APEX applications in the ‘XYX’ schema. Your goal is to create high-quality, easy-to-read, and concise technical documentation for the support team that will take over support for the application. Create a document called TECHICAL_DESIGN.md in the DOCS folder.

Other Considerations

• Ensure the LLM and SQLcl are connected to the correct instance and schema. This is especially important if, like me, you have numerous saved database connections in SQL Developer. Because the LLM is deciding what command to run in SQLcl, it can easily pick the wrong connection. It helps to have clear connection names that differ between clients and instances, e.g., ABCCORP-DEV and CLOUDNUEVA-DEV, as opposed to DEV1 and DEV2.

• I recommend creating a read-only schema in non-development instances.

• For complex questions, the number of iterations between the LLM and SQLcl can be large. Some questions can take multiple minutes to answer and require a significant number of tokens. 💲

• I find it interesting to review both the plan that the LLM generates at the start of the process and the “model reasoning trace” it emits as it goes through the process of answering your question. This helps me to build better prompts.

• As models evolve (GPT3 > GPT4 > GPT5), the prompts you enter today may not yield the same results tomorrow. As with any AI technology, it is important to build a list of Evals that you can use to test new models and prompts against results from previous iterations.

• If you do not already, add rich and informative table and column comments. I laid out why this is important in my post about SELECT AI.

Conclusion

In the end, the SQLcl MCP server isn’t magic 🪄; it’s just a bridge between your database and an LLM. It saves time, reduces context switching, and helps you think through SQL and APEX problems more efficiently. It won’t replace your judgment or stop you from making a bad call, but it can make routine work faster and more consistent.

Appendix 1 - Configure & Test GitHub Copilot with SQLcl MCP Server

Here is a guide to get started with GitHub Copilot in VS Code.

Install GitHub Copilot Extensions for VS Code

• Install the GitHub Copilot and GitHub Copilot Chat Extensions

• Log in using your GitHub account

Configure Copilot to use the SQLcl MCP Server

• Open the VS Code Command Palette.

• Type MCP to see the MCP Options

• Select MCP: Add Server

• Select Command (stdio)

• Enter a name for the MCP Server

• Select which scope you want it to run in:

• You should now see the mcp.json file

• Now that the SQLcl MCP Server is installed, you can start/stop/restart it by opening the menu and selecting > MCP: List Servers

• Then select SQLcl

• Select ‘Start Server’ to start the MCP Server. The same navigation will allow you to stop an already running MCP Server.

• Click ‘Show Output’ to see a log of what it is doing.

Note: VS Code will start the SQLcl MCP Server for you if it is not already started.

Test from VS Code

Open the CoPilot Chat Extension and type the following in the chat Window:

Connect to DEMO using the SQLcl MCP Server

Oracle APEX Web Credentials supports many standard REST API authentication schemes. However, not all APIs play nicely - some use custom or unsupported authentication flows.

When that happens, securing and reusing credentials becomes harder. You lose the built-in power of APEX Web Credentials and the ability to use features like REST Data Sources.

Goals

• Built a reusable and secure authentication solution for non-standard APIs

• Leveraged Oracle TDE and Data Redaction for at-rest and at-access credential protection

• Enabled native APEX Web Credential reuse through persistent token injection

Use Case

I am working on a project to extract Quote information from servicePath. servicePath is a SaaS based Configure, Price, Quote solution (CPQ) focused on technology sales.

The servicePath REST APIs use an HTTP Header Bearer token for Authentication. A token can be obtained from the Generate Access Token endpoint. Here is where the fun starts!

Getting a servicePath Access Token

The servicePath token service requires that you send a username and password in the body of a POST request:

After calling the token service, you receive a Bearer token (access token) in a JSON response:

{
  "Bearer": "eyJhbG...", 
  "Refresh": "I4-8Cun..."
}

The Bearer (access token) is used in the ‘Authorization’ HTTP Header variable to authenticate when calling servicePath APIs:

curl --location 'https://example.servicepath.io/api/v3/Quotes?page_size=500&last_modified_from=2025-04-23' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbG...'

The servicePath approach rules out using an APEX Web Credential in the classical sense. But all is not lost; we can still use APEX Web Credentials and benefit from REST Data Sources, etc. Read on to find out how.

Approach

This diagram illustrates the idea I am trying to convey in this post. We use custom code to get and refresh the Bearer token, then store it persistently in an HTTP Header type APEX Web Credential to be available to other APEX sessions.

Storing Credentials Securely

As we cannot use APEX Web Credentials, we must first find a secure way to store the API credentials (in this case, a username and password).

The approach described in this section is much more straightforward and sufficiently secure for most use cases. It relies on Oracle Transparent Data Encryption (TDE) to secure the data at rest, and Oracle Data Redaction to keep the credentials secure from access via SQL. This approach works seamlessly on OCI Autonomous Databases or on the OCI APEX Service, which uses TDE on all tablespaces without any setup required on your part.

Step 1: Create a New Schema

-- For OCI ATP, run as ADMIN
-- Having a separate schema separates securing the API keys from your APEX Parsing Schema.
CREATE USER api_sec
  IDENTIFIED BY "ComplexPassword"
  QUOTA 10M ON users
  DEFAULT TABLESPACE users
  TEMPORARY TABLESPACE temp
  PROFILE default;

-- Create Limited Grants to the new user
GRANT CREATE SESSION                 TO api_sec;
GRANT CREATE TABLE, CREATE PROCEDURE TO api_sec;
ALTER USER api_sec DEFAULT ROLE NONE;

Step 2: Create the Credentials Table in the New Schema

-- Run as user api_sec or admin
CREATE TABLE api_sec.api_credentials 
 (credential_code VARCHAR2(30)   PRIMARY KEY,
  api_user        VARCHAR2(100)  NOT NULL,
  api_pwd         VARCHAR2(4000) NOT NULL);

Step 3: Create a Data Redaction Policy for the New Table

-- Run as ADMIN
-- Any user except for your parsing schema user will see NULL for the API_PWD column
BEGIN
  DBMS_REDACT.ADD_POLICY
   (object_schema   => 'API_SEC',
    object_name     => 'API_CREDENTIALS',
    column_name     => 'API_PWD',
    policy_name     => 'REDCT_API_CRED_PWD',
    function_type   => dbms_redact.full,
    expression      => 'sys_context(''userenv'',''current_user'') <> ''PARSING_SCHEMA''',
    enable          => TRUE);
END;
-- Where PARSING_SCHEMA is your APEX Parsing Schema

Step 4: Create a PL/SQL Package in the New Schema

This package will handle all interactions with the api_credentials table.

Create the package spec in the new API_SEC schema.

Package Spec

CREATE OR REPLACE PACKAGE api_credentials_pk AUTHID DEFINER AS

-- This procedure is specific to servicePath
-- You would create specific procedures similar to this for 
--   every API that requires their own unique authentication approach.
PROCEDURE set_servicepath_credentials 
  (p_apex_credential IN VARCHAR2,
   p_token_api_url   IN VARCHAR2);

-- Create a new record in api_credentials
PROCEDURE create_credential
 (p_credential_code IN api_credentials.credential_code%TYPE,
  p_api_user        IN api_credentials.api_user%TYPE,
  p_new_password    IN api_credentials.api_pwd%TYPE);

-- TBD Create APIs to change a password and delete a credential.

END api_credentials_pk;

• Create with DEFINER rights so that when we call the APIs from our APEX parsing schema, the APIs can access the un-redacted password in the API_SEC schema.

Package Body

CREATE OR REPLACE PACKAGE BODY api_credentials_pk AS

----------------------------------------------------------
-- Notice that we never return the value for API_PWD.
-- This prevents a developer from every seeing the password.
PROCEDURE set_servicepath_credentials
  (p_apex_credential IN VARCHAR2,
   p_token_api_url   IN VARCHAR2) IS

  CURSOR cr_credentials IS
    SELECT api_user
    ,      api_pwd
    FROM   api_credentials
    WHERE  credential_code = 'SERVICEPATH';

  lr_credentials      cr_credentials%ROWTYPE;
  l_body_json         VARCHAR2(1000);
  l_response          CLOB;
  l_access_token      VARCHAR2(4000);
  l_response_obj      json_object_t;

BEGIN

  apex_automation.log_info ('** Start Refresh servicePath Bearer Token **');
  apex_automation.log_info ('APEX Credential: '|| p_apex_credential);

  -- Get servicePath Credentials
  OPEN cr_credentials;
  FETCH cr_credentials INTO lr_credentials;
  CLOSE cr_credentials;

  -- Build JSON with Username and Password.
  l_body_json := JSON_OBJECT('Username' VALUE lr_credentials.api_user,
                             'Password' VALUE lr_credentials.api_pwd);

  -- Set HTTP Headers.
  apex_web_service.set_request_headers 
   (p_name_01   => 'Content-Type', 
    p_value_01  => 'application/json',
    p_name_02   => 'Accept', 
    p_value_02  => 'application/json',
    p_name_03   => 'User-Agent', 
    p_value_03  => 'APEX-Integration',
    p_reset     => TRUE);

  -- Call the servicePath Token Web Service.
  l_response := apex_web_service.make_rest_request
                 (p_url         => p_token_api_url,
                  p_body        => l_body_json,
                  p_http_method => 'POST');
  apex_automation.log_info ('Token API HTTP Response: '|| apex_web_service.g_status_code);

  IF apex_web_service.g_status_code <> 201 THEN
    apex_automation.log_error ('Token API Call Failed. Response: '|| l_response);
    raise_application_error(-20010, 'Error getting servicePath Token. HTTP Status Code: ' || apex_web_service.g_status_code);
  ELSE
    -- Store the Bearer token persistently in an APEX HTTP Header Web Credential
    l_response_obj := json_object_t.parse(l_response);
    l_access_token := l_response_obj.get_String('Bearer');
    apex_credential.set_persistent_credentials
     (p_credential_static_id => p_apex_credential,
      p_key                  => 'Authorization',
      p_value                => 'Bearer ' || l_access_token);
    apex_automation.log_info ('Token Set: '|| SUBSTR(l_access_token,1,10)||'...');
  END IF;

  apex_automation.log_info ('** End Refresh servicePath Bearer Token **');

EXCEPTION WHEN OTHERS THEN 
  apex_automation.log_error ('Unhandled Error ['|| SQLERRM || ']');
  RAISE; 
END set_servicepath_credentials;

----------------------------------------------------------
PROCEDURE create_credential 
 (p_credential_code IN api_credentials.credential_code%TYPE,
  p_api_user        IN api_credentials.api_user%TYPE,
  p_new_password    IN api_credentials.api_pwd%TYPE) IS

BEGIN
  INSERT INTO api_credentials
    (credential_code, api_user, api_pwd)
  VALUES 
    (p_credential_code, p_api_user, p_new_password);
END create_credential;

END api_credentials_pk;

Step 5: Grant Execute to the Package

Next, allow your APEX parsing schema to run APIs in the package:

-- Run as API_SEC or ADMIN
GRANT EXECUTE ON api_sec.api_credentials_pk TO <<PARSING_SCHEMA>>;

Step 6: Add a Credential

Create a credential:

-- Run from APEX Parsing Schema.
BEGIN
  api_credentials_pk.create_credential
   (p_credential_code => 'SERVICEPATH',
    p_api_user        => 'myusername',
    p_new_password    => 'mypassword');
END;

Step 7: Lock the New Schema

-- Run as ADMIN
-- Prevents anyone logging into this schema
ALTER USER api_sec ACCOUNT LOCK;

Summary

• No user can see the API_PWD column, except for the ADMIN user. Even the API_SEC user cannot see it because we locked the account.

• There is no API to get the password. Instead, we have an API to set the APEX Web Credential with the Access token. This prevents developers from seeing the API password (or the token).

• No schemas have access to the api_credentials table except for API_SEC (which is locked).

• The only way to affect the api_credentials is via the PL/SQL package api_credentials_pk which can only be run from your APEX parsing schema.

Putting it all Together

In this section, we will create an APEX Web Credential to store the Bearer Token and an APEX Automation to update the APEX Web Credential with a new Bearer token on a schedule.

APEX Web Credential

Before creating the Automation, we must create an ‘HTTP Header’ type APEX Web Credential to store the Bearer Token:

The set_servicepath_credentials procedure uses APEX_CREDENTIAL.SET_PERSISTENT_CREDENTIALS to store the Bearer token. apex_credential.set_persistent_credentials sets the Credential Name and Secret so all APEX sessions can utilize it.

BEGIN
  apex_credential.set_persistent_credentials
   (p_credential_static_id => p_apex_credential,
    p_key                  => 'Authorization',
    p_value                => 'Bearer ' || l_access_token);
END;

• The p_key parameter is stored in the ‘Credential Name’ field of the Web Credential.

• The p_value parameter is stored in the ‘Credential Secret’ field of the Web Credential.

There is an overloaded version of this procedure. It does the same thing with different parameter names.

BEGIN
  apex_credential.set_persistent_credentials
   (p_credential_static_id => p_apex_credential,
    p_username             => 'YourUserName',
    p_password             => 'YourPassword');
END;

APEX Automation

We can use an APEX Automation to update the Web Credential with a new Bearer token on a schedule. In the case of servicePath, the Bearer token is valid for eight hours. Given this, we may want to run the automation every seven hours.

• In the Automation Action, we call the set_servicepath_credentials API to set the Bearer token in the APEX Credential with a static ID called ‘servicepath’.

• We also pass in the token URL for the servicePath token endpoint.

Using the Web Credential

Now that the Bearer token is stored persistently in an APEX Web Credential (and refreshed on a schedule), we can use the HTTP Header type APEX Web Credential the same way as any other APEX Web Credential.

Used in APEX_WEB_SERVICE:

  l_response := apex_web_service.make_rest_request
                 (p_url                   => l_api_url,
                  p_http_method           => 'GET',
                  p_credential_static_id  => 'servicepath');

Used in an APEX REST Data Source:

Conclusion

While Oracle APEX Web Credentials don’t natively support every API authentication scheme, with the right architecture, we can work around those limitations without compromising on security or maintainability.

In this example, we:

✅ Handled non-standard API auth — Built a flow to retrieve and refresh Bearer tokens from a servicePath API that doesn’t follow standard auth protocols

✅ Secured credentials effectively — Used Oracle Transparent Data Encryption and Data Redaction to store credentials securely on OCI ATP without external key management

✅ Enabled full APEX integration — Persisted tokens in APEX Web Credentials so REST Data Sources and APEX_WEB_SERVICE calls can use them transparently

✅ Automated refresh securely — Leveraged APEX Automation to update tokens on schedule, preserving a fully native APEX experience

In this post, I’ll share two practical tips to enhance email functionality in Oracle APEX applications:

1. Why you should wrap the APEX_MAIL PL/SQL procedure with your own API.

2. How to use JSON_OBJECT_T to manage email placeholders more flexibly.

The second technique is also useful for passing parameters between procedures, without needing to know all the parameters in advance.

Using JSON_OBJECT_T for Placeholders

Background

APEX mail templates allow you to include placeholder variables that are substituted when you send an email using the APEX_MAIL API. All you have to do is pass JSON in the p_placeholders parameter. This is a very flexible approach.

However, in many apps, you’ll encounter multiple templates that share common fields. Without a structured approach, this often leads to redundant, boilerplate code. If we utilize the JSON_OBJECT_T data type, we can build a more efficient and lower-code solution.

Setting Placeholders

First, we define a reusable procedure to populate common placeholder fields related to quotes:

PROCEDURE common_email_placeholders
  (p_quote_id     IN quotes.quote_id%TYPE,
   x_placeholders IN OUT NOCOPY json_object_t) IS

  lr_quote_info        cr_quote_info%ROWTYPE;

BEGIN

  -- Get Details for the Quote.
  OPEN  cr_quote_info (cp_quote_id => p_quote_id);
  FETCH cr_quote_info INTO lr_quote_info;
  CLOSE cr_quote_info;

  -- Set Quote related values.
  x_placeholders.put ('CUSTOMER_NAME', lr_quote_info.account_name);
  x_placeholders.put ('QUOTE_TYPE', lr_quote_info.quote_type);
  x_placeholders.put ('QUOTE_NAME', lr_quote_info.quote_number);
  x_placeholders.put ('QUOTE_AMOUNT', lr_quote_info.quote_amount);

  -- Set other common values e.g. links back to our app, instance, name, and language.
  x_placeholders.put ('LANGUAGE_CODE', lr_quote_info.language_code);
  x_placeholders.put ('INSTANCE_NAME', get_instance_name());
  x_placeholders.put ('CUSTOMER_APP_LINK', get_app_url());
  x_placeholders.put ('PORTAL_APP_LINK', portal_url());

END common_email_placeholders;

The common procedure can include all possible placeholders.

Procedure to Send the Email

Next, we create a procedure to send a specific type of email, such as a request for approval. It builds on the common placeholders and adds email-specific fields if needed:

PROCEDURE email_request_for_approval
  (p_document_id IN evl_documents.document_id%TYPE,
   p_rule_name   IN VARCHAR2,
   p_to_email    IN VARCHAR2,
   p_comments    IN VARCHAR2 DEFAULT NULL) IS

  l_placeholders_obj   json_object_t := json_object_t();

BEGIN

  -- Set common email placeholders.
  common_email_placeholders
   (p_document_id  => p_document_id,
    x_placeholders => l_placeholders_obj);

  -- Add placeholders specific to this particular email.
  l_placeholders_obj.put ('APPROVAL_TYPE', p_rule_name);

  -- Call wrapper API to send the email (see below).
  send_email
   (p_to                 => p_to_email,
    p_template_static_id => 'APPROVAL_REQUIRED',
    p_placeholders       => l_placeholders_obj);

END email_request_for_approval;

Why Wrap APEX_MAIL?

Instead of calling APEX_MAIL directly, I recommend using a wrapper procedure. Here’s a basic example:

PROCEDURE send_email
  (p_to                 IN VARCHAR2,
   p_cc                 IN VARCHAR2 DEFAULT NULL,
   p_from               IN VARCHAR2 DEFAULT NULL,
   p_template_static_id IN VARCHAR2,
   p_placeholders       IN json_object_t) IS

  l_to_email       VARCHAR2(32000);
  l_cc_email       VARCHAR2(32000);
  l_placeholders   CLOB;

BEGIN

  -- Convert Placeholders json_object_t object to a CLOB required by APEX_MAIL.
  l_placeholders := p_placeholders.to_Clob;

  -- Whitelist To email dlist. 
  -- Useful for testing, avoid sending customers emails from development or test instances.
  l_to_email := apply_email_whitelist (p_email_address => p_to);
  IF p_cc IS NOT NULL THEN
    -- Whitelist CC email dlist.
    l_cc_email := apply_email_whitelist (p_email_address => p_cc);
  END IF;

  -- TBD additional code that checks a setting and does not send the email at all.

  -- Send the Email.
  apex_mail.send 
   (p_to                 => l_to_email,
    p_cc                 => l_cc_email,
    p_from               => NVL(p_from,  'Quoting <quoting@example.com>'),
    p_replyto            => 'no-reply@example.com',
    p_template_static_id => p_template_static_id,  
    p_placeholders       => l_placeholders);  

  -- TBD additional code to log the email.
  -- insert into email_log (to_email, subject, body, sent_on) values (...);

END send_email;

Key Benefits of Wrapping APEX_MAIL

Conclusion

Wrapping APEX_MAIL and using JSON_OBJECT_T for placeholders are simple but powerful techniques to improve your APEX application’s email functionality.

• Wrappers improve control, security, and maintainability.

• JSON-based placeholders enable flexible and scalable email generation.

These strategies reduce technical debt today and future-proof your application for tomorrow.