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.

No one gets excited about technical debt, but when your APEX instance is still on 18.2 (or earlier), its “interest clock” is already ticking.

Oracle offers full support for only 18 months per APEX release. Upgrading usually takes less time than your weekly sprint demo; yet, thousands of production apps still run on outdated versions.

Staying current isn’t just about running the latest APEX version. It’s about proactively addressing deprecated features and aligning Instance, Workspace, and Applications settings with the latest features.

This post will follow a case study of a client running on-premises APEX (18.2) who is migrating to an Autonomous Transaction Processing Database (ATP) instance running on Oracle Cloud Infrastructure (OCI).

Case Study

The client went live with their old system when APEX 18.2 came out in the fall of 2018 (seven years ago). Premier support for APEX 18.2 ran out at the end of March 2023 (two years ago). I thought, “Wow, this client has been running their APEX environment for seven years and has had virtually no maintenance costs.”

APEX Remediations

This section describes APEX remediations I discovered while assessing the client’s APEX 18.2 environment for upgrade to APEX 24.2.

Include Legacy JavaScript

There are two checkboxes: ‘Pre 18.1’ and ‘18.x’. They tell APEX to load legacy JavaScript libraries found in /i/libraries/apex/legacy*.js. These incur unnecessary overhead and indicate that you are not taking good care of your APEX environment!

Include jQuery Migrate

Similar to the previous option, this is a crutch for Apps using legacy jQuery code.

Compatibility Mode

Certain APEX runtime behaviors change from one release to the next. This option allows you to avoid the impact of these changes during an upgrade. The release notes list compatibility mode changes dating back to APEX 4.1.

Upgrade Universal Theme

Not on the Universal Theme - Yikes!

In this use case, one of the apps did not use the Universal Theme. Migrating from legacy themes to the Universal Theme is a significant undertaking and will likely require remediation and possibly even a UI redesign. See the ‘Migrating from Other Themes’ tab of the Migration Guide in the APEX Universal Theme App to learn how to migrate to the Universal Theme.

Refreshing the Universal Theme

Assuming your Apps are using the Universal Theme, the steps to refresh it are simple and are laid out in the ‘Refresh Universal Theme’ tab of the Migration Guide in the APEX Universal Theme App.

Upgrade Application

Specific APEX components undergo changes in their implementation. For example, between APEX 23.1 and APEX 24.1, the Rich Text Editor changed frameworks three times from CKEditor > Tiny MCE > Oracle Rich Text Library. The Date Picker has undergone similar changes to its implementation.

While APEX does a good job of allowing old implementations to work alongside the new, it is good practice to update to the latest implementation when you upgrade APEX.

One way to do this is to run the Upgrade Application utility. This will provide a report of components that you should transition to, along with suggestions on changes to make based on updates to existing components.

While not all suggestions need to be actioned, it is worth checking this report after every upgrade. For example, in the above report, ‘Upgrade jQuery Date Picker to new Date Picker’ should be addressed.

Check Security Settings

This exercise provides an excellent opportunity to ensure that you have all the recommended security settings in place. While this list is not intended to be a comprehensive security checklist, it highlights settings that are incorrectly configured for this customer and are worth reviewing in your instance.

Application Level Authorization Scheme

Page Level Authorization Schemes

Application Security Runtime API Usage

These options restrict what impact an application can have on your APEX environment. For example, to use the API APEX_UTIL.CREATE_USER in an APEX Application, the application must permit modification of the workspace repository.

Bookmark Hash Function

This was set to MD5 and needed to be SHA-2, 512-bit.

Browser Caching

This was set on. I can’t think of any good reasons to have this switched on.

Session State Protection

Although this was set at the Application Level (which does nothing), it was only set for about half of the pages. Not having this set for every page makes URL tampering a real risk.

Session Management

While this was set for the applications in this case study, it is worth noting, especially for applications that haven’t been updated in a long time. Setting appropriate idle and session timeouts is essential.

Other Settings to Check

Friendly URLs

