A supplier sends an invoice PDF, a delivery photograph, and a voice message explaining a shortage. An Oracle Integration 3 (OIC) workflow can route these inputs through the relevant AI services, extract useful evidence, validate the results, and prepare a procurement exception for resolution. But completing each service call successfully does not mean the business case is correct, the transaction is safe to post, or the entire workflow can recover after a timeout.
Production engineering introduces a different set of questions. What happens if document extraction succeeds but speech transcription fails? If a request times out after the receiving system has committed a transaction, should OIC retry? Can support staff diagnose the failure without exposing supplier information? And how do we know a model or configuration change has not degraded the result?
This tutorial develops an operational design for those questions. It uses a fictional procurement workflow to connect previously implemented OCI AI capabilities with durable state, evidence-based quality gates, deterministic business controls, controlled recovery, observability, cost measurement, and release governance.
Start here: what the three Oracle products do
OCI is Oracle Cloud Infrastructure, the cloud platform. OCI AI services analyze documents, images, audio, or text. Oracle Integration 3 (OIC Gen3) connects those services to business applications and applies workflow rules. Think of OIC as the coordinator, the AI service as a specialist, and the procurement system as the official record keeper. This guide assumes you can open an existing non-production OIC integration, use its mapper, and configure a connection. If those tasks are new, first follow the linked OIC user guide; this article explains the next layer of reliability.
Before You Begin: A Plain-English Orientation
You do not need to memorize every term before starting. Use this small glossary as you work through the design. The examples are fictional and show patterns to adapt, not settings already deployed in a tenant.
| Term | Meaning in this tutorial |
|---|---|
| Canonical case contract | The application's own standard record for one business case. It connects the source, processing steps, decisions, and target transaction. |
| Provenance | The evidence showing where a result came from and which operation or configuration produced it. |
| Quality gate | A defined check that decides whether a result may continue, needs review, or must stop. |
| Idempotency | A business design that makes a repeated request safe, for example by preventing the same invoice from creating a second transaction. It requires real duplicate controls; a key by itself is not enough. |
| Reconciliation | Checking the destination or provider's actual state to resolve whether a request took effect after a timeout or lost response. |
| RAG | Retrieval-augmented generation: retrieving relevant approved information, then using it as context for a generated answer. |
| p95 latency | The time at or below which 95% of measured operations finished; the slowest 5% took longer. |
A safe learning order is: map the current workflow, write down the case states, define the business checks, then test duplicate and failure paths in a non-production environment using synthetic data. Do not begin by enabling every AI service or experimenting with live financial writes.
Choose a reading path. For your first pass, read shared setup (section 3), the invoice exercise (4.4), quality and business controls (5–6), and the first practical exercise (15.1). Then work through security, retries, recovery, monitoring, and release controls before production. The invoice path ends with a recorded decision; a real approval application and financial write require separate implementation.
| Term | Plain-English meaning |
|---|---|
| Tenancy / compartment | Your organization’s OCI environment / a logical grouping used to organize resources and scope access. |
| Region / realm | A geographic deployment area / a collection of regions sharing an isolation and trust boundary. They are different availability checks. |
| IAM / principal / dynamic group | Access management / the identity making a call / rule-based membership for resource identities. |
| Bucket / namespace / object name | An Object Storage container / its tenancy-level naming scope / the exact key identifying a stored file. |
| Trigger / invoke / mapper | How OIC starts a flow / how it calls another system / how it translates source fields to target fields. |
| Durable state / atomic claim | A record that survives an execution ending / a single indivisible operation that allows only one worker to claim the same work. |
| Deterministic / synthetic / PII | Rule-based and reproducible / invented for testing / personally identifiable information. |
1. What You Will Build
The practical outcome is a production-readiness evidence pack for one existing OCI AI integration solution. You will examine its architecture, define a canonical case contract, establish acceptance and review rules, design safe retries and reconciliation, and prepare operational dashboards, failure drills, release gates, and a support runbook.
The reference workflow follows this business sequence:
| Stage | Engineering responsibility | Completion evidence |
|---|---|---|
| Intake | Register the business case and secure its source artifacts. | Case ID, artifact references, source fingerprint. |
| AI processing | Execute only the capabilities justified by the input and business need. | Operation status, request/job references, result artifact. |
| Quality control | Assess output completeness, consistency, and evidential support. | Gate decision and reason codes. |
| Business validation | Check authoritative procurement records and approval rules. | Validation evidence and approval state. |
| Commit and support | Control target writes, reconcile uncertain outcomes, and monitor recovery. | Target transaction reference, audit trail, support evidence. |
The expected result is a reproducible set of engineering decisions and operational checks, not a claim that a real tenant has passed production testing.
Scope and evidence boundary
This is an architecture and operations tutorial with one concrete primary route: an OIC-native OCI Document Understanding action for invoice extraction, followed by application-owned normalization, deterministic purchase-order validation, and a quality gate. The wider production hardening guidance still assumes that the implementing team will supply its real target-system contract and test evidence. No tenant or runtime results were provided here. Example identifiers, normalized values, state names, contracts, and test outcomes are illustrative unless explicitly labelled as documented Oracle behavior.
2. In This Post
- Before You Begin: A Plain-English Orientation
- What You Will Build
- In This Post
- Before You Begin — Shared Setup
- Select the Right Combination of OCI AI Services
- Primary Route: Invoice Extraction and Quality Gate
- Canonical Contracts, Provenance, and Quality Gates
- Authoritative Data, Human Review, and Controlled Writes
- Identity, Privacy, Residency, and Trust Boundaries
- Retries, Throttling, Concurrency, and Circuit Breaking
- Duplicate Work, Uncertain Outcomes, and Recovery
- Observability, Correlation, and Support Runbooks
- Combine the Controls and Run Failure Drills
- Throughput, Latency, Capacity, and Unit Economics
- Versioning, Promotion, Rollback, and Model Drift
- Deterministic Orchestration Versus Agents
- Completion Checklist and What Comes Next
- Five Useful FAQs
- Verified References
- Finally — Summary
3. Before You Begin — Shared Setup
3.1 Establish the actual environment baseline
Use the current Oracle Integration 3 documentation as the public documentation baseline. That is not proof that a particular tenant is on a given release or patch. Record the deployed OIC release, edition, enabled capabilities, OCI region and realm, and relevant service/API versions from the real environment.
Keep these version concepts separate:
- OIC release and patch: the integration platform's deployed capabilities and limitations.
- OCI service API version: the contract used by a particular REST operation.
- Model or model-configuration version: the inference implementation or custom model configuration selected by the application, where applicable.
- Tenant and region availability: whether the required action, model, endpoint, permissions, and capacity are actually available to the environment.
3.2 Build an environment manifest
Create one controlled manifest for the solution. Store approved identifiers and configuration references, but do not place passwords, private keys, access tokens, or raw sensitive supplier content in the manifest.
| Inventory item | What to record | Why it matters |
|---|---|---|
| OIC solution | Project, integrations, versions, connections, lookup/configuration dependencies. | Reproducible deployment and rollback. |
| AI operations | Service, exact operation, native action or REST route, API version, endpoint, model/configuration reference. | Detect contract and lifecycle changes. |
| Identity | OIC caller, connection authentication, OCI access policies, storage permissions, target credentials owner. | Prove which principal can perform each operation. |
| Data | Approved input locations, classifications, region restrictions, artifact/result retention, deletion owner. | Control information exposure and lifecycle. |
| Business controls | Authoritative records, validation rules, approval thresholds, target transaction keys. | Prevent AI output from becoming unverified business truth. |
| Operations | Support owner, alert route, service limits, recovery window, cost baseline, runbook location. | Ensure somebody can restore service safely. |
3.3 Confirm the integration route
For every implemented capability, identify whether the workflow uses an OCI AI activity exposed by OIC, a REST Adapter invoke, or a separately implemented API client. This matters because the visible configuration fields, authentication configuration, available operations, and response envelopes may differ by route.
Use the documented contract for the route actually deployed. A successful standalone REST request does not prove that the OIC mapping, runtime identity, fault handler, business correlation, or target write is correct. Conversely, an available native action does not prove that every underlying service option is exposed by that action.
Native OCI AI actions have prerequisites and availability boundaries. Oracle's OIC prerequisites require an identity-domain-enabled tenancy, a dynamic group whose matching rule uses the OAuth application's client ID for the Oracle Integration instance, and an IAM policy granting access to the specific OCI AI service. The current AI feature availability page says availability varies by OIC edition and region; its OCI AI service action table currently states OC1 commercial-realm availability and lists region support by service.
3.4 Separate business identifiers from secrets and payloads
Choose a durable business case ID before processing starts. Add OIC instance identifiers, OCI request IDs or asynchronous job identifiers where available, artifact references, and target transaction IDs as the case progresses. These are different identifiers with different owners; do not assume one will automatically be copied into every system.
Use synthetic inputs for initial drills. Keep raw invoice contents, access tokens, full prompts, and unredacted supplier messages out of ordinary diagnostic identifiers and notifications.
4. Select the Right Combination of OCI AI Services
Architecture selection begins with the required business evidence, not with the number of AI services available. Each service should address a distinct information-processing need. Introducing another service adds latency, cost, dependencies, data movement, and additional failure modes.
Kid-friendly analogy
Imagine a school office receiving a permission slip, a photograph, and a voice message. The office uses the right tool for each item instead of sending everything to every available helper.
In this OCI AI integration, this means: Select a service for a specific input and output requirement, and omit redundant processing steps that do not improve a measurable business outcome.
4.1 Use the business need to select the capability
| Capability | Appropriate role | Boundary to preserve |
|---|---|---|
| OCI Document Understanding | Extract document text, fields, tables, or other supported document information. | Extraction is not proof that a value is accurate or agrees with an approved purchase order. |
| OCI Language | Apply the specific supported text-analysis, entity, sentiment, or translation operation needed. | An entity, sentiment label, or translation does not establish commercial meaning or contractual breach. |
| OCI Vision | Analyze images using the operation appropriate to the required visual evidence, such as supported image analysis or OCR. | A detected label or text region is not a verified receiving record or proof of product condition. |
| OCI Speech | Transcribe supported audio or use another specifically supported speech operation. | A transcript may contain recognition errors and does not prove the speaker's authorization. |
| OCI Generative AI | Perform a bounded generative task such as a supported classification, summary, or structured transformation. | Plausible generated text is not authoritative data, a validated calculation, or an approval. |
| OCI Generative AI Agents RAG action | Retrieve relevant knowledge and generate an answer grounded in the approved corpus for the supported scenario. | Retrieval and citations do not independently prove that an answer fully supports a business decision. |
The table describes architectural responsibilities, not a guarantee that a particular operation or field is available in every OIC release, region, model, or native action. Check the current operation guide and tenant configuration for the implementation being hardened. The linked OIC category guide documents the native action family; the separate OCI Generative AI Agents RAG-tool guide explains the underlying retrieval capability. The presence of a RAG action does not authorize a target-system write.
4.2 Define the minimum useful pipeline
For an invoice exception, a reasonable sequence might be document extraction, deterministic normalization, authoritative purchase-order validation, and human review where required. A delivery photograph may need Vision only if it provides evidence that cannot be obtained from receiving records. A voice note may need Speech if the information is operationally necessary and not already available as text.
Add Language analysis when a specific text operation provides measurable value. Add generative summarization when an operator benefits from a concise explanation that remains traceable to source evidence. Add RAG when a decision requires answering questions against an approved knowledge corpus, such as a published procurement policy.
Do not use a model to re-extract, reclassify, or re-summarize a field simply because another model call is possible. Before adding an operation, record the expected improvement, extra cost, failure impact, and acceptance test that would demonstrate the improvement.
4.3 Choose the processing boundary
- Inline processing: appropriate only when the specific operation, request size, response time, and OIC invocation contract support it.
- Asynchronous processing: useful for supported long-running or batch operations. The design must persist the job reference, inspect terminal status, retrieve outputs, and reconcile all items.
- Human review: required when the configured quality or business policy says that automation must stop for a person to decide.
- Controlled write: separate from inference and retrieval. It uses the target system's documented contract, authorization, validation, and duplicate-prevention strategy.
Checkpoint: Every service in the design has a defined responsibility, input, output, evidence source, failure action, and owner. If two operations have no distinct acceptance criterion, investigate whether one can be removed.
4.4 Primary Route: Invoice Extraction with an OIC-Native Document Understanding Action
This route makes the operations design concrete. A supplier invoice is already stored in OCI Object Storage. OIC supplies the stored object reference to the native OCI Document Understanding action, maps the extraction into an application-owned case record, looks up the authoritative purchase-order values, and routes the case according to deterministic checks. The example stops a mismatched invoice for review; it does not invent or perform a production write.
What you need: an OIC Gen3 project in a non-production environment; a request or event trigger that supplies the business case ID and Object Storage object name; a test invoice in a permitted bucket; the appropriate Document Understanding permissions and region; and a safe way to retrieve a test purchase-order record. The actual purchase-order connector/API and its schema depend on your business system, so use that system's documented contract rather than copying an invented endpoint from this article.
Step 1 — Confirm the action can run in this environment
Keep the first test small: use a one-page synthetic English invoice PDF, clearly printed, with no password protection, containing a supplier, invoice number, currency, and total. Check the service’s Document Understanding limits and the native action’s supported formats. The current service limits list synchronous input at 8 MB and five pages or fewer, including Object Storage input. Storing a larger file in a bucket does not make a synchronous action a batch processor. For larger eligible workloads, evaluate the supported Processor Job route and its different limits; also check OIC’s own limits.
- Create a dynamic group with a matching rule that uses that client ID (Oracle's example shape is
resource.id = 'client_ID', with your real ID substituted). Create the service-specific IAM policy from Oracle's prerequisite guide. Do not paste a broad policy from an unrelated service. - Confirm that the OIC integration can read the intended bucket/object and that the object retention and region choices satisfy your data policy. IAM access to Document Understanding does not automatically grant Object Storage access or permission to write to your procurement system.
Follow Oracle's OIC AI service prerequisites for the exact identity-domain and policy setup, and the Document Understanding action guide for the supported fields in your release.
Step 2 — Add and configure the native action
- In OIC, open Projects, select the non-production project, and open the integration that receives the case envelope. On the integration canvas, drag OCI Document Understanding from Actions to the point after input validation, or use the add-action control at that point in the canvas.
- Give the action a descriptive name such as
AnalyzeInvoiceWithConfidence. In Select Categories, choose Pre-trained Models. In the action wizard, choose Analyze document (with confidence score). - Select the region in which the model is available, then the OCI compartment configured for this OIC instance's service access. Choose Invoice as the document type and Object storage as the input source. Select the input bucket and namespace; finish the wizard.
- Do not assume the OIC region and the Document Understanding model region must always be identical. The action guide documents a region selection and, for supported routes, a runtime region override. Use cross-region processing only where the release, region, service, security controls, and data-residency requirements explicitly permit it.
This route uses the pretrained invoice model. A custom model is appropriate only if your document fields and supported model features require it and the model has already been created and evaluated. Keep a model-selection change separate from a reliability change so test results remain interpretable.
Step 3 — Map the source object and normalize the response
- In the request mapper for the Document Understanding action, map the incoming application field that identifies the invoice object to the target Object Name element. For example, the application-owned input can supply
intake/PROC-TEST-002/invoice.pdf. Bucket and namespace are configured in the wizard unless your supported mapping explicitly overrides them. - In the response mapper, inspect the source schema generated for the selected action and map the actual returned invoice fields and their confidence elements into your application-owned case structure. Do not copy guessed field names from another service response or assume all document types return identical fields.
- Keep the business case ID, source artifact reference/fingerprint, operation name, processing state, and quality decision alongside the normalized values. Store the detailed response only where required by the audit and retention policy; do not put the raw invoice or entire response into ordinary notifications.
- Use the real purchase-order read operation to retrieve the authoritative supplier ID, PO status, currency, line quantities, and amounts needed by the business rule. The output of document extraction is a candidate value, not a substitute for that lookup.
Step 4 — Apply a deterministic quality gate
Worked example: exactly what the comparison means
For this training case only, the purchase order has one line, is fully received, and allows one full invoice. Both records use INR; tax, freight, and discounts are zero; the approved difference tolerance is INR 0.00. The invoice requests INR 1,080.00; the authoritative amount for that same billable scope is INR 1,060.00. The difference is INR 20.00, so the case needs review. Real invoices may legitimately cover only part of a PO or include tax and charges. Compare the eligible lines, receipts, and amounts under your matching policy; total-PO equality is not a general invoice-validation rule.
Implement two decisions: technical extraction quality first, then business matching. A readable, high-confidence extraction can pass the first decision and fail the second. In the example response below, qualityGate is a combined application routing outcome; it is not an OCI service field or a grant of approval.
Use ordinary integration logic and the authoritative purchase-order data to decide the next state. At minimum, check that required invoice fields exist, data types and currency are valid, the supplier and PO can be resolved, and the relevant amounts/quantities agree within the documented business tolerance. If a confidence score is available, use a threshold only after calibrating it on representative labeled examples.
| Synthetic test | Expected gate decision | Why |
|---|---|---|
| All required fields are present; supplier and PO match; amounts pass business rules; all approvals are satisfied. | PASS to the next authorized workflow step. | The extracted information passed structural, deterministic, and authorization checks. |
| Invoice total is INR 1,080.00, but the comparable billable amount is INR 1,060.00 under the stated full-invoice test policy. | REVIEW with reason code PO_TOTAL_MISMATCH; no target write. | The values are intentionally inconsistent. A generated explanation cannot override the numerical check. |
| Invoice number, supplier, or total is missing or cannot be validated. | REVIEW or FAIL according to the documented input policy. | Required evidence is absent or unsuitable for automated processing. |
For a failed or review gate, save the reason code and references to the extracted field and authoritative record. For a passing gate, still apply the workflow's current authorization and approval checks before a privileged target write. If you have not supplied the target system's verified API/adapter contract, leave the write step as an explicit, blocked boundary rather than inventing endpoint paths or request fields.
Step 5 — Test and capture evidence
| Build this in the training integration | What to verify |
|---|---|
| Trigger and input validation | Supply the application envelope below. Require nonempty identifiers; allow only approved object locations. Configure a safe case ID as an OIC business identifier. |
| Document Understanding action and mapping | Use the action’s generated schema. Map actual extracted values and confidence elements; retain source evidence. Missing values must not default to a fabricated zero or approval. |
| Purchase-order read | Retrieve the test PO from a documented read operation. For an isolated first lab, a clearly labelled fixed synthetic fixture is acceptable; it does not validate a real PO connection. |
| Assign / mapper, then Switch | Normalize the values and compute the documented comparison. Branch to PASS, REVIEW, or FAIL with reason codes. The exact XPath paths depend on your generated schema. |
| Persist decision and end | Record the case outcome and evidence using your selected store/API. Leave financial writes absent from this first exercise. A recorded PASS means eligible for the next check, not paid. |
| Scope and fault handling | Capture a sanitized fault, persist the recovery state, and apply the error policy. A handled business REVIEW can finish technically successfully while the business case remains held. |
Use this application-owned input envelope for a non-production test trigger. It is not the native Document Understanding API request or a required OIC trigger schema; map the equivalent fields in your actual integration:
{
"caseId": "PROC-TEST-002",
"sourceRecordId": "SUPMSG-TEST-002",
"invoiceObjectName": "intake/PROC-TEST-002/invoice.pdf",
"purchaseOrderId": "PO-TEST-041",
"sourceVersion": "test-source-v1"
}
For the synthetic mismatch case, a normalized application-owned output could look like this. The values, field names, confidence numbers, and reason code are deliberately illustrative; they are not a captured OCI response or a promise that the model will return these exact values.
{
"caseId": "PROC-TEST-002",
"documentExtraction": {
"status": "COMPLETED",
"invoiceNumber": { "value": "INV-TEST-007", "confidence": 0.94 },
"supplierName": { "value": "Northwind Components", "confidence": 0.96 },
"invoiceCurrency": "INR",
"invoiceTotal": { "value": "1080.00", "confidence": 0.92 }
},
"purchaseOrderValidation": {
"purchaseOrderId": "PO-TEST-041",
"currency": "INR",
"comparableBillableAmount": "1060.00",
"tolerance": "0.00",
"matchingRuleVersion": "training-full-invoice-v1",
"result": "MISMATCH"
},
"qualityGate": "REVIEW",
"reasonCodes": [ "PO_TOTAL_MISMATCH" ],
"targetWriteState": "NOT_SUBMITTED"
}
- Activate the test integration in the non-production environment and submit the synthetic case using the trigger's actual contract.
- Open the OIC instance and verify the request mapping, selected Document Understanding action, response mapping, purchase-order lookup, and quality-gate branch. Inspect only the payload detail allowed by your tracing and data policy.
- Capture the OIC instance ID, safe case ID, configured action and region, mapped status, gate reason code, and proof that the mismatch did not reach the target-write step.
- Repeat with missing file, unsupported input, access denied, and a valid matching PO. Record expected versus actual outcome. The expected sample above is not test evidence.
Hands-on route boundary: the OIC-native extraction, normalization, authoritative lookup, and gate are the complete primary AI-processing path illustrated here. A final write must use the real procurement system's documented operation, identity, approval enforcement, and idempotency contract; those tenant-specific facts were not supplied and are intentionally not fabricated.
5. Canonical Contracts, Provenance, and Quality Gates
5.1 Separate the business case from each AI operation
A canonical contract is the application-owned representation of a case that remains stable even if an internal AI service, model, or invocation route changes. It is not a replacement for the service's native request or response schema. It is a boundary contract for business state, provenance, outputs, and decisions.
Kid-friendly analogy
Imagine a school office assigning one number to a lost-property case. The librarian, classroom teacher, and office administrator can each add their findings without creating three unrelated cases.
In this OCI AI integration, this means: Keep one stable business case ID and store each operation's route, version, state, evidence, and output reference against that case.
A canonical case should normally record:
- A stable case ID, correlation ID, contract version, and idempotency key.
- Source-system identity, source-record reference, artifact version or fingerprint, and permitted content location.
- For each operation: service, operation, invocation route, API/model/configuration version when applicable, timestamps, processing status, and provider request or job reference.
- Result artifact references, per-operation quality evidence, deterministic validation outcomes, review status, approval provenance, and target transaction reference.
- A terminal or recovery state that the business workflow can interpret without guessing what happened in a remote service.
5.2 Example application-owned case contract
The following JSON is a synthetic application contract for this tutorial. It is not an Oracle service API payload, a native OIC mapper schema, or a claim that every OCI operation returns these fields. The example deliberately keeps detailed output in referenced artifacts rather than copying potentially sensitive content into the case record.
{
"contractVersion": "1.0",
"caseId": "PROC-2026-00042",
"correlationId": "corr-00042",
"idempotencyKey": "hash-of-business-key-and-source-version",
"state": "QUALITY_REVIEW_REQUIRED",
"source": {
"sourceSystem": "supplier-portal",
"sourceRecordId": "SUPMSG-00042",
"artifacts": [
{
"artifactId": "ART-00042",
"objectRef": "intake/PROC-2026-00042/invoice.pdf",
"sourceVersion": "test-source-v1",
"sha256": null,
"mediaType": "application/pdf"
}
]
},
"steps": [
{
"stepName": "invoice-extraction",
"service": "OCI Document Understanding",
"route": "OIC_NATIVE_ACTION",
"status": "COMPLETED",
"apiVersion": null,
"providerModelVersion": null,
"applicationConfigVersion": "invoice-route-v1",
"providerRequestOrJobId": "opaque-provider-reference",
"outputRef": "results/PROC-2026-00042/extraction.json",
"qualityGate": "REVIEW",
"reasonCodes": [
"PO_TOTAL_MISMATCH"
]
}
],
"decision": {
"state": "HUMAN_REVIEW",
"approvedBy": null,
"reasonCodes": [
"PO_TOTAL_MISMATCH"
]
},
"target": {
"system": "authoritative-procurement-system",
"transactionId": null,
"state": "NOT_SUBMITTED"
}
}
The values such as QUALITY_REVIEW_REQUIRED, COMPLETED, and HUMAN_REVIEW are application-defined states. They are not universal OCI job states. Map each service's documented lifecycle into your contract explicitly, including its failures and terminal states.
A null provider version means it has not been captured or is not exposed by the selected route. Record the reason in the real manifest. invoice-route-v1 identifies your own configuration, not an Oracle model release. Compute a real SHA-256 only from the actual source bytes; the synthetic case intentionally leaves it empty. For an unambiguous storage reference, retain namespace, bucket, object name, and an immutable source version or verified fingerprint. Prevent source replacement between validation and processing.
5.3 Preserve provenance without retaining everything forever
Provenance explains how an output was produced. For a document extraction, the relevant evidence may include the source artifact version, page or region where a value originated, operation/model configuration, request or job identifier, and the stored response artifact. A generative result may additionally need a prompt-template version and retrieval-corpus revision. Record these only where relevant to the operation and available in the documented contract.
A SHA-256 fingerprint can help determine whether a binary source artifact has changed. It does not authenticate the source, prove that its contents are true, or independently establish that a different encoding of semantically identical content has the same hash. If semantic duplicate detection is required, define and test a separate canonicalization rule.
For asynchronous work, retain the original service job identifier and result-artifact references for the duration required to reconcile and audit the case. A provider job reference, an OIC instance ID, and an Object Storage object reference are distinct values. Record the relationship explicitly.
5.4 Define quality gates for actual output semantics
A quality gate evaluates whether an operation's output is suitable for its next processing step. Gate logic must reflect what the actual operation returns, not a generic assumption that every AI output has a comparable confidence score.
| Gate outcome | Application rule | Next action |
|---|---|---|
| PASS | Required output is present, structurally valid, and meets the operation-specific acceptance criteria. | Proceed to the next approved step. |
| REVIEW | Output exists but is ambiguous, incomplete, inconsistent, or outside the validated automatic-processing policy. | Retain evidence and route to the appropriate reviewer. |
| FAIL | The operation failed or the result cannot satisfy a mandatory contract or safety requirement. | Use the defined recovery, quarantine, or final-failure path. |
| PARTIAL | Some independent steps or items succeeded, while others are unresolved. | Preserve successful work; recover only the outstanding work where possible. |
Examples include required invoice fields being absent, an image not meeting an input requirement, an unsupported input language, a transcript missing a required segment, or a policy answer lacking evidence for a material claim. Use each service's actual response structure and documented error behavior to implement the gate.
Where a score exists, use a labeled validation set to determine whether it helps discriminate acceptable output from output needing review. A score of 0.95 is not proof of 95% business correctness for your documents, language, suppliers, or operational conditions. Track false acceptance and false rejection, and set thresholds according to the cost of each error.
Checkpoint: Every result can be tied to a source, an operation and version, an output reference, and an explicit gate outcome. Partial success is visible instead of being misreported as complete success.
6. Authoritative Data, Human Review, and Controlled Writes
6.1 Separate technical quality from business approval
Technical quality asks whether an extracted value or generated answer is suitable for the next step. Business approval asks whether the proposed action is permitted under the organization's actual rules. These are separate decisions, and they may require different evidence and different accountable owners.
Kid-friendly analogy
A student may fill in a library form neatly and correctly, but that does not mean they may take a restricted book home. The librarian still checks the borrowing rules and the student's permission.
In this OCI AI integration, this means: An acceptable AI result can advance to deterministic validation, but only the authorized business process can decide whether a purchase, payment, or other privileged transaction is permitted.
6.2 Define authoritative sources for each important field
For a procurement workflow, identify the system of record rather than using extracted text as the authority for every value.
| Value or decision | Example authoritative check | AI's permitted role |
|---|---|---|
| Supplier identity | Approved supplier master data and identifiers. | Extract a candidate value for exact or controlled matching. |
| Purchase order | Authorized purchase-order and line records. | Read a reference from the invoice and surface mismatch evidence. |
| Received quantity | Approved receiving or inventory records. | Interpret relevant delivery evidence where justified. |
| Invoice total | Deterministic reconciliation of parsed values, business rules, and authoritative records. | Extract candidate amounts and supporting document references. |
| Policy interpretation | Approved policy version plus any mandatory business-system rule. | Retrieve evidence and explain relevant policy language. |
| Release or approval | The designated workflow, authorization model, and approval record. | Prepare a summary or recommendation without granting the approval. |
6.3 Keep deterministic validation outside model judgment
Implement checks such as supplier-ID existence, purchase-order status, permitted currency, quantity reconciliation, arithmetic totals, policy thresholds, and required approval level in the appropriate deterministic integration or target-system control plane.
For numerical comparison, define the permitted tolerance, rounding convention, currency precision, tax treatment, and source of each operand. Do not ask a generative model to decide whether two amounts match when a deterministic calculation can answer the question reproducibly.
Parse monetary text with the documented locale and use exact decimal arithmetic or integer minor units with the correct currency scale. The example JSON deliberately represents amounts as decimal strings: parse and validate them before comparison; do not compare the strings lexically or use binary floating-point for financial equality. Reject an ambiguous currency or number format. Re-read mutable approval, receipt, and PO facts before committing when required by the business transaction contract.
A review outcome should carry reason codes and evidence references. For example, PO_TOTAL_MISMATCH identifies the reason for the hold; a reference to the parsed invoice field and current purchase-order record helps the reviewer understand it.
6.4 Make every privileged write independently safe
A REVIEW value does not create a human task. Persist the held case and connect it to an implemented review queue or approval application. Record assignee, permitted decisions, corrected values, decision time, and the source/rule version reviewed. Resume only through an authenticated path that rechecks permissions and current business facts. For the first lab, recording the review outcome is sufficient; the case remains held until that review mechanism exists. Select any Oracle human-review capability only after checking its availability and setup requirements.
Before an OIC invoke creates or changes a target record, validate the current authorization, business key, required fields, and approval state. The target system's own security and business rules remain authoritative. A generated explanation, prompt instruction, retrieved document, or AI tool result is never an independent grant of permission.
For a controlled write, define how the integration detects an existing transaction, how it identifies an uncertain outcome, and who may authorize a correction or manual retry. Do not claim exactly-once processing unless the end-to-end contracts actually establish that property.
7. Identity, Privacy, Residency, and Trust Boundaries
7.1 Inventory each identity separately
An enterprise AI workflow can cross several authorization boundaries. The inbound supplier or application identity, the identity used by an OIC connection, the OCI service caller, the Object Storage reader or writer, the reviewer, and the target-system write identity must not be treated as one automatic identity chain.
Kid-friendly analogy
A school visitor's badge may allow entry into reception, but it does not automatically open the library, the staff room, and the office safe. Each area has its own permission check.
In this OCI AI integration, this means: Verify the actual caller, authentication mechanism, resource permissions, and target authorization at each boundary instead of assuming that access to OIC or one OCI service authorizes all other actions.
| Boundary | Verify | Required evidence |
|---|---|---|
| Inbound request to OIC | Trigger authentication, caller restrictions, and input validation. | An unauthorized or invalid caller cannot reach privileged processing. |
| OIC to OCI AI | The actual native-action or REST route, its documented authentication, and required IAM permissions. | The permitted operation works and an unauthorized operation is denied. |
| OIC to Object Storage | Read/write scope, bucket and object access, encryption, and retention policy. | A processor can access only the artifacts required for its task. |
| Human review | Reviewer identity, case-level access, allowed decisions, and audit evidence. | An unassigned or unauthorized reviewer cannot approve the case. |
| OIC to business system | Target identity, permitted operations, approval enforcement, and duplicate protection. | An unapproved case cannot create the privileged transaction. |
OCI policies follow a subject, verb, resource, location, and optional condition structure. See Oracle's IAM policy syntax and Identity and Access Management overview. Scope each real policy to the identity, resource family, compartment, and operation needed by the verified route. A broad example policy from a tutorial is not automatically a least-privilege policy for your architecture.
For OCI Generative AI, Oracle documents a model-level IAM control using the target.model.id condition for specified inference resource types. This is a specific control, not a universal condition that restricts every OCI AI service or every resource within the Generative AI resource family. See Limiting Model Inference Access with IAM Policies.
7.2 Treat all external content as untrusted
Supplier messages, uploaded documents, image text, transcripts, and retrieved policy fragments are input data—not privileged instructions. In generative workflows, a document can contain prompt-injection text that attempts to redirect the model or influence a later tool call. Retrieval relevance and a model's willingness to follow instructions do not establish authorization.
Keep tool permissions narrow. Separate answer generation from privileged writes. Restrict retrieval to the caller's authorized knowledge set. Validate all generated structured fields against the application schema, and enforce critical controls with deterministic integration and target-system checks. An instruction embedded in a document must not bypass approval, change the caller's permissions, or authorize a payment.
7.3 Decide privacy and data residency before selecting a route
For each artifact, define its classification, purpose, allowed destination, permitted transformation, retention period, and deletion owner. Then verify that the selected OIC capability, actual OCI operation, model or serving mode, region, target system, and any external provider all satisfy those requirements.
Do not infer residency solely from a product name or from the location of the integration designer. Review the documented processing path for the actual service and route. Oracle's regions and availability documentation explains that resource availability varies by region; region and realm must be verified rather than assumed.
For PII protection, distinguish these controls:
- Detection: identifies sensitive items that the operation can recognize. Detection can miss or misclassify content.
- Masking or replacement: changes detected values in a particular representation. Validate both the transformed text and any metadata, faults, logs, and retained originals that could still expose the value.
- Tokenization: may enable reversible reference-based substitution when an appropriately controlled token vault exists. It is not the same as irreversible anonymization.
- Deletion and retention: require a lifecycle policy for source documents, derived outputs, job artifacts, logs, and business records. Deleting one resource does not prove all its related artifacts have been deleted.
OIC tracing can expose payloads. The activation guide lists Production activity-stream retention at 32 days (184 days for Healthcare), Audit at eight days with trigger/invoke wire payloads, and Debug at 24 hours with detailed payloads. After Debug data is purged, minimal instance information remains for 32 days. Its automatic return to Production can occur later than 24 hours if no messages are processed; explicitly reset tracing when debugging ends. Verify configured retention separately, and set lifecycle policies for service jobs, stored files, exports, and downstream copies.
Checkpoint: The security review identifies every caller, every relevant permission boundary, every data destination, and every retention owner. Negative tests prove that unauthorized access is denied and that routine diagnostics do not leak sensitive content.
8. Retries, Throttling, Concurrency, and Circuit Breaking
8.1 Classify the failure before deciding to retry
A retry is a new attempt to perform work. It is safe only when the failure is likely to be transient and the effect of another attempt is understood. The HTTP status alone is not enough to classify every failure, especially when a remote system may have completed the operation but OIC did not receive its response.
Kid-friendly analogy
If a school website is busy, waiting and trying again may help. If a permission form is incomplete, repeating the submission without fixing it will not make the missing signature appear.
In this OCI AI integration, this means: Retry transient faults using a bounded policy; repair invalid input, authorization, and business-rule failures through the correct corrective path instead of repeatedly resubmitting them.
| Failure category | Default handling strategy | Required check |
|---|---|---|
| Invalid schema, unsupported input, invalid parameter | Reject, correct, or quarantine. Do not blindly retry. | Input contract and documented operation constraints. |
| Authentication or authorization denied | Stop repeated attempts and route to the identity/configuration owner. | Principal, credentials, policies, region, and resource scope. |
| Throttling or rate limiting | Reduce concurrency, honor documented retry instructions, and use bounded backoff. | Current operation limits, request rate, shared load, and queue depth. |
| Transient network or service failure | Retry when allowed by the operation's documented behavior and duplicate risk is controlled. | Whether the request took effect despite the missing response. |
| Business mismatch or approval rejection | Preserve the result and route for correction or review. | Authoritative records, validation rules, and decision evidence. |
| Unknown outcome after timeout | Reconcile existing work before attempting a new submission. | Provider job state, request history, or authoritative target query. |
8.2 Understand the OIC retry behavior you are enabling
Oracle documents an Add Retry Logic to Invoke Connections in Projects feature. The documented helper is available only for integrations in Projects. Its generated retry logic defaults to three retries and a five-second wait between retries. Oracle also documents that the helper retries all invoke faults, including business and runtime faults, and does not provide a fault-type selector for excluding a category.
That is an important design constraint. Three retries with a five-second wait are documented defaults for that helper, not universal retry defaults for every OIC invoke or OCI AI API. A fixed delay is not automatically appropriate for a throttled service, and replaying a business fault may create unnecessary load or repeat an unsafe operation.
Review retries at every layer. The current REST Adapter capabilities guide documents an invoke-wizard option that disables its three automatic HTTP 504 retries during synchronous invoke calls. This is separate from the Projects retry helper. Disabling adapter retries does not disable an outer loop, caller retry, or operator resubmission. Inspect every layer, test the actual invoke, and use target idempotency or reconciliation for uncertain writes. This setting does not establish retry behavior for native OCI AI actions.
Oracle's earlier integration retry-pattern article also demonstrates custom retry loops with scopes, fault handlers, variables, waits, and an explicit exhaustion path. Use that as a pattern reference, not as proof that a given integration already contains the desired policy.
8.3 Use bounded exponential backoff for eligible transient faults
For a retryable transient error, an application-level policy can grow the delay after each failed attempt, add jitter to spread requests across time, and stop when either the attempt budget or elapsed-time budget is exhausted.
retryIndex = 0 for the first retry
cap = min(maxDelay, baseDelay * 2^retryIndex)
delay = uniformRandom(0, cap) // full jitter; never exceeds maxDelay
Stop retrying when:
attempt budget is exhausted
OR elapsed-time budget is exhausted
OR the fault is not retryable
OR the operation outcome is uncertain
OR retrying would violate the operation's safety contract
This is an illustrative policy formula, not an Oracle-prescribed default. Derive the base delay, maximum delay, jitter, retry count, and overall deadline from the actual operation, business latency requirement, service contract, and load tests. When a service provides a documented Retry-After instruction, do not retry earlier than it permits. If that wait exceeds your local wait budget or deadline, defer the case durably or stop and escalate; do not shorten the service-required wait. This pseudocode is not a paste-ready OIC expression. Implement it using supported actions and a verified random source, or choose a documented supported retry policy.
For OCI Generative AI on-demand inference, Oracle documents dynamically adjusted request-throttling limits that can change with model demand and system capacity. The limits are not all published as a fixed number. Oracle recommends backoff after rejections because repeated rapid requests can cause further rejection, higher latency, and potential temporary blocking. See Dynamic Throttling.
8.4 Control concurrency and protect the workflow
Retries are only one source of load. A burst of new cases, several parallel AI operations per case, and scheduled replay of old failures can produce a surge even when every individual retry policy is bounded.
Use a queue or controlled intake rate where the business flow permits asynchronous processing. Set concurrency limits per service and operation using measured throughput, documented quota, downstream capacity, and the number of simultaneous jobs that the selected route supports. Do not assume that the highest concurrency accepted by OIC is also safe for the target AI service.
A circuit breaker is an application resilience pattern, not a claim that every OCI AI service or OIC native action provides one. Track repeated failure or throttling over an explicitly defined time window. When the failure policy is triggered, temporarily stop sending new work to the affected dependency, allow the configured recovery period, and admit a small number of controlled probes before restoring normal traffic.
Design the circuit-breaker state to be durable and appropriately shared by the callers it protects. If multiple OIC instances or scheduled flows independently make retry decisions, local variables alone may not coordinate their aggregate traffic.
Include adapter retries, application retries, status polling, and recovery traffic in the same capacity plan. Nested retry layers can multiply remote attempts. Poll existing jobs with a bounded interval and deadline; polling too quickly adds load without making the AI finish sooner. For work that can outlive an integration execution, persist the next action and schedule a later worker rather than relying on an unbounded wait loop.
9. Duplicate Work, Uncertain Outcomes, and Recovery
9.1 Build an application-level idempotency strategy
An idempotency strategy makes repeated delivery of the same business request safe according to a defined contract. It is different from a provider request ID, a job ID, or an OIC instance ID. Those values can help identify an attempt; they do not automatically prevent duplicate business effects.
Kid-friendly analogy
When a school trip form is handed in twice, the office checks the student's case record before creating a second trip booking. A second envelope should not automatically create a second reservation.
In this OCI AI integration, this means: Register a stable business key and source version, detect duplicate deliveries, and reconcile previous attempts before submitting work that could cause duplicate cost or a duplicate target transaction.
For the synthetic procurement scenario, a case registry should let the integration locate a prior case using a stable business key and a defined source fingerprint. The precise key depends on the source and business process. An invoice number alone may not be globally unique; a combination of supplier identity, invoice reference, source version, and an approved normalization rule may be required.
At minimum, store the idempotency key, case state, current attempt, latest provider request/job reference, result artifact references, target transaction reference, and the timestamp and outcome of the last reconciliation. Enforce uniqueness in the durable store where the chosen technology supports it. Do not rely solely on two parallel OIC executions checking the same key without an atomic claim or equivalent concurrency control.
Two different duplicate controls
Delivery duplicate: the same source event/version arrives again. Reuse the registered case. Business duplicate: the same payable invoice arrives as a changed scan or a different event. A new file hash does not make it a new payable obligation. Maintain the process’s business uniqueness rule separately from the artifact/version key. Decide how corrections and credit notes are handled; never use a changed hash alone to authorize another payment.
A durable registry can be implemented in a transactional database or a service offering conditional writes. OIC variables and activity streams alone are not that registry. Persist a submission intent before calling a remote system, then its response and references afterward. A crash between remote acceptance and recording the response still leaves an uncertain outcome; a local database transaction does not make the remote call atomic. Use provider-supported idempotency or reconcile. If workers use expiring claims, define lease renewal and protection against a stale worker continuing after another worker takes over.
9.2 Treat uncertain outcomes as a separate state
A timeout may mean the request never reached the destination, the destination rejected it, or the destination completed the operation and the response was lost. Unless the documented operation contract proves the outcome, classify this as UNKNOWN rather than declaring either success or failure.
Use the following recovery sequence:
- Persist the observed failure, the original business key, any request or job reference, and the last known state.
- If an asynchronous job was created, query the documented status or retrieve the existing job where supported. Do not create another job merely because the original status check timed out.
- If a target write timed out, query the authoritative target system using a documented unique key or external reference. Validate the result before deciding that another write is safe.
- If the destination proves completion, record the confirmed target transaction ID and reconcile the case to the correct completed state.
- Retry only when the documented contract makes repetition safe or authoritative evidence establishes that the original attempt cannot still create an effect. A single “not found” lookup is insufficient when processing or indexing can be delayed. Use the target’s consistency and completion guarantees, a provider-supported idempotency key, or an explicitly owned reconciliation procedure before another write.
- If the destination cannot provide adequate evidence, keep the case in a reconciliation queue and assign an owner. Do not convert uncertainty into an automatic new write.
9.3 Model asynchronous processing explicitly
For an operation that returns an asynchronous job, distinguish the submission response, the job's current state, terminal processing status, per-item outcome, and availability of the resulting artifact. The business case is complete only when the output needed for its decision is available and has passed its required validation.
A suitable application-level state model might include:
RECEIVED
-> INPUT_VALIDATED
-> AI_SUBMITTED
-> AI_RUNNING
-> AI_COMPLETED
-> QUALITY_REVIEW_REQUIRED or QUALITY_PASSED
-> BUSINESS_VALIDATED
-> AWAITING_APPROVAL, if required
-> WRITE_SUBMITTED
-> WRITE_CONFIRMED
Alternative paths:
-> PARTIAL
-> RECONCILIATION_REQUIRED
-> RETRY_WAIT
-> FAILED_FINAL
-> HUMAN_REVIEW
These are tutorial-defined business states, not universal service job enums. Map each supported operation's actual states and errors into them. Define handling for delayed jobs, per-item failures, expired or inaccessible output artifacts, denied storage access, duplicate submission, and interrupted polling. Preserve successful work instead of rerunning every operation when only one downstream step failed.
For OIC's own message recovery, consult the actual Resubmit Failed Messages documentation. Oracle does not automatically resubmit failed messages. Failed asynchronous-flow instances are generally recoverable, subject to exceptions and the recovery window; scheduled flows with scheduled parameters are an exception, synchronous flows cannot be resubmitted, and a failed instance can be resubmitted a maximum of ten times. Resubmission may resume at a designed recovery location or restart from the beginning. Do not discard an error that you intend to resubmit. OIC resubmission does not eliminate the need for business idempotency.
10. Observability, Correlation, and Support Runbooks
10.1 Make one business case traceable across systems
Observability is the ability to reconstruct what happened, where it happened, and what should happen next from controlled operational evidence. A case may cross several OIC instances, OCI service calls, asynchronous jobs, object artifacts, and business transactions. The design must preserve the links between those objects.
Kid-friendly analogy
A parcel may pass through several delivery centers. Its tracking number helps connect the collection, transfer, and delivery records without printing the parcel's private contents on every label.
In this OCI AI integration, this means: Propagate a stable case correlation across permitted headers or payload fields and maintain explicit links to OIC instances, OCI request/job IDs, artifact references, and target transaction IDs.
Use a correlation registry or another durable record to store these relationships. An illustrative record might contain a case ID, OIC integration and instance IDs, provider request or job references, source/result artifact IDs, and the target transaction reference. Do not assume a custom case header is automatically propagated or indexed by every service; inspect the actual integration and API contracts.
Define business identifiers in OIC for stable, non-sensitive values that make the instance searchable. Oracle documents tracking and filtering integration instances by business identifiers in Track Integration Instances. Good candidates are a synthetic or pseudonymous case ID and a safe source-system key, subject to the organization's data policy. Avoid using a tax number, full email address, raw invoice text, or an access token as a business identifier.
10.2 Use OIC and OCI observability for different questions
Start with OIC's own dashboards, instances, errors, and activity streams to identify integration status and the point of failure. The current Observability Pages documentation describes the relevant views, including integration status, run-time behavior, instance details, and error recovery actions.
Use OCI Logging, Monitoring, and their supported notification or dashboard integrations for the broader operational view where appropriate. OCI Logging distinguishes audit logs, service logs, and custom logs. OCI Monitoring supports metrics and alarms, including custom metrics where the application publishes them. See the official Logging overview and Monitoring overview.
AI-specific measures such as extraction-quality failure rate, unresolved provider jobs, human-review backlog, duplicate suppression, retrieval relevance, and cost per completed business case may require explicit instrumentation. Do not assume that OIC's basic integration success count automatically contains those semantic business measurements.
The Oracle Integration product team's Logging Analytics dashboard article describes how OCI Logging Analytics can supplement native OIC observability. Use the documented setup and capabilities applicable to your instance rather than treating a blog dashboard as a universal tenant feature.
10.3 Define the dashboard before the alert
An operational alert should identify an actionable condition, not merely report activity. Establish thresholds from the service objective and measured baseline rather than inventing a universal acceptable failure percentage or latency number.
| Measure | Why it matters | Possible action |
|---|---|---|
| Intake and completion rate | Shows whether demand is being processed and completed. | Investigate sustained divergence or growing queue depth. |
| Errors by layer and operation | Distinguishes mapping, identity, provider, storage, and target failures. | Route to the owner of the failing dependency. |
| Retries and throttling | Reveals instability, excess concurrency, or an overloaded dependency. | Reduce admission rate, back off, or investigate a provider issue. |
| p50, p95, and p99 latency | Shows typical performance and the impact on slower cases. | Locate queue delay, slow steps, and long-tail failures. |
| Oldest unresolved case and review backlog | Shows whether work is accumulating even when services are returning responses. | Assign review capacity or recover stalled work. |
| Unknown target outcomes | Identifies cases at risk of duplicate writes or missed completion. | Run the approved reconciliation procedure. |
| Quality-gate failure and review rate | Detects output-quality changes and increased manual workload. | Review labeled examples and the latest model/configuration change. |
10.4 Make the support runbook executable
For each alert, record the severity, business impact, initial diagnostic query, safe first action, named owner, escalation route, and recovery stop condition. At a minimum, the support team should be able to:
- Search for the case using the approved business identifier.
- Open the OIC instance and identify the failing activity or invoke.
- Follow the correlated OCI request/job and artifact references.
- Determine whether the fault is validation, identity, throttling, provider, storage, integration, or target-system related.
- Establish whether the remote operation completed, failed, or remains uncertain.
- Choose the documented retry, recovery, reconciliation, or manual-review procedure.
- Record the outcome and ensure the case cannot be silently lost or duplicated.
For additional detail, review Manage Errors. A useful runbook is validated by an engineer who did not design the integration, using an injected failure and only the documentation and access that on-call support would normally have.
11. Combine the Controls and Run Failure Drills
A control is not proven merely because it exists in a design document. A failure drill deliberately creates a safe, known condition and checks whether the workflow responds as intended. Run these tests in a non-production environment, with synthetic supplier data and a test target. Do not inject failures or duplicate writes into a live procurement or payment flow.
Use the table as a test plan. The evidence column tells the tester what to capture; it is not a record that any test has already passed.
| Case | Expected behavior | Evidence to capture |
|---|---|---|
| Valid synthetic invoice; PO values match | Required fields are extracted, deterministic checks pass, and the case advances only to the approved next state. | Case ID, OIC instance ID, output reference, rule outcomes, final case state. |
| Missing required field or unsupported file | Input is rejected or routed for review; no target write occurs. | Validation reason, fault details, target-write count or absence of a target transaction. |
| IAM permission deliberately removed in a test compartment | The call fails closed, repeated pointless retries stop, and the responsible owner can identify the permission boundary. | Sanitized error, caller/operation/region, alert route, no secret or raw supplier content in the alert. |
| Transient service failure or throttling simulation | Only eligible errors use bounded retries/backoff; attempt and delay limits are respected. | Attempt timestamps, retry counter, observed error category, total elapsed time. |
| Timeout after a test target may have committed a write | Case enters UNKNOWN or reconciliation; the integration checks the target before any repeat write. | Target query, unique key, transaction record, reconciliation decision, duplicate count. |
| Same business request delivered twice | Duplicate-detection policy identifies the prior case or routes a changed source version according to the business rule. | Registry uniqueness evidence, prior case link, target transaction count. |
| Asynchronous job is delayed or has partial results | The workflow polls or reconciles the existing job according to its contract and preserves successful items. | Provider job reference, status history, per-item results, output availability. |
| Supplier content contains prompt-injection instructions | Content is treated as untrusted data and cannot override authorization, change tool permissions, or bypass approval. | Sanitized test input, generated output, policy decision, blocked write evidence. |
| Reviewer is not assigned or not authorized | Approval is denied and recorded; the case remains in a controlled review state. | Reviewer identity, access decision, case state, audit entry. |
11.1 Run each drill in a repeatable order
- Write down the starting state, the condition you will change, the expected outcome, and the stop condition before you run the test.
- Use one synthetic case ID and record all starting identifiers. Confirm that the test target and any storage bucket are non-production.
- Run the case once, collect the OIC activity stream and correlated provider or target evidence, then run the planned failure or duplicate condition.
- Compare expected and observed results. Mark a test PASS, FAIL, or NOT RUN; never mark it PASS merely because the integration returned a response.
- Restore any test-only policy or configuration change and record who approved the test, when it ran, and what remains unresolved.
Evidence status for this article: these are proposed test cases and expected outcomes. They have not been executed against your OIC tenant or target systems.
12. Throughput, Latency, Capacity, and Unit Economics
Capacity planning asks whether the whole workflow can process expected demand within the required time and cost—not just whether one AI request succeeds. Measure each major stage separately: intake, file access, AI processing, polling, deterministic validation, human review, and target writes.
Start with these simple definitions:
- Throughput: completed business cases per minute, hour, or day.
- Latency: elapsed time for one operation or end-to-end case, including waits and polling if you measure end-to-end completion.
- Concurrency: how many operations are in progress at the same time.
- Backlog age: how long the oldest unfinished case has been waiting. A workflow can have successful calls while its backlog becomes unacceptable.
- Unit economics: the measured cost and human effort associated with one successfully completed business case.
Track p50, p95, and p99 latency. The p50 is the midpoint, p95 identifies the slower tail, and p99 highlights rare but very slow cases. Averages alone can hide a small group of cases that miss the business deadline.
12.1 Estimate work before estimating money
Count operations per case first. For example, in a fictional test with 200 cases and two AI actions per case, the baseline is 400 action invocations before retries, reprocessing, or polling. If some cases require another attempt, count those attempts too. This example is arithmetic for planning only; it is not a quota, service limit, or observed result.
An initial concurrency estimate can be made with the relationship: in-flight work ≈ arrival rate × average time in the system. For example, a stable arrival rate of two operations per second and an average system time of five seconds suggests about ten operations in flight. Treat this as a rough estimate, not a sizing guarantee; validate it with tests because service quotas, queueing, variable file sizes, and downstream limits can change the result.
Use consistent boundaries and units for that estimate. Arrival rate and elapsed time must refer to the same queue or processing stage over a stable measurement window. Including queue wait estimates work in the whole system, including queued work; it does not directly size active provider calls or OIC worker slots. Separate automated processing time from human-review waiting time, and report unfinished or expired cases alongside completed-case latency so a fast-success sample does not hide a growing backlog.
12.2 Measure cost per completed case
Use this application-level calculation over a clearly defined measurement window:
cost per completed case =
attributable OIC cost
+ attributable OCI AI cost
+ storage, logging, and supporting-service cost
+ measured human-review cost
-------------------------------------------------
completed business cases
This is an internal allocation model, not an Oracle billing formula. Use the current price list, your contract, actual usage records, and the billing meters relevant to the services you use. Include failed attempts and retries in the numerator, and count only cases that reached your defined successful terminal state in the denominator. If shared costs cannot be attributed precisely, state the allocation method so the result can be compared consistently over time.
Group the entire cost numerator before dividing. When no cases complete, report the cost and zero completions separately; cost per completed case is undefined. A window with substantial work still in progress can distort this measure. Use a consistent case cohort or disclose opening/closing work in progress, and avoid mixing failed attempts from one population with completions from another.
Run a baseline test, a peak-load test, and a recovery-after-outage test. Confirm that increasing concurrency improves completed-case throughput rather than merely increasing throttling, retries, or target errors. Measure the impact of human-review queues separately; adding AI calls does not necessarily reduce total operating effort.
Checkpoint: The team has a measured baseline, a demand profile, a backlog alert, a tested concurrency limit, a cost-allocation rule, and an agreed service objective. No universal latency or cost threshold is assumed in this tutorial.
13. Versioning, Promotion, Rollback, and Model Drift
A release changes more than integration code. The behavior of a procurement workflow may also depend on connection configuration, the selected OCI operation, the model or custom-model configuration, the canonical contract, prompts, thresholds, policy documents, and the mapping from provider states to business states. Record the components that can affect the outcome.
13.1 Keep a release manifest
For each promoted release, store a reviewed manifest containing:
- OIC project/export identity, integration versions, deployment selection, connection names, and configuration dependencies. Keep credentials and secret values in approved secret-management facilities, not in the manifest.
- OIC release/patch as observed in the environment, the actual service/API route, region, resource identifiers, and any exposed model or configuration identifier.
- Canonical contract version, mapping version, gate rules, reason-code catalog, prompt/template version where applicable, and the revision of the approved retrieval corpus.
- Regression-test version, labeled evaluation set, expected outcomes, actual test evidence, known limitations, owner, and rollback plan.
Record only model version details that the service and selected operation actually expose. Do not invent a model version or assume that every managed service supports pinning a model to an immutable version. Where the provider can update model behavior and the application cannot pin a version, make that limitation explicit and use regression evaluation plus monitoring to detect behavior changes.
13.2 Promote with evidence, not just a successful deployment
- Development: validate mappings and state transitions using synthetic input and a test target.
- Test: run positive, invalid-input, boundary, permissions, throttling, duplicate, timeout, and human-review cases. Compare AI output with a labeled reference set where model output is used.
- Pre-production: repeat the suite against the actual deployment shape and realistic volume, verify secrets and IAM separately, and rehearse reconciliation and rollback.
- Production approval: require owners to accept residual risks, confirm alerts and the runbook, and make sure support can find cases without reading raw sensitive payloads.
- Post-release: compare quality, review rate, retries, latency, and cost to the baseline. Roll back or pause processing when a defined guardrail is breached.
A rollback may require restoring more than an integration version. The old model may no longer be selectable; a policy corpus may have changed; a target schema may not accept the earlier contract. Document which components can be reverted, which require a forward fix, and which cases need replay or reconciliation. Never replay old business cases automatically without applying the duplicate and current-authorization controls.
13.3 Monitor for quality drift
Quality drift means the results or operational outcomes change compared with an accepted baseline. It can arise from different supplier document formats, language or image quality, upstream schema changes, retrieval-corpus changes, prompts, model updates, or a shift in the mix of cases. Monitor both model-facing measurements and business-facing outcomes.
Review a small, controlled sample of completed and manually reviewed cases against labeled reference answers. Track false acceptance (a bad result passed) separately from false rejection (a good result was unnecessarily held). Review changes by supplier, input type, language, model/configuration, and operation where the available data and privacy rules permit. A rising review rate can be an early warning even if provider calls still return HTTP success.
Checkpoint: Every release is identifiable, tested against the same repeatable baseline, approved by an owner, observable after promotion, and accompanied by a feasible rollback or forward-recovery plan.
14. Deterministic Orchestration Versus Agents
Deterministic orchestration follows an explicitly designed sequence of steps and rules. Agentic execution gives an AI agent some discretion to choose among permitted tools or steps in pursuit of a goal. Both approaches can be useful, but they solve different problems and have different operational risks.
| Prefer deterministic orchestration when… | Consider an agent when… |
|---|---|
| The steps are known, ordered, and must be repeated consistently. | The system must interpret an open-ended request and choose among a small, explicitly allowed set of tools. |
| The flow includes fixed policy checks, calculations, approvals, or target writes. | The task benefits from flexible research, summarization, or multi-step retrieval where the exact sequence is not known in advance. |
| Auditability and predictable side effects are primary requirements. | The task can tolerate bounded variation and has clear checks for output quality, tool access, and stop conditions. |
For the procurement example, a sensible default is deterministic OIC orchestration for input validation, numeric reconciliation, approval routing, and final writes. Use AI to extract a candidate invoice value, transcribe a required voice note, summarize evidence, or answer a question against an approved policy corpus. A RAG answer can help the reviewer understand a policy; it does not itself approve a transaction or confer authorization.
If an agent is justified, constrain it: expose only approved tools, prefer read-only tools initially, set explicit iteration/time/tool budgets where supported, validate tool arguments and outputs, enforce caller permissions outside the model, and require a separate authorized approval for consequential writes. Test prompt injection and tool misuse. Treat generated text and retrieved content as untrusted inputs to the business control layer.
Do not add an agent just to make a fixed sequence sound more advanced. Choose it only when its flexibility produces a measurable benefit that outweighs extra latency, cost, variability, testing effort, and operational risk.
15. Completion Checklist and What Comes Next
Use this checklist to decide whether the implementation has enough evidence to move to the next delivery stage. A checked item should point to a real artifact, test record, or named owner—not just a statement that the topic was discussed.
| Readiness item | Evidence to attach | Owner |
|---|---|---|
| Environment and route verified | OIC release, region/realm, action or API, endpoint, and availability evidence. | Integration owner |
| Identity and least privilege reviewed | Reviewed policies, caller map, successful permitted call, denied unauthorized call. | Cloud/security owner |
| Case contract and state transitions defined | Versioned schema, state diagram, reason codes, owner for unresolved states. | Solution owner |
| Quality and business controls tested | Labeled examples, required-field tests, deterministic reconciliations, review rules. | Business/process owner |
| Retries, duplicate prevention, and reconciliation proven | Failure-drill evidence, unique key/atomic claim, unknown-outcome procedure. | Integration/target owner |
| Privacy and retention reviewed | Classification, approved regions, trace levels, retention/deletion responsibilities. | Security/data owner |
| Alerts and support runbook exercised | Alert test, sanitized diagnostic query, escalation contact, tested recovery procedure. | Operations owner |
| Release and cost baseline captured | Manifest, regression results, load-test results, cost method, rollback or forward-fix plan. | Release owner |
15.1 Your first practical exercise
- Choose one synthetic invoice case and register its stable case ID, source version, and artifact reference.
- Identify the existing OIC native AI action or REST route from the actual implementation. Confirm its prerequisites and documentation before changing anything.
- Save the operation result by reference and map it into the application-owned case contract. Do not treat the illustrative contract in this article as an OCI API schema.
- Compare extracted values with a synthetic purchase order using deterministic rules. Route a mismatch to review instead of allowing a model to approve it.
- Replay the same test request and verify duplicate handling. In a safe test environment, simulate an uncertain target response and prove that reconciliation occurs before another write.
- Complete the evidence table and runbook before moving on to more services, larger volume, or agentic behavior.
The next step is not automatically to add more AI. It is to close the highest-risk evidence gap identified by your tests and make the operational behavior reproducible for someone other than the original developer.
16. Five Useful FAQs
1. Does every OIC Gen3 tenant expose the native OCI AI actions?
No. Check the identity/IAM prerequisites, edition, service, region, and deployed release. Oracle’s aggregate availability page and Document Understanding-specific release guidance differ about government/non-commercial availability; see section 3.3 and confirm the exact route before relying on it. A REST route also needs its own documented authentication, schema, availability, and failure handling.
2. Can I assume OIC retries only temporary service faults?
No. The Projects helper retries business and runtime faults, with documented defaults of three retries and a five-second interval. The REST Adapter’s automatic HTTP 504 retries are a separate layer. Inspect both, plus caller and recovery retries; disabling one layer does not disable the others.
3. If an invoke times out, is it safe to submit the same request again?
Not until you know whether the first request took effect or the operation contract makes repetition safe. A timeout can hide a successful remote write. Persist the original business key and request references, query the provider or authoritative target where supported, and reconcile before sending a new write. OIC failed-message resubmission has flow-type and recovery limitations and does not replace application-level idempotency.
4. Does a high AI confidence score prove that an invoice is correct?
No. A confidence score describes a model's confidence for the specific output it reports; it does not prove that the invoice agrees with the purchase order, that arithmetic is correct, that a supplier is authorized, or that policy permits payment. Calibrate gates with labeled examples and use authoritative records plus deterministic business rules.
5. Should I use RAG or an agent to approve a procurement exception?
Not as a substitute for the authorized approval process. RAG can retrieve policy evidence and help prepare an explanation. An agent may be appropriate for bounded investigation when tool choice is genuinely dynamic, but tool permissions, data access, business validation, and privileged writes must remain separately controlled. The target system and approved business workflow remain authoritative.
17. Verified References
A reachable page is not a guarantee that every specific claim in every release-specific paragraph applies to your tenant; confirm the guide, service, and release that match your implementation.
- Using Integrations in Oracle Integration 3 — current OIC user guide;
- OCI AI Services Category — native OIC AI action family and prerequisites links.
- OIC prerequisites for OCI AI services — identity domains, dynamic group, and IAM policy prerequisites.
- Extract Document Information with a Document Understanding Action — action wizard, supported invoice extraction, region and compartment fields, object-storage mapping, and response mapping.
- AI Feature Availability — OIC feature and region availability.
- Add Retry Logic to Invoke Connections in Projects — scope, defaults, and fault-selection limitation.
- New Adapters and Connectivity Enhancements in Oracle Integration 26.07 — REST Adapter HTTP 504 retry control and dynamic JSON support.
- Resubmit Failed Messages — recovery behavior and limitations for OIC instances.
- Activate an Integration — trace levels, data capture, and retention.
- Track Integration Instances and Manage Errors — business identifiers, runtime tracing, and error recovery.
- OCI Document Understanding overview, OCI Vision overview, OCI Language overview, and OCI Speech — service capabilities and constraints.
- OCI Generative AI overview, Dynamic Throttling, and Managing RAG Tools in Generative AI Agents — model access, throttling, and retrieval-grounded answers.
- IAM Policy Syntax, IAM overview, and Limiting Model Inference Access with IAM Policies — permission statements and model-level restrictions.
- OCI Regions and Availability Domains, OCI Logging overview, and OCI Monitoring overview — deployment boundaries and observability.
- Deep Dive into Integration Retries during the failure and OCI Logging Analytics Dashboards for OIC — product-team implementation-pattern examples, not guaranteed tenant configurations.
Additional implementation references: Document Understanding limits — distinguish synchronous requests from asynchronous jobs; REST Adapter capabilities — automatic HTTP 504 retries and the separate disable option.
Finally — Summary
A reliable OCI AI workflow is more than a chain of successful service calls. It keeps a durable record of each business case, ties every output to its source and processing step, and uses explicit quality gates before allowing results to influence business decisions. Deterministic rules and authoritative systems—not generated text—must control financial calculations, authorization, and privileged writes.
For production readiness, verify the actual OIC release, native action or REST route, identity permissions, region and data-retention boundaries. Design retries around the fault type and duplicate risk; treat uncertain outcomes as a reconciliation task. Then prove the design with synthetic failure drills, measurable service objectives, repeatable regression tests, a cost baseline, and an actionable support runbook.
The examples in this tutorial are architecture patterns, not evidence of a deployed tenant or executed tests. Your readiness decision should be based on the implementation's own configuration, observed results, and accepted business risks.

Comments
Post a Comment