An OIC Human Task is a built-in Oracle Integration Cloud activity that pauses a running integration to route a decision to a person — sending a notification, waiting indefinitely without consuming compute, and resuming the flow the moment that person approves or rejects. Paired with a three-zone decision model, it's how you teach an AI Agent to know the difference between an easy yes, an easy no, and a genuine judgment call that belongs to a human.
Have you ever wondered what happens when an AI system is not sure whether to say yes or no?
In previous sessions, we set firm expense limits for each category — $500 for Training, $1,000 for Travel.
Clear approvals and clear rejections are easy. But what about the amounts right at the edge?
A $480 Training expense when the limit is $500 — is it a rubber-stamp approval,
or does it deserve a second pair of eyes?
The answer is hiding inside a three-zone decision model and a powerful OIC feature called the Human Task.
🗺️ The Big Picture — Why Do We Need a Grey Zone?
In most real companies, amounts close to a policy limit go to a human manager for review.
The AI handles the easy cases instantly. A human handles the borderline ones.
Here is how that flow looks end to end:
Expense
Submitted
AI Agent
Evaluates
3-Zone
Decision
Human Task
(if yellow)
Manager
Decides
Final
Response
Simple, right? Now let us understand each part in detail! 🎯
🚦 Part 1 — The Three-Zone Decision Model
Before writing a single line of configuration, let us map the three zones.
Think of the classic traffic light — it has three colours for a reason!
Think of a traffic light at a junction.
🟢 Green (far under limit) → the AI agent says APPROVED and moves on. No human needed.
🔴 Red (far over limit) → the AI agent says REJECTED immediately. No human needed.
🟡 Yellow (close to the limit) → the AI agent pauses, sends the decision to a human manager, and waits for that human to click Approve or Reject. The human is the final authority in the yellow zone.
In our system, the yellow zone is: amount between $400 and $500 for a Training expense (limit $500).
The exact range is configurable — we will show how to make it easy to change later.
Here is the full three-zone map for a Training expense with a $500 limit:
The AI agent never changes. The integration adds the new yellow-zone logic. When the integration returns
PENDING_HUMAN as the decision,
the agent tells the user "a manager has been notified and will respond shortly."
The agent itself does not send any email — the integration does that through OIC's Human Task engine.
👤 Part 2 — What Is an OIC Human Task?
An OIC Human Task is a special activity you can drop into any integration.
When the flow reaches it, three things happen automatically — no code required.
- Sends a notification — typically an email — to one or more assigned approvers.
- Pauses the integration — the flow waits. It does not time out or burn compute while waiting.
- Resumes when the human acts — when the approver clicks Approve or Reject, the integration wakes up and continues with that decision.
Imagine you send a letter to your boss asking for permission to buy something expensive. You then sit down and wait for the reply — you are not running around doing other things. You are just patiently waiting.
When the boss writes back "YES" or "NO", you wake up, read the reply, and carry out whatever comes next. That is exactly what an OIC Human Task does — it sends the request, then sleeps, then wakes up with the human's answer. 💌
🔍 OIC Human Task — The Full Lifecycle
Here is how the Human Task flows from trigger to completion, step by step:
Beautiful, isn't it? The integration sleeps patiently and wakes up only when the human is ready. 🎯
🏗️ Part 3 — Updated System Architecture
Compared to the previous session, only the integration changes — and only in the borderline zone branch.
The agent, the LLM, the ReAct pattern, and the tool registration stay exactly the same.
We add one new integration version (v3.0) and update the system prompt slightly.
Integration pauses here.
Two clickable buttons: Approve / Reject.
Returns APPROVED_BY_MANAGER or REJECTED_BY_MANAGER.
Only the integration changes between v2.0 and v3.0 — not the agent, not the LLM, not the tool registration. This is intentional design. Keeping the agent stable means you can upgrade the business logic (the integration) independently, with zero disruption to the AI layer.
🛠️ Part 4 — How to Build It — Step by Step
There are six steps to go from v2.0 to a fully working Human-in-the-Loop system.
Here is the complete roadmap before we dive into each step:
Let us build each step now! 🚀
⌨️ Step 1 — Create Integration v3.0
Open the project. Find CheckExpenseApproval v2.0.
Click the three-dot menu (⋮) and select Create New Version.
This creates v3.0 as a draft copy. Version 2.0 stays live and handles all requests
until we activate and switch to v3.0.
Always version before editing. Never edit an active integration directly. If your v3.0 has a bug and you need to roll back in production, you simply point the agent tool back to v2.0 — a two-click operation. No panic. No emergency fix. Just a clean rollback. ✅
⌨️ Step 2 — Add the Borderline Zone to the Switch
In v2.0, each category branch had two paths: amount within limit → APPROVED, amount over limit → REJECTED.
In v3.0, we split the "within limit" path into two: comfortably within (green) and borderline (yellow).
Let us use the Training category (limit $500) as the full worked example.
The other categories follow the same pattern with their own numbers.
reason = "Within limit"
AND amount <= 499
decision = "PENDING_HUMAN"
Wait for click.
reason = "Exceeds limit"
This is the condition for the new yellow branch inside the Training Switch. The first condition checks the amount is at or above the borderline floor ($400). The second condition checks it has not yet hit the full limit ($500). When BOTH are true, this branch runs and the Human Task activity is triggered. The AND keyword means both conditions must be satisfied simultaneously.
$Request/nsmpr0:request-wrapper/expenseAmount >= 400 AND $Request/nsmpr0:request-wrapper/expenseAmount <= 499
In OIC Switch activities, branches are evaluated top to bottom and the first matching branch wins. Always put the yellow (borderline) branch before the green (approved) branch — never after it. If the green branch condition is
amount <= 500, it will swallow borderline amounts and
the yellow branch will never be reached.Correct order: Yellow → Green → Red (narrow conditions first). ✅
⌨️ Step 3 — Configure the Human Task Activity
Inside the yellow branch — after the condition is satisfied — we add a Human Task activity.
In OIC Gen3 this is found in the activity palette under Approvals. Easy to find! 🎯
Here are all the settings you need to fill in:
| Field | Value to Enter | Why |
|---|---|---|
| Task Name | BorderlineExpenseApproval |
Appears in OIC Monitoring and the manager's inbox subject line |
| Assignees (Approvers) | manager@company.com (or a role) |
Who receives the email. Can be dynamic from the request payload. |
| Outcomes | APPROVE, REJECT | These become the two clickable buttons in the email and OIC Workspace |
| Expiry / Escalation | 48 hours → escalate to senior manager | Prevents the task waiting forever if the manager is on leave |
| Notification Channel | Email (SMTP or Oracle Notification Service) | Where the task notification goes |
| Priority | Normal | Affects how it appears in the OIC Workspace task list |
📧 The Approval Email — What the Manager Sees
The email body is configured inside the Human Task notification template.
You can use XPath expressions to insert live values from the expense request.
Here is exactly what lands in the manager's inbox:
Dear Manager,
An expense claim requires your review because it falls within the borderline zone (80%–99% of the policy limit).
Please click one of the buttons below to submit your decision:
This task will expire in 48 hours. If no action is taken, it will escalate to senior management. You can also manage this task in the OIC Workspace Portal.
In the Human Task activity → click Configure Notification → choose Email. In the Subject field, use XPath:
concat("Approval Required — Borderline Expense: $", $Request/expenseAmount, " (", $Request/expenseCategory, ")").
In the Body, use the rich-text editor and insert XPath field references by clicking the variable picker
(the {x} button) to pull live values from the request payload.
⌨️ Step 4 — Updated Response Payload and Decision Values
The integration now has five possible decision values instead of two.
We update the response schema and add two new outcome mapping branches —
one for when the manager approves, one for when the manager rejects.
We now allow five decision values instead of two. The new values (
PENDING_HUMAN, APPROVED_BY_MANAGER, REJECTED_BY_MANAGER)
let the AI agent understand exactly what happened and phrase its response accordingly.
We also add approverEmail so the agent can tell the employee who made the decision,
and taskId for audit tracking.
{
"type": "object",
"properties": {
"decision": {
"type": "string",
"description": "One of five values",
"enum": [
"APPROVED",
"REJECTED",
"PENDING_HUMAN",
"APPROVED_BY_MANAGER",
"REJECTED_BY_MANAGER"
]
},
"reason": { "type": "string" },
"amount": { "type": "number" },
"expenseCategory": { "type": "string" },
"categoryLimit": { "type": "number" },
"remainingBudget": { "type": "number" },
"approverEmail": {
"type": "string",
"description": "Email of the human who approved or rejected (null if AI decided)"
},
"taskId": {
"type": "string",
"description": "OIC Human Task ID for audit trail tracking"
}
}
}
🔍 Mapping the Human Task Outcomes
After the Human Task activity in OIC, you add an If/Else that checks
the task outcome variable — let us call it $HumanTaskOutcome.
This variable is automatically populated by OIC when the manager clicks a button.
After the Human Task completes (manager clicked), the flow enters this If/Else. Branch 1 checks if the outcome equals the APPROVE label we configured earlier. If yes → map APPROVED_BY_MANAGER. If no (REJECT was clicked) → map REJECTED_BY_MANAGER. Both branches also capture the approver's email from the Human Task context variable for the audit trail.
IF: $HumanTaskOutcome/outcome = "APPROVE"
decision → "APPROVED_BY_MANAGER"
reason → concat("Borderline Training expense of $",
string($Request/expenseAmount),
" has been manually reviewed and approved by your manager.")
amount → $Request/expenseAmount
expenseCategory → $Request/expenseCategory
categoryLimit → 500
remainingBudget → 500 - $Request/expenseAmount
approverEmail → $HumanTaskOutcome/assignee/email
taskId → $HumanTaskOutcome/taskId
ELSE: (outcome = "REJECT")
decision → "REJECTED_BY_MANAGER"
reason → concat("Borderline Training expense of $",
string($Request/expenseAmount),
" has been reviewed and rejected by your manager.",
" Please contact them directly for further guidance.")
amount → $Request/expenseAmount
categoryLimit → 500
remainingBudget → 0
approverEmail → $HumanTaskOutcome/assignee/email
taskId → $HumanTaskOutcome/taskId
When the yellow branch first fires, OIC triggers the Human Task and the integration pauses. But the AI agent (the original API caller) is still waiting for a response right now. We return PENDING_HUMAN immediately so the agent can tell the user "a manager has been notified." Think of it as an instant acknowledgement receipt — the full answer comes later asynchronously.
decision → "PENDING_HUMAN"
reason → concat("Your ", $Request/expenseCategory,
" expense of $", string($Request/expenseAmount),
" is in the manager review zone ($400–$499 for this category).",
" An approval request has been sent to your manager.",
" You will receive an email notification once they have reviewed it.")
amount → $Request/expenseAmount
expenseCategory → $Request/expenseCategory
categoryLimit → 500
remainingBudget → 0
approverEmail → "manager@company.com"
taskId → "" (populated after Human Task completes)
⌨️ Step 5 — Updated System Prompt and Tool Description
The tool description needs to tell the agent about the three new decision values.
And the system prompt needs to tell the agent how to talk to the user
when the answer is "not yet — a human is deciding."
🔍 Updated Tool Description
The DECISION VALUES section is the most critical update. The LLM reads this to understand what each decision value means. Without a clear explanation of PENDING_HUMAN, the agent might literally say "the result is PENDING_HUMAN" — copying the raw code instead of explaining it in plain English. With a clear description, it knows to say "your expense is being reviewed by a manager." 🤖
Use this tool to evaluate whether an employee expense should be approved or rejected.
The tool applies category-specific limits and a three-zone decision model.
REQUIRED INPUTS:
- expenseAmount (number): The expense amount in USD
- expenseCategory (string): Travel | Meals | Office Supplies |
Training | Software | Entertainment | Other
DECISION VALUES THE TOOL RETURNS:
- APPROVED → AI approved automatically (well within limit)
- REJECTED → AI rejected automatically (over limit)
- PENDING_HUMAN → Amount is in the borderline zone; a manager
approval email has been sent. Not yet decided.
- APPROVED_BY_MANAGER → A human manager reviewed and approved.
- REJECTED_BY_MANAGER → A human manager reviewed and rejected.
OTHER FIELDS RETURNED:
- reason: Full explanation of the decision
- categoryLimit: The policy limit for the category
- remainingBudget: Budget left after approval (0 if rejected or pending)
- approverEmail: Who reviewed it (null for AI-only decisions)
- taskId: OIC task reference for audit trail
IMPORTANT:
- If expenseCategory is missing, ask the user before calling this tool.
- Never call this tool without both required inputs.
🔍 Updated System Prompt
The key addition is explicit instructions for each of the five decision values. Before this, the agent only knew how to handle APPROVED and REJECTED. Now it knows: when it sees PENDING_HUMAN, it must reassure the user politely, tell them who was notified, and set the right expectation about timing. This makes the agent feel professional and human rather than like a raw API response reader.
You are an Expense Approval Assistant for the company's finance department.
You use the check_expense_approval tool to evaluate all expense claims.
CATEGORY POLICY LIMITS (for reference):
- Travel: $1,000 | Meals: $75 | Office Supplies: $200
- Training: $500 | Software: $300 | Entertainment: $150 | Other: $100
BORDERLINE ZONE:
Each category has a borderline zone of approximately 80%–99% of its limit.
Expenses in this zone require a human manager's approval.
The tool handles this automatically — you just need to communicate it clearly.
BEFORE CALLING THE TOOL:
- Confirm you have both expenseAmount and expenseCategory.
- If category is missing, ask for it politely before proceeding.
DECISION HANDLING — how to respond for each decision value:
APPROVED:
State it is approved, mention the amount, category, and category limit.
Include the remaining budget from the tool response.
REJECTED:
State it is rejected, mention the category limit that was exceeded.
Advise the employee to seek manager pre-approval before resubmitting.
PENDING_HUMAN:
Do NOT say "PENDING_HUMAN". Instead, say something like:
"Your [Category] expense of $[Amount] is currently being reviewed
by your manager ([approverEmail]). You will receive an email once
they have made their decision. This typically takes up to 48 hours."
Be warm and reassuring. The employee is waiting — help them feel informed.
APPROVED_BY_MANAGER:
"Great news! Your [Category] expense of $[Amount] has been personally
reviewed and approved by [approverEmail]."
REJECTED_BY_MANAGER:
"Your [Category] expense of $[Amount] was reviewed by [approverEmail]
and unfortunately could not be approved at this time.
We recommend reaching out to them directly for further clarification."
RULES:
- Never copy raw decision values (PENDING_HUMAN etc.) into your response.
- Never make up a decision — always call the tool first.
- Policy questions need no tool call — answer from CATEGORY POLICY LIMITS above.
⌨️ Step 6 — Testing All Three Zones
With v3.0 activated and the agent pointing at it, run these four tests in order.
Each one covers a different decision path. Do not skip any — each one validates a different branch! 🎯
Test 1 — Green Zone (AI Auto-Approve) ✅
$250 Training is comfortably below $400 (the start of the yellow zone). The integration should return APPROVED immediately — no human task triggered. The agent responds in under 3 seconds.
{ "sessionId": "test-green", "userMessage": "Please approve my Training expense of $250 for an AWS course." }
Expected: "APPROVED — Your Training expense of $250.00 has been approved. The Training category allows up to $500. You have $250 remaining for this claim."
Test 2 — Yellow Zone (Human Task Triggered) 🟡
$450 Training is in the borderline zone ($400–$499). The integration should trigger the Human Task, return PENDING_HUMAN, and the manager's inbox should receive the approval email within seconds. The agent response must be a friendly "waiting for manager" message — not the raw code word.
{ "sessionId": "test-yellow", "userMessage": "I need approval for a $450 Training expense for an Oracle certification." }
Expected: "Your Training expense of $450.00 is currently being reviewed by your manager (manager@company.com). Because this amount is close to the Training policy limit of $500, it requires a manual review. You will receive an email once your manager decides. This typically takes up to 48 hours."
Open the email account you configured as the Human Task assignee. You should see the approval email with the two buttons. Click APPROVE. Then check the OIC Monitoring trace — the integration should have resumed and logged APPROVED_BY_MANAGER. ✅
Test 3 — Manager Clicks Approve → Confirmation
After the manager clicks Approve in the email, we simulate the employee following up. In a full production system, the employee would receive a callback email automatically. This test simulates that status check through the agent directly.
{ "sessionId": "test-manager-approved",
"userMessage": "My manager just approved my $450 training expense. What happens next?" }
Expected: "Great news! Your Training expense of $450 has been personally reviewed and approved by your manager. Please proceed with submitting your receipt through the expense portal, and the reimbursement will be processed in the next payment cycle."
Test 4 — Red Zone (AI Auto-Reject) ❌
$650 Training is well over $500. The integration must return REJECTED immediately — no human task triggered at all. Confirm by checking the OIC Monitoring trace: there should be no Human Task instance for this run.
{ "sessionId": "test-red", "userMessage": "Can you approve my $650 Training expense for a bootcamp?" }
Expected: "REJECTED — Your Training expense of $650.00 exceeds the Training category limit of $500. To proceed, please obtain pre-approval from your department manager before submitting, and resubmit with the approval reference attached."
🔍 Part 5 — Monitoring the Human Task
Human Tasks appear in two places in OIC Monitoring.
Knowing both locations saves significant debugging time — let us map them out! 🗺️
- Shows the integration run that triggered the Human Task
- Status shows as WAITING while manager is deciding
- Changes to COMPLETED after manager clicks
- Trace shows every step including the Human Task pause point
- The manager can approve/reject here as an alternative to email
- Shows task title, assignee, due date, priority
- Useful if the manager did not receive the email
- Audit trail shows who clicked what and when
- Dedicated view for all Human Task instances
- Filter by: status, assignee, date range, task name
- SLA tracking — shows tasks approaching expiry in red
- Export to CSV for compliance reporting
🔬 Troubleshooting Human Tasks — Common Problems
Something not working? Here are the five most common problems and their fixes:
| Symptom | Likely Cause | Fix |
|---|---|---|
| Manager email never arrived | SMTP not configured in OIC or email in spam | Check OIC email connection credentials; whitelist the sender domain |
| Manager clicked Approve but integration still shows WAITING | Action URL expired or wrong outcome label | Check outcome label names match exactly (case sensitive). Check token expiry in Human Task settings. |
| All expenses hitting Human Task (even $50 ones) | Yellow zone branch placed before the green branch in Switch | Reorder branches: narrow condition first, broad condition last |
| Agent says "PENDING_HUMAN" literally | DECISION HANDLING section missing or unclear in system prompt | Add explicit "Do NOT say PENDING_HUMAN" instruction and example phrasing |
| Task expired before manager acted | Manager on leave, no escalation configured | Set escalation path in Human Task to a backup approver or a distribution list |
✅ Best Practices for Human-in-the-Loop AI Agents
Before you ship this to production, here are the rules that experienced OIC developers follow.
DOs first, then DON'Ts — memorise these and you will save yourself hours of pain! 😅
- ✅ Always set an expiry time on Human Tasks. Never let a task wait indefinitely. 48 hours with escalation is a sensible default.
- ✅ Make the approval email self-contained. The manager should be able to decide from the email alone — no system login needed.
- ✅ Translate decision codes into plain English in the system prompt. Employees should never see PENDING_HUMAN. The agent is the interpreter.
- ✅ Log the approver's email in the response. This creates an audit trail that compliance teams will appreciate.
- ✅ Test the expiry path. Set a very short expiry (5 minutes) in your test environment and confirm the escalation fires correctly.
- ✅ Define the borderline zone as a configurable variable. Finance teams change thresholds. A variable in an OIC lookup table means no integration redeploy.
- ❌ Don't route everything through a Human Task. If 90% of expenses trigger it, managers will rubber-stamp without reading. Reserve it for genuinely borderline amounts.
- ❌ Don't assume the manager will always click the email. Always configure an alternative approval route through the OIC Workspace, and always set an escalation path.
- ❌ Don't let the LLM make the final decision on borderline amounts. The point of a Human Task is to take that decision away from the AI. Asking the agent to "use its judgement" defeats the purpose.
- ❌ Don't forget to update the tool description and system prompt when adding new decision values. The LLM only knows what you tell it. An unexplained new value will produce confusing responses.
When uploading data or configuring Human Tasks in OCI/OIC that involve real employees and real expense amounts — never include personally identifiable information (PII) in test environments unless you have proper data governance approvals in place. Use synthetic test data (John Smith, $450) for all development and QA runs.
❓ Frequently Asked Questions
It's a built-in Oracle Integration Cloud activity that sends a notification to an assigned approver, pauses the running integration without consuming compute, and resumes automatically the moment the approver clicks Approve or Reject.
It splits amounts into green (comfortably within policy, auto-approved), yellow (borderline, routed to a human via a Human Task), and red (clearly over policy, auto-rejected) — so an AI Agent only escalates the genuinely uncertain cases to a person.
Because OIC evaluates Switch branches top to bottom and the first matching branch wins. A broad condition placed before a narrow one will silently swallow it — the yellow (borderline) branch must always be placed before the green (approve) branch, not after.
The system prompt's DECISION HANDLING section explicitly tells the agent never to repeat raw decision codes like PENDING_HUMAN, and instead gives example phrasing for reassuring the employee that a manager has been notified and will respond within a set time frame.
No — over-triggering Human Tasks causes alert fatigue, and managers will start rubber-stamping without reading. Reserve the yellow zone for genuinely borderline amounts where a human's judgment adds real value, not for the majority of routine cases.
📝 Quick Summary — What We Learned
-
Three-Zone Model →
Green (auto-approve), Yellow (human review), Red (auto-reject).
The yellow zone is defined as 80%–99% of the category limit. - OIC Human Task → A special activity that emails the manager, pauses the integration, and resumes when the human clicks. Like a sleeping messenger — it waits patiently for the human's reply.
- Integration v3.0 → The only thing that changes from v2.0. Agent, LLM, and tool registration stay exactly the same.
- Five Decision Values → APPROVED, REJECTED, PENDING_HUMAN, APPROVED_BY_MANAGER, REJECTED_BY_MANAGER. Each one tells the AI agent exactly what happened so it can phrase its reply correctly.
- System Prompt — DECISION HANDLING section → Translates raw decision codes into warm, plain-English responses. Never let the agent say "PENDING_HUMAN" to a real employee!
- OIC Monitoring → Check Observability → Instances for integration traces, My Tasks for the manager's approval queue, and Observability → Human Tasks for SLA and audit reporting.
- When to Use Human-in-the-Loop → Only for genuinely borderline cases. Over-triggering causes alert fatigue. Reserve it for the grey zone where stakes are real and a human eye adds value. 👁️
Comments
Post a Comment