Enabling Friendly URLs changes how APEX handles URLs from the legacy f?p= syntax to a path-based syntax. It is also a prerequisite for enabling PWAs.

Progressive Web App

Enable the ‘Enable Progressive Web App’ setting as a minimum. This provides performance improvements by serving static files more efficiently using advanced caching. There are also other compelling PWA features worth considering.

Instance & Workspace Settings

As APEX evolves, new options are added at the Instance (INTERNAL/Administration Services) and Workspace levels. It is essential to verify these settings after an upgrade to ensure that any newly added options are configured correctly.

Instance

Some more recently added instance settings that you should check:

• Manage Instance > Security

  • AI Enabled (on by default)

  • Allow Persistent Auth (Off by default)

• Manage Instance > Instance Settings

  • Workflow Settings

  • Background Jobs

Not recent but worth checking anyway:

• Manage Instance > Security > Require HTTPS (should be on)

Workspace

Some more recently added workspace settings that you should check:

• Manage Workspaces > Existing Workspaces > Edit Workspace Information

  • AI Enabled

  • Maximum Background Page Process Jobs (on-premise only)

Plugins

The applications that were part of this exercise used five plugins. All of them are no longer actively supported. The good news is that they can all be replaced with standard functionality in APEX 24.2.

Tabular Forms

Tabular forms were used extensively. Tabular forms were deprecated in APEX 20.1 and are considered legacy.

Deprecated & De-Supported Features/APIs

Check for references to deprecated APEX features, PL/SQL, and JavaScript APIs. In my use case, I found calls to htmldb_mail.SEND and wwv_flow_mail.push_queue and usage of legacy data load definitions and tabular forms.

Modern Authentication

For this use case, the customer utilized a custom table-based Authentication Scheme with plain-text passwords. Legacy apps often use hardcoded custom authentication schemes that are now better handled with APEX Social sign-on and modern authentication providers, such as Active Directory and Okta.

This even applies to APEX Builder. Configuring APEX Builder to use SSO enhances the security of your development environment and streamlines login for your developers.

APEX Advisor

The APEX advisor appears to be receiving more attention from the APEX development team, and as of APEX 24.2, is starting to provide valuable insights again.

Release Notes

If all you did for each APEX upgrade were to read the release notes, you would be more than halfway there. Just look at the index. Why would you not want to know these things before upgrading?

What About ORDS?

Everything I have said about APEX applies to Oracle REST Data Services (ORDS). In every release, ORDS introduces new features, deprecations, performance improvements, and bug fixes. In short, whatever steps you take for APEX, you should also take for ORDS.

What About the Database?

The great thing about APEX running in the database is that with each major database release, APEX receives a direct boost in functionality and performance enhancements. When performing a database upgrade, review the new features to identify areas where you can utilize modern approaches and features. Some examples in 19c and 23ai include:

• Significant improvements to how you handle JSON in the database. This includes much more efficient JSON Parsing since 19c. It also enables the inclusion of additional attributes in a JSON column.

• Vector/Semantic search in 23ai significantly enhances search and serves as the building block for AI techniques, such as Retrieval-Augmented Generation (RAG).

• SQL Macros (since 19c) allow you to create parameterized views, which can boost the performance of your APEX reports.

• JSON Relational Duality Views provide a configurable JSON interface to relational tables.

Reasons to Stay Up to Date

1. Oracle Support - After a new version of APEX is released, Oracle provides support for it for 18 months.

2. Security - By running the latest version, you are running the most secure version of APEX. Also, remember to update the recommended security settings accordingly.

3. Return on Investment - Take advantage of the latest groundbreaking features by running the latest APEX version and enabling new features.

4. Performance - Take advantage of performance improvements included in the latest version.

5. Developer Productivity - The latest features make building APEX Apps even quicker.

6. Developer Sanity - Keep your developers happy (no one wants to be working on APEX 18.2).

Reasons Why We Don’t Stay Up to Date

For every reason why it is a good idea to stay up to date, there is another reason why people don’t:

1. Fear of breaking Apps with a lot of Custom JavaScript.

2. Fear of breaking something by making changes to settings.

3. Fear of breaking Plugins.

4. Lack of Resources to remediate and or regression test after every upgrade.

5. Locked into a Custom Theme that cannot be refreshed or converted to the Universal Theme.

How Can I Avoid This Fate?

Follow these steps to avoid the fate of the customer in my use case:

1. Avoid plugins unless they provide a measurable differentiator for your business. For example, APEX Office Print from United Codes provides functionality fundamental to business applications that are not available in APEX out of the box.

2. If your business depends on a Plugin, make sure you either know how to fix it yourself or that a reputable company, such as United Codes, supports it.

3. Check the release notes to see if the latest version has a feature that allows you to remove a plugin or simplify code.

4. Avoid JavaScript unless it is going to provide a measurable business impact.

5. Do not unsubscribe from the Universal Theme.

6. Upgrade APEX (and ORDS) at least once a year.

7. Read the release notes for every APEX release.

8. If you do not address the remediation issue in the current upgrade cycle, at least document it so that you are aware of the technical debt you are accumulating by not taking action. Documenting deferred remediations has the added benefit of giving you a list to process throughout the year. I suggest leaking them into your sprints while working on other changes to your Apps. You could also reserve a couple of dedicated sprints each year to handle remediation issues.

9. Build regression test scripts (manual or automated) to allow you to run regressions after each upgrade.

Conclusion

An aging APEX environment rarely screams for attention. All the same, it quietly accumulates risk, inefficiency, and missed opportunity. As this case study shows, the illusion of stability can mask a mounting backlog of deprecated features, security gaps, and unsupported components.

The payoff is modern security, faster performance, happier developers, and the freedom to adopt new features with confidence. Don’t let inertia become your architecture. Make staying current part of your culture, not just your roadmap.

One of the upcoming features described by the APEX Development team at KSCOPE25 was Custom Tools (also known as Functions). Although this feature is not yet available, this post describes how AI tools like OpenAI utilize functions and how we can implement them in our APEX Apps today.

Before I begin, I would like to clarify the distinction between Tools and Functions in the context of AI. LLMs utilize tools to perform external actions that assist the LLM in answering a question. Functions are a type of Tool that allows you to run custom code and return the results to the LLM.

How Functions Work

When I first looked into functions, I thought that the LLM directly called the function. This put me off looking into functions because, for most business use cases, you would not want a public LLM to be able to access your business data via an API call.

It was at KSCOPE that I realized that this is how functions work:

1. Pass the LLM the user’s question and a list of potential functions.

2. The LLM returns a list of functions (and their corresponding parameter values) that it wants you to run to help it answer the user’s question.

3. You run the requested functions(s) and call the LLM a second time with the user’s questions and the results of running the function(s).

4. The LLM uses the results from the function calls (and it’s general knowledge) to answer the question.

The diagram below shows an example process flow:

Why not use RAG?

Retrieval Augmented Generation (RAG) involves searching for and sending a subset of your data to the LLM to use for context when answering a question.

Functions offer an alternative to RAG solutions, enabling LLMs to act on your business data. RAG solutions often rely on passing a significant amount of your data to the LLM for context. Functions can significantly reduce the amount of data (and therefore the cost) by allowing the LLM to request only the data it needs to answer the question.

Example

For my example, I would like to request information about a Sales Order. I will be using the OpenAI Responses API. The documentation on functions can be found here.

PL/SQL Function

I created a simple PL/SQL function that returned information about a Sales Order. The function was compiled in my database.

CREATE OR REPLACE FUNCTION get_order_info(p_order_id NUMBER, p_info_type VARCHAR2) RETURN VARCHAR2 IS
    l_order_id        sales_orders.order_id%TYPE;
    l_order_date      sales_orders.order_date%TYPE;
    l_customer_number sales_orders.customer_number%TYPE;
    l_total_amount    sales_orders.total_amount%TYPE;
    l_status          sales_orders.status%TYPE;
BEGIN
    SELECT order_id, order_date, customer_number, total_amount, status
      INTO l_order_id, l_order_date, l_customer_number, l_total_amount, l_status
      FROM sales_orders
     WHERE order_id = p_order_id;

    IF LOWER(p_info_type) = 'order_id' THEN
        RETURN l_order_id;
    ELSIF LOWER(p_info_type) = 'order_date' THEN
        RETURN TO_CHAR(l_order_date, 'YYYY-MM-DD');
    ELSIF LOWER(p_info_type) = 'customer_number' THEN
        RETURN l_customer_number;
    ELSIF LOWER(p_info_type) = 'total_amount' THEN
        RETURN TO_CHAR(l_total_amount);
    ELSIF LOWER(p_info_type) = 'status' THEN
        RETURN l_status;
    ELSE
        RETURN 'Invalid info_type';
    END IF;
EXCEPTION WHEN NO_DATA_FOUND THEN
  RETURN 'Order not found.';
END;

End-To-End Example in JSON

Let’s walk through an example illustrating the JSON that is passed back and forth at each step. Note: In the JSON examples, I have omitted parts of the payload (e.g., model, temperature) that are not explicitly related to functions.

For each of the calls to the LLM, we can use apex_web_service.make_rest_request.

  apex_web_service.set_request_headers 
   (p_name_01   => 'Content-Type', 
    p_value_01  => 'application/json',
    p_name_02   => 'Authorization', 
    p_value_02  => 'Bearer YOURAPIKEYGOESHERE',
    p_reset     => TRUE);

  l_response := apex_web_service.make_rest_request
   (p_url         => 'https://api.openai.com/v1/responses',
    p_http_method => 'POST',
    p_body        => l_json);

JSON for Initial LLM Call with Function Definitions (Call 1)

{
  "input": [
    {
      "role": "system",
      "content": [
        {
          "type": "input_text",
          "text": "Answer the users question"
        }
      ]
    },
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "what is the status of order 1"
        }
      ]
    }
  ],
  "tools": [
    {
      "type": "function",
      "name": "get_order_info",
      "description": "Retrieves order information based on the provided order ID and information type.",
      "parameters": {
        "type": "object",
        "required": [
          "p_order_id",
          "p_info_type"
        ],
        "properties": {
          "p_order_id": {
            "type": "number",
            "description": "The unique identifier for the order"
          },
          "p_info_type": {
            "type": "string",
            "description": "The type of information to retrieve (e.g., order_id, order_date, customer_number, total_amount, status)"
          }
        },
        "additionalProperties": false
      },
      "strict": true
    }
  ]
}

• The input array contains the system prompt and the user’s question.

• The tools array contains a list of the functions I want the LLM to consider when answering the user’s question. The tool type in this case is function.

• Function definitions require a specific JSON format, which can be viewed here. The documentation also specifies best practices for defining a function, which I advise you to read.

Response from Call 1

{
  "output": [
    {
      "id": "fc_6858c0ab059c819b89594dc4d64dd4df03a1897b9ddea35b",
      "type": "function_call",
      "status": "completed",
      "arguments": "{\"p_order_id\":1,\"p_info_type\":\"status\"}",
      "call_id": "call_fyixqaqJGHwVsOada86TkvTs",
      "name": "get_order_info"
    }
  ],
  "parallel_tool_calls": true,
  "tool_choice": "auto",
  "tools": [
    {
      "type": "function",
      "description": "Retrieves order information based on the provided order ID and information type.",
      "name": "get_order_info",
      "parameters": {
        "type": "object",
        "required": [
          "p_order_id",
          "p_info_type"
        ],
        "properties": {
          "p_order_id": {
            "type": "number",
            "description": "The unique identifier for the order"
          },
          "p_info_type": {
            "type": "string",
            "description": "The type of information to retrieve (e.g., order_id, order_date, customer_number, total_amount, status)"
          }
        },
        "additionalProperties": false
      },
      "strict": true
    }
  ]
}

• If the LLM finds a function that it wants you to run, it will be listed in the output array. This is signified by the output type of function_call.

• In the above example, it is asking us to run a function with the name get_order_info and pass parameters as follows:

  • p_order_id = 1

  • p_info_type = status

Call our Function

All we need to do now is run the function:

  -- Parse the Response from call 1
  l_response_obj := JSON_OBJECT_T.parse(l_response);
  l_output_arr := l_response_obj.get_Array('output');
  l_output_obj := JSON_OBJECT_T(l_output_arr.get(0));
  l_name      := l_output_obj.get_String('name');  
  l_arguments := l_output_obj.get_String('arguments');

  -- Call the function.
  IF l_name = 'get_order_info' THEN
    l_order_info := get_order_info
     (p_order_id  => JSON_OBJECT_T.parse(l_arguments).get_Number('p_order_id'),
      p_info_type => JSON_OBJECT_T.parse(l_arguments).get_String('p_info_type'));
  END IF;

JSON Payload for the Second LLM Call with Function Results (Call 2)

{
  "input": [
    {
      "role": "system",
      "content": [
        {
          "type": "input_text",
          "text": "Answer the users question"
        }
      ]
    },
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "what is the status of order 1"
        }
      ]
    },
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "The result from tool get_order_info is: Pending"
        }
      ]
    }
  ]
}

• I included the result from the function call as a second user message in the input array.

• When we call the LLM with this JSON, it now has everything it needs to answer the user’s question.

Response from Call 2

{
  "output": [
    {
      "id": "msg_6858c2e3439c8199a71400ac3c3b38ba020aa24e30c9a174",
      "type": "message",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "annotations": [],
          "text": "The status of order 1 is currently pending."
        }
      ],
      "role": "assistant"
    }
  ]
}

• You can see the answer to the question in the output.content.text field.

Additional Thoughts

Multiple Tool Calls

As I alluded to in the example, the LLM will request multiple function calls if it requires them. For example, if the user asks the question ‘what is the status of order 1 and what is its value', then we can expect the LLM to ask us to call the function twice with different parameters. The following JSON is an excerpt from the response, where the LLM instructs us to call the function once to retrieve the status and again to get the amount.

"output": [
  {
    "id": "fc_685997def9b88199977de8d1d817431603004e30121b785e",
    "type": "function_call",
    "status": "completed",
    "arguments": "{\"p_order_id\":1,\"p_info_type\":\"status\"}",
    "call_id": "call_X38rKT3SQhefM5561hvxKlTk",
    "name": "get_order_info"
  },
  {
    "id": "fc_685997df3c7c819993541e73df119cf503004e30121b785e",
    "type": "function_call",
    "status": "completed",
    "arguments": "{\"p_order_id\":1,\"p_info_type\":\"total_amount\"}",
    "call_id": "call_lwcVs312CMVjz1TRex9To09i",
    "name": "get_order_info"
  }

This means your code must:

• Loop through and call all of the requested functions.

• Concatenate responses from the tool calls and send them back in the 2nd user message of the second call to the LLM, e.g., ‘Function Name: get_order_info - status = Pending \n Function Name: get_order_info - total_amount = 250 \n’.

Security

Of course, security is a primary concern here. Assuming you are calling the LLM from an APEX Application, then you should provide that user context to your function calls to make sure the user has access to the data in question.

Other security considerations:

• Make sure you are OK with the results of your function calls being consumed by the LLM and potentially ending up in remote log files, etc.

• Validate parameters received from the LLM against database constraints before calling functions.

• Log each function invocation with inputs and user context for auditing.

• Avoid exposing high-sensitivity operations (e.g., finance approvals) directly via function calls.

Additional Use Cases

I purposely chose a simplified example for this post, but there are many other potential use cases for functions. Here are three to get your thinking:

• Customer-Facing ERP Chatbot

  • Provide users of your customer portal with a way to get their order status using natural language. If the customer wants to change or cancel an order, initiate an APEX workflow to obtain approval for and take action on the change.

• Project Status Assistant

  • Let project managers ask “Show me open risks for Project Delta” or “What tasks are overdue for Milestone 3?” with dynamic responses from your project tables.

• AI-Assisted Form Auto-Fill

  • On a data-entry screen, users can say, “Pre-fill this form using the last order I created,” and a function retrieves and injects historical values into the current APEX session state.

Conclusion

As you can see, incorporating functions in your apps is not straightforward. You must provide a robust wrapper to handle zero or multiple function call requests, invalid parameters, route to the correct PL/SQL code, etc. That being said, function calling provides a structured approach to integrating business logic with LLMs, allowing for the safe handling of sensitive data. By handling function execution server-side and passing only the necessary results to the LLM, this approach strikes a balance between capability and control.

In AI development, evaluating an LLM’s performance using test cases based on your understanding of what the LLM is supposed to do is critical. These evaluations, commonly called “Evals”, serve as test cases to help you assess whether your model behaves the way it should. In this post, I’ll explain why Evals are essential, show how they apply in Oracle APEX environments, and provide examples you can adapt to your projects.

My Aha Moment

I recently came across a Y Combinator video on YouTube that discussed Meta-Prompting. While Meta-Prompting is an interesting topic in its own right, it was something else they said that made me stop and think. They were showcasing a Prompt from an AI Startup that focuses on Customer Service and highlighted the fact that the company does not consider their AI Prompts to be their primary Intellectual Property (IP). This surprised me because you would have thought that prompts would be the most important asset for a business that has essentially built a wrapper on ChatGPT.

This startup considers the thousands of Evals (Test Cases) they have developed based on their deep domain knowledge of Customer Service as their primary IP.

Why Create Evals?

Measure Model Quality and Progress

Evals give objective metrics to track:

• Accuracy, fluency, coherence, or truthfulness

• Improvements across model iterations

• New feature emergence (e.g., tool use, reasoning)

Align Model Behavior with Product or User Goals

Well-designed evals ensure the model performs as expected for:

• Specific tasks (e.g., summarization, classification, document recognition)

• Business KPIs (e.g., ticket deflection, content moderation accuracy)

• User satisfaction and trust

Identify Weaknesses, Gaps, and Safety Issues

Evals uncover:

• Hallucinations, bias, toxicity, and overconfidence

• Weak performance on edge cases or minority groups

• Failure modes in real-world or adversarial conditions

Compare Across Models, Versions, and Configurations

Evals allow rigorous A/B testing of:

• Different AI platforms and the different models they offer

• Prompt templates, temperature settings, or tool-using agents

Trustworthy, Responsible Deployment

For enterprise use cases, evals provide:

• Documentation of model performance and limitations

• Assurance of compliance (e.g., fairness, explainability)

• Evidence for audits or governance boards

Types of Evals

There are two primary types of Evals. I will use examples from my APEX Developer Blogs Website to illustrate them.

Code Driven

The best way to evaluate the result of an interaction with an LLM is to use code to check its work. To do this, however, the result of the AI interaction must be empirical. It’s probably easiest to describe this using an example.

Example - Blog Classifier

Before allowing blogs onto APEX Developer Blogs, I first check them for relevance related to 5 areas of interest to APEX Developers (APEX, ORDS, OCI, SQL, and PL/SQL). I pass a prompt and the content of the post to OpenAI, and ask it to check the post for relevance, specifying that I want a JSON object in response that looks like this:

{"APEX":2,"ORDS":0,"OCI":1,"SQL":0,"PLSQL":2}

For each category, I am looking for a score from zero to five. If a post receives a score of two or more across all categories, I allow it. Otherwise, I add it to a queue of rejected posts, which I review manually every so often.

This response is something I can easily test programmatically:

• Verify it is valid JSON using json_object.parse. If an -40441 error occurs, then the JSON is not valid.

• Verify that all five categories are represented. Use json_obj.has to check for each field.

• Verify that the scores are between zero and five. Use json_obj.get_Number to verify the scores are within range.

• Store the scores so that I can test the same blog posts with different parameters (new models, changes to the temperature, etc) and see how the scores change. Log all calls to AI and store the request and response (more on this later).

LLM Driven

Of course, if you could use code to test all of the responses from an LLM, then we would not need the LLM to start with. The LLM-driven approach involves making a second call to the LLM to check that the output is correct, or at least meets the standards you are aiming to achieve.

Example - Blog Summarizer

The second step when ingesting blogs in APEX Developer Blogs is to create a simple Gist of the post. This allows people to get the gist of the post before reading it in full. Much as I would like to, there is no way I could read every post and write a summary myself.

So, how can we test if the summary that OpenAI generates is any good? The answer is to pass the post and the summary back to the LLM, asking it to rate the summary. We could use a prompt like the one below to do this:

# BACKGROUND
- I write summaries/gists of blog posts so that users can see a preview of the post before reading it.
- I want to make sure my summary is high quality. 
- What follows is the summary ##SUMMARY## followed by the blog post ##BLOG POST##. 
# TASK
- Carefully compare the summary to the blog post and assess the quality of the summary based on conciseness and readability. 
- The scores should be between 0-5 with 5 being excellent and 0 being extremely poor. 
# OUTPUT
- Return the scores in a JSON object that looks like this: {"READABILITY":4,"CONCISENESS":2}
##SUMMARY##
<<Summary Goes Here>>
##BLOG POST##
<<Blog Post Goes Here>>

This returns a JSON score, which we can evaluate using PL/SQL.

How can we do Evals in APEX?

Using Historical Data

The easiest way to run evals is on LLM calls that have already been run. To do this reliably, you need to be able to determine the parameters and payload that went into the LLM call, as well as the response. I suggest creating two tables: one to store AI Configurations and another to log all your LLM calls.

⚙️ Configs

Create a table to store your AI Configs, which includes:

• Config Name

• AI Provider, Model, & REST EndPoint

• Max Input & Output Tokens

• Temperature

• APEX Web Credential

• Instructions / System Prompt

Storing this information in a table allows you to easily make changes to the parameters and keep track of which configuration generated which output.

🪵 Log Table

You should be logging every call you make to the LLM. This provides the foundational data for running your Evaluations. Your log table should include the following:

• Foreign Key to your Config table, so you know which config generated which log

• Response Time (to measure the performance of LLM API calls using different models)

• Outbound JSON Payload to the LLM REST API

• Response JSON returned from the LLM REST API

With a combination of the Config and the Log Tables, you have everything you need to run evals against historical LLM calls.

📚 Eval Library

Being proactive about Evals takes more effort. You need to build a library of tests (and expected results) as well as code that can run these tests against your prompts and data. This is where your domain knowledge comes into play. You need to think of all the possible scenarios that could come into play and design tests that cater for those (not forgetting the edge cases, of course). These evals (or tests) represent the knowledge you have on the subject that perhaps no one else knows.

You should continually add to and adjust the library over time as new use cases and user behaviors emerge.

Given that we run APEX on a database, APEX is the obvious tool for maintaining such a library. You can also use APEX to run your evaluations, track results, and report on them.

Red Teaming

While traditional Evals measure whether an AI model meets your quality and performance standards, red teaming focuses on discovering its failures. This involves intentionally crafting contrarian inputs to elicit undesired behavior, such as biased, toxic, or misleading outputs.

Red teaming helps answer questions like:

• Can the model be jailbroken to ignore safety instructions?

• Does it respond differently to subtly biased prompts?

• Will it hallucinate plausible-sounding but false information?

• Does it degrade disproportionately on edge cases (e.g., ambiguous phrasing)?

In enterprise use, this kind of testing is critical for:

• Hardening your application against misuse

• Meeting compliance or governance obligations

• Understanding risk before deployment at scale

🔗 This post from Anthropic provides an overview of Red Teaming and how they do it.

Conclusion

As APEX developers, test-driven development is second nature, but when it comes to AI, it’s easy to overlook evaluation in the excitement of prompt engineering. Evals give you a structured, repeatable, and objective way to track progress, detect regressions, and justify AI decisions in enterprise environments. Whether you’re classifying content or summarizing documents, start small by logging your LLM calls. Then build your Eval Library over time.