Skip to main content

OCI AI Services: How to Choose the Right Service for Enterprise Integration

Calculating read time…

Imagine that a procurement team receives three pieces of evidence for one supplier exception: a PDF invoice, a phone recording, and a blurry delivery photograph. Each contains useful information, but no single AI action processes all three in the same way. Document Understanding can extract invoice fields without proving that the invoice is valid. Speech recognition can transcribe a supplier's words without proving that the promised delivery date is correct. Vision can detect objects or text in a photograph without establishing that a delivery actually occurred. A generated answer can sound convincing while relying on an outdated policy.

OCI AI architecture: select Language, Document Understanding, Vision, Speech, Generative AI, or Agents RAG for the task; check IAM and region; validate outputs before business action.

The engineering challenge is therefore not simply choosing a capable model. It is deciding which capability owns each transformation, how the input reaches the service, which identity authorizes the call, and what evidence must be checked before the business workflow continues. Oracle Cloud Infrastructure (OCI) provides specialized AI services, generative models, and retrieval-backed agent capabilities, while Oracle Integration 3 (OIC Gen3) exposes a documented subset through native actions. This tutorial establishes a practical selection method and walks through configuring one native Language action and the surrounding validation, mapping, and test criteria.

1. What You Will Build

You will produce a defensible service-selection map for the six OCI AI service-action families covered here, understand the infrastructure and identity dependencies that affect their use through OIC Gen3, and implement a synchronous language-detection baseline using a native OCI Language action.

Practical outcome

A REST-triggered OIC integration accepts a synthetic supplier message and returns a normalized language-detection result with its confidence score and source metadata.

Example input:

{
  "requestId": "supplier-msg-0001",
  "sourceRef": "supplier-message-001",
  "text": "Please confirm the expected arrival date for PO-10482."
}

Expected result structure:

{
  "schemaVersion": "1.0",
  "requestId": "supplier-msg-0001",
  "status": "COMPLETED",
  "result": {
    "languageCode": "en",
    "languageName": "English",
    "confidence": 0.98
  },
  "provenance": {
    "service": "OCI Language",
    "operation": "Language detection",
    "sourceRef": "supplier-message-001"
  }
}

Illustrative contract only—not an observed execution result. The language and numeric confidence value are examples; an actual response depends on the submitted text and service result. No tenant execution is claimed by this article.

The scope is deliberate. This is an architecture-essentials module, not six separate implementation labs. Only the Language action receives an implementation walkthrough here; completing the tenant-specific schemas, expressions, mappings, and fault handling and then running the tests are still required. The other service families receive a concrete selection map and their relevant OIC integration boundaries, giving subsequent service-specific tutorials a sound foundation.

2. In This Post

  1. What You Will Build
  2. In This Post
  3. Before You Begin
  4. Concepts That Affect This Build
  5. Build and Configure — Step by Step
  6. Test and Prove It
  7. Troubleshooting and Recovery
  8. Enterprise Considerations
  9. Completion Checklist and What Comes Next
  10. Five Useful FAQs
  11. Verified References
  12. Finally — Summary

3. Before You Begin

CORE — prerequisites for the working baseline

  • An Oracle Integration 3 instance with access to OCI AI service actions in the commercial realm, OC1, and a supported service region. Oracle's current edition comparison includes OCI AI services in Standard, Enterprise, and Healthcare editions; the separate AI assistant and agentic AI features have different edition entitlements.
  • An OCI tenancy using identity domains, an administrator who can configure the required dynamic group and IAM policy, and access to the OIC instance's OAuth application client ID.
  • Permission to create and activate a REST-triggered OIC integration and invoke it with a synthetic JSON request.
  • A compartment configured for OCI Language access by the OIC instance.
  • The ability to inspect the action response and the integration instance's execution details.

Use the current Oracle guides for AI Feature Availability and OCI AI service prerequisites. The feature-availability page notes that native OCI AI service actions are available only in OC1 and that individual services have their own regional availability.

Check Oracle Integration Editions for the current entitlement matrix. Visibility of a feature in the designer alone does not establish entitlement to other AI features.

JUST-IN-TIME PREREQUISITE: The lab uses pretrained language detection. It does not require creating a custom model, a model endpoint, a knowledge base, or an Object Storage bucket.

4. Concepts That Affect This Build

4.1 Select a capability before selecting an AI product

The six native OCI AI action families covered here solve different technical problems. They are the scope of this OIC selection map, not an exhaustive inventory of OCI AI products or capabilities. Select the operation by its required input, output, and acceptance criteria—not because one family contains the word AI or because a model can generate an answer about the input.

Kid-friendly analogy

Imagine a school receiving a note, a photograph of a worksheet, a voice recording, and a question about a rule in its handbook. A reader, a camera inspector, a transcription helper, and a librarian have different jobs. Asking one helper to do everything can produce the wrong kind of answer.

In this OCI AI integration, this means: Match the service operation to the required transformation, and keep deterministic business validation in OIC or the target system.

Service family Choose it when... Typical input → output Important boundary
OCI Language You need to analyze or transform unstructured text. Text → language, entities, key phrases, sentiment, classification, translation, or personally identifiable information (PII)-related results. An extracted entity or sentiment label does not establish business truth.
OCI Document Understanding You need document-oriented extraction, OCR, classification, or table structure. PDF, PNG, or JPEG document → extracted text (optical character recognition, or OCR), words and lines, key-value fields, tables, or document type. Extracted invoice values must still be validated against procurement records and business rules.
OCI Vision You need visual analysis of image content. Image → classification labels, object detections, or detected text (and face-related detections where appropriate), according to the selected task. Image-level text detection is not equivalent to structured invoice extraction.
OCI Speech You need speech-to-text transcription or text-to-speech synthesis. Audio → text transcription; text → synthesized speech artifact. Transcription is not proof that every word, speaker label, or date was recognized correctly.
OCI Generative AI You need model-generated text, embeddings, or relevance-based reranking. Task-specific input → chat responses, text embeddings, or ranked candidate documents. Image input is also supported for documented chat/model combinations. Fluent generation is not evidence of factual accuracy; embeddings require compatible downstream search.
OCI Generative AI Agents RAG You want answers informed by configured enterprise knowledge bases. Question and agent endpoint → context-aware answer and session-related information. Retrieved content and citations do not guarantee that the answer is complete, current, or true.
Deterministic logic You need enforced business rules or authoritative system facts. Validated records and business conditions → reproducible decisions or controlled actions. Keep authorization, invoice reconciliation, idempotency, approval, and write controls here.

Oracle's current service guides describe these capabilities in more detail: Language, Document Understanding, Vision, Generative AI, and Generative AI Agents. The OIC native action documentation establishes the subset exposed directly in integrations.

4.2 Specialized AI, generative AI, retrieval, and deterministic processing

Specialized services apply task-focused models to inputs such as text, documents, images, and audio. Within OCI Generative AI, chat models synthesize responses, embedding models produce vectors, and reranking models score candidate relevance; these are distinct inference tasks, and embedding or reranking is not itself text generation. Retrieval-augmented generation (RAG) retrieves information from configured sources and uses it as context for a generated answer. These techniques complement one another; they do not replace the transaction system that establishes the authoritative business state.

Kid-friendly analogy

Imagine checking a school library's loan register, finding the matching handbook page, and then asking someone to explain that rule in plain language. The register establishes who borrowed the book, the handbook supplies evidence, and the explanation makes the evidence easier to understand.

In this OCI AI integration, this means: Use authoritative business APIs and deterministic rules for transaction facts, retrieval for relevant policy evidence, and generation for language tasks that benefit from synthesis.

For the procurement scenario, a sound sequence might be:

  1. Use Document Understanding to extract invoice fields from the submitted invoice.
  2. Use Language to classify or analyze the supplier's text, if that analysis serves a defined requirement.
  3. Use Speech to transcribe a voice note and Vision to inspect a delivery photograph, when those inputs exist.
  4. Use Generative AI to summarize already available evidence, or embeddings and reranking when implementing semantic retrieval.
  5. Use Generative AI Agents RAG to answer questions against configured procurement-policy knowledge bases.
  6. Use OIC and authoritative procurement systems to validate purchase-order existence, supplier status, totals, permissions, and approval requirements.

A key boundary: the OIC action named OCI Generative AI Agents RAG invokes the managed agent/RAG capability documented by Oracle. It is not the same thing as OIC Project AI Agents, a generic chat completion, or an unrestricted workflow agent. Select it because the requirement is to query a configured knowledge base through an agent endpoint.

The wider OCI services extend beyond this selection map. Current OCI Generative AI documentation also describes agentic APIs, tools, and hosted applications; OCI Generative AI Agents supports RAG and other tool types. Those service capabilities are not automatically exposed by the OIC native actions described here. For this tutorial's RAG scenario, select an agent configured with the intended knowledge-base retrieval behavior and review its enabled tools and permissions.

4.3 Native OIC action versus REST invocation

The OCI service is the underlying capability; a native OIC action is one supported integration interface to that capability. Native actions expose documented categories, operations, configuration fields, and mapper schemas. They do not automatically expose every operation, parameter, or resource-management feature available through the underlying OCI REST API or SDK.

Kid-friendly analogy

A school has a standard form for borrowing ordinary books. If you need a special archive operation that the form does not offer, you must use an authorized route that actually supports that operation. You cannot assume that every archive function is hidden behind the standard form.

In this OCI AI integration, this means: Prefer a native action when its documented contract meets the requirement; use a verified API route only when the required capability or control is not exposed by the action.

Decision Native OCI AI action REST invocation
Best starting point A documented operation is available and its supported fields satisfy the use case. The required API operation, parameter, or resource-management behavior is not available through the native action.
Contract Use the generated action request and response schemas. Use the actual OCI API contract and a supported OIC connection/authentication route.
Identity Configure the documented OIC-to-OCI service-access prerequisites. Verify the selected API's supported authentication and how the OIC caller can provide it.
Proof Inspect the generated mapping schema, action result, and integration execution. Verify HTTP contract, authentication, regional endpoint, payload, returned state, and subsequent result retrieval as applicable.

This lab uses the native Language action because the documented action includes language detection. It does not use a REST Adapter to invoke the OCI Language API directly.

If a later requirement forces a REST route, separately establish the API endpoint, authentication protocol, required headers, request body, and response contract. Do not conflate a native action's identity mechanism, an OCI request-signature request, and OAuth bearer authentication. They are not interchangeable merely because each can be used to reach a cloud service.

4.4 Identity, IAM, compartments, regions, and endpoints

For a native OIC AI action, the important security question is which OIC instance is allowed to invoke which OCI service resources. Identity and Access Management (IAM) policies grant or restrict that access. The current OIC prerequisite guide instructs administrators to create a dynamic group matching the OIC instance's OAuth application client ID, then grant that group the relevant OCI service permissions. This setup is distinct from authenticating an external caller to the OIC integration.

Kid-friendly analogy

A student may show a valid library card, but that does not automatically grant access to every locked room. The card identifies the student; the room's access rules determine what the student may do. A room in another building also has its own location and entry conditions.

In this OCI AI integration, this means: Match the OIC runtime identity to an explicit IAM rule, grant only the required resource access, and independently confirm that the selected service and endpoint are available in the chosen region and realm.

In the OCI Console, the documented setup obtains the client ID through the identity domain's Oracle Cloud Services entry for the Oracle Integration instance, under its OAuth configuration and General Information. The dynamic group matching rule uses that client ID. For example, a tutorial-defined dynamic group named oic-ai-language-dg would use a rule in this form:

resource.id = 'OIC_OAUTH_APPLICATION_CLIENT_ID'

Replace the placeholder with the actual client ID copied from the OIC service instance. Do not substitute an unrelated Compute instance rule or another resource identifier.

The current OIC prerequisite guide publishes this Language policy pattern:

Allow dynamic-group oic-ai-language-dg to manage ai-service-language-family in compartment OIC_INSTANCE_COMPARTMENT

Both names are tutorial placeholders. Replace the dynamic-group name if yours differs. Oracle's current prerequisites page defines the policy's compartment placeholder as the compartment in which the Oracle Integration instance is located; follow the live prerequisites and relevant service IAM guidance for your topology rather than assuming the policy compartment is interchangeable with any compartment that contains AI data. The documented example uses manage, which is broad and must not be described as least privilege. Ask the IAM administrator to assess narrower permissions where supported, without removing permissions required by the documented operation.

For a dynamic group in a non-default identity domain, qualify the group name with its domain as required by Oracle's prerequisites. For example: Allow dynamic-group IDENTITY_DOMAIN/oic-ai-language-dg to manage ai-service-language-family in compartment OIC_INSTANCE_COMPARTMENT. Replace both placeholders with the actual domain and compartment names. The unqualified example above assumes the default identity-domain context. Create the policy at a location that can grant access to its intended compartment scope.

↗ New to OCI IAM Policies?

Learn the fundamentals of OCI IAM policies and understand how access to Oracle Cloud resources is controlled. Read the OCI IAM Policies guide →

Do not copy the Language policy to every service. The same OIC prerequisites page gives different resource families for Document Understanding, Generative AI, Generative AI Agents RAG, Speech, and Vision. In its Generative AI Agents RAG example, it lists object-family access in a compartment and genai-agent-family access in the tenancy. Those published requirements are not a reason to grant broad access without reviewing the target agent, knowledge bases, buckets, and applicable IAM guidance. See OIC AI service prerequisites and Generative AI Agents IAM policies.

Keep four dimensions distinct:

  • Identity: Which caller or OIC runtime identity is authorized?
  • Compartment: Which resources are in the requested access scope? A compartment is not itself proof of permission.
  • Region and realm: Is the service, model, or endpoint available where the action is configured? Native OCI AI service actions are documented as available in OC1, and service-level regional support differs.
  • Endpoint or model: Does the selected resource exist and support the operation? Dedicated model endpoints and Generative AI Agents endpoints are specific resources, not generic names for any regional service.

This distinction matters most when an action is visible but its call fails, a resource does not appear in the selector, or the same action works in one region but not another. OCI service availability does not prove native OIC action availability in the same region or realm.

4.5 Text, base64, stream references, and Object Storage

The selected capability determines how input is represented. OCI Language receives text through its action request. Document Understanding and Vision actions can accept file data as base64 or read from Object Storage, depending on the selected action. File-oriented jobs also use Object Storage as their input and/or output location.

Kid-friendly analogy

You can read a short note aloud to a classmate, send a copy of the note, or put the original worksheet in a labeled folder and tell the classmate where it is. A folder location is not the worksheet's contents, and permission to use the folder still matters.

In this OCI AI integration, this means: Map actual text into text fields, encode binary data only when the selected action expects base64, and use Object Storage locations plus the required permissions for file-based processing.

Representation Meaning Engineering consequence
Inline text The text itself appears in the action's request. Validate length and content, and avoid passing unnecessary sensitive values.
Base64 file content Binary file bytes are encoded into text for a payload field that expects base64. The encoded content is larger than the original file and may increase payload and memory pressure. Use supported file sizes and formats.
OIC stream reference A reference to file or stream content managed by OIC; not automatically the base64 representation required by the target action. Use the documented mapper function or file-handling pattern for the selected action. Oracle's Document Understanding guide shows oraext:encodeReferenceToBase64 for an inline document mapping from a stream reference.
Object Storage input A service reads an object from an authorized bucket using configured identifiers and the object name where required. Confirm namespace, bucket, object name/prefix as applicable, region, and the distinct permissions needed for the relevant service and storage operation.

For document or image input, choose inline base64 when the workload fits the action's documented constraints and inline mapping is appropriate. Prefer Object Storage for workflows that already stage files there or need service-side batch processing and an output artifact. The exact supported format and file-size limits belong to the selected operation; do not infer them from another service.

4.6 Synchronous actions versus asynchronous jobs

A synchronous action returns its result as part of the current invocation. An asynchronous operation creates or submits a job that must be tracked separately. A successful submission or a returned job ID is evidence of job creation—not proof that processing completed or that all inputs succeeded.

Kid-friendly analogy

If a school assistant accepts a stack of worksheets, the receipt proves the stack was handed over. It does not prove that every worksheet has been marked. You still need to check the completion record and collect the finished work.

In this OCI AI integration, this means: For an asynchronous OCI job, retain its correlation ID, inspect the documented lifecycle status, wait only within a bounded policy, and retrieve and validate the output artifact before declaring business completion.

The six families do not all expose identical runtime patterns:

  • Language: The native action offers immediate text-analysis actions and separate job operations that use Object Storage for larger file-oriented workloads.
  • Document Understanding: Immediate analysis actions coexist with processor-job operations that return a job ID and support status inspection.
  • Vision: The native action supports image analysis and separate image-job operations for batch processing.
  • Speech: The documented speech-to-text native actions manage transcription jobs; text-to-speech synthesis returns a stream reference that can be downloaded.
  • Generative AI: The documented native Chat, EmbedText, and Rerank operations return their respective model results. In the current OIC action wizard, On demand lists Chat and EmbedText; Dedicated lists Chat, Rerank, and EmbedText. Rerank uses the Endpoint selector, while Dedicated Chat/EmbedText use Endpoint ID. Do not infer on-demand Rerank support in this native action from capabilities of the underlying OCI API. Model and regional availability must be checked separately.
  • Generative AI Agents RAG: The action addresses a selected agent endpoint. It creates a new session when no prior session ID is supplied; a prior session ID can be mapped when continuing an existing conversation. The OIC guide says to set Should Stream to false in its mapper.

For async work, the operational sequence is: submit once, persist the job ID and input correlation, poll or query according to the documented API and bounded retry policy, identify a terminal state, retrieve the output, inspect item-level failures, and then validate the business result. Never blindly resubmit a costly job because an OIC caller timed out; the first submission may still be running.

4.7 Confidence, relevance, accuracy, and human review

An AI score is meaningful only when its specific definition is understood. A confidence score attached to a language label, the confidence attached to an extracted invoice field, a sentiment-class confidence, and a reranker relevance score are not interchangeable. None should automatically be read as the probability that the complete business outcome is correct.

Kid-friendly analogy

Suppose a spelling app marks one word as very likely correct. That does not prove the whole essay has no mistakes. A strict review rule can send many good essays to a teacher; a loose rule can let important errors pass. The right rule depends on what the mistakes cost.

In this OCI AI integration, this means: Define review thresholds from representative labeled results and the cost of false acceptance or rejection; do not treat the model's score as a universal business-accuracy guarantee.

OCI Language documents language detection as returning the detected language with a confidence score between 0 and 1. The underlying language-detection guide also says that when the input is multilingual, only one dominant language is returned. This matters for mixed-language supplier messages: the output should not be interpreted as a complete list of all languages present.

For the baseline, return the score and detected language without inventing a threshold. A downstream policy can later decide whether a result should continue automatically, be reviewed, or be rejected for a particular business purpose. The threshold belongs to your application policy, not to a universal rule implied by the native action.

Build a representative, human-labeled evaluation set from the intended workload:

  • Language detection: include short messages, realistic supplier wording, supported languages, and mixed-language examples; measure the proportion of correct language labels.
  • Document extraction: measure exact-field correctness, missing values, incorrect values, and table-row/column preservation against reviewed documents.
  • Vision and Speech: compare detected objects or text against labeled images; compare transcriptions with human-checked reference transcripts, including names, dates, and identifiers.
  • Generative AI: evaluate factual support, required-field completeness, refusal or boundary behavior, and invalid or unsupported output—not fluency alone.
  • RAG: measure retrieval relevance, whether the answer is supported by retrieved sources, whether important evidence was omitted, and whether the citations actually support the claims.

Choose acceptance and review policies using labeled results and the consequence of error. A small pilot can reveal obvious failure modes, but it does not establish production-grade accuracy across every language, document template, image condition, or model revision.

4.8 Privacy, source provenance, and business validation

The AI service result is one part of a controlled business outcome. The integration should retain enough provenance to explain which source and service produced the result without unnecessarily copying sensitive source content into logs or downstream envelopes.

Kid-friendly analogy

When a teacher reviews an assignment, it helps to know which worksheet was submitted and which marking guide was used. Writing every student's private details on a public noticeboard would not make the record more trustworthy; it would simply expose more information than necessary.

In this OCI AI integration, this means: Record source references, operation and region, correlation IDs, result status, and the policy/model context needed for audit, while restricting raw sensitive content in logs and downstream messages.

The following distinctions matter in enterprise processing:

  • PII detection is not complete de-identification. Language's PII capability can detect and apply supported masking, replacement, or removal behavior for configured entity types. Detection can miss content. Confirm the chosen entity coverage and inspect transformed output before relying on it.
  • Extraction is not reconciliation. An extracted invoice total, supplier name, or purchase-order number must be compared with authoritative business data and the applicable business rules.
  • Retrieval is not freshness by itself. An answer can be based on a knowledge base that has not yet ingested a recent policy update. Track the ingestion/update process and identify the source version used when available.
  • Citations are not proof by themselves. Check that cited evidence contains the claim being used and that the source is approved for the purpose.
  • Model guidance does not enforce authorization. A prompt or generated answer cannot replace downstream identity checks, privileged-write authorization, approval workflows, duplicate prevention, or transaction validation.

A reusable provenance contract should identify the source reference or artifact, service family and operation, service region, execution/correlation ID, timestamp, relevant model or endpoint identifier when exposed, output status, and the policy/evaluation version applied. For document extraction, retain evidence such as field-level results and page or position information when the action provides it. For RAG, preserve returned source references and validate them rather than storing only the final answer.

5. Build and Configure — Step by Step

Step 1 — Establish the OCI service-access prerequisite

In the OCI Console, use the identity-domain and policy setup documented on the official OIC AI prerequisites page.

  1. Open the identity domain and locate the Oracle Cloud Services entry for the OIC instance.
  2. Open the instance's OAuth configuration and copy its client ID from General Information.
  3. Create a dynamic group for the OIC instance using the documented resource.id = 'client_ID' matching rule.
  4. Create the Language IAM policy using the policy pattern and compartment definition in Oracle's current prerequisites guide. That guide currently describes the policy's compartment placeholder as the compartment containing the OIC instance; verify this against the live guide and your IAM administrator's approved policy design.
  5. Confirm with the administrator that the OIC instance, OCI Language service, and required action are available for the selected realm and region.

Checkpoint: The dynamic group matches the actual OIC OAuth application client ID, and the policy grants the required Language access. A broad policy in an unrelated compartment is not a substitute for confirming the caller and resource scope.

Step 2 — Define the integration's public request and response contracts

Create an Application integration (previously called app-driven orchestration) with a REST Adapter trigger. Define its request and response bodies using the tutorial contracts below. These examples describe this integration's public API; they are not OCI Language's raw REST schema or the generated request/response wrapper schema of the native action.

Configure the REST trigger

  1. Create an integration using the Application style (previously called App Driven Orchestration) and add a REST Adapter as its trigger.
  2. Give the trigger operation a name such as DetectSupplierMessageLanguage, set the relative resource URI to /supplier-language, and select POST.
  3. Enable both Configure a request payload for this endpoint and Configure this endpoint to receive the response. Use JSON payloads for the request and response, and supply the examples below as representative samples.
  4. Choose an inbound security policy appropriate to your environment and use the matching credentials when testing. The inbound policy protects callers of the OIC endpoint; it is separate from the dynamic-group/IAM setup that lets the OIC instance invoke OCI Language.
  5. Before finishing the wizard, make sure your trigger schemas can support the behavior you intend. If you want missing or blank fields to reach an in-flow validation branch and return your custom error envelope, the schema must allow those cases through. If the REST trigger rejects a request before orchestration, that is a trigger-level error instead and must be tested/documented separately.

Request contract

{
  "requestId": "supplier-msg-0001",
  "sourceRef": "supplier-message-001",
  "text": "Please confirm the expected arrival date for PO-10482."
}
Field Contract rule
requestId Required string containing at least one non-whitespace character. It is the integration's correlation identifier, not a credential or authorization token. Reusing it does not itself prevent duplicate execution.
sourceRef Optional synthetic source reference supplied by the caller. Verify optionality in the generated trigger schema and omit the corresponding response element when it is not supplied. Use a supported schema-definition input if the sample-generated schema does not express the required contract; do not assume a general schema editor exists. Avoid embedding sensitive supplier or personal data in identifiers.
text Required string containing at least one non-whitespace character and no more than 5,000 characters for this single-document lab. Reject missing, null, blank, or oversized text before the Language action. Enforce the original JSON type at the request boundary; do not rely on a string-converted mapper value to prove that the caller sent a JSON string.

Normalized success response

{
  "schemaVersion": "1.0",
  "requestId": "supplier-msg-0001",
  "status": "COMPLETED",
  "result": {
    "languageCode": "en",
    "languageName": "English",
    "confidence": 0.98
  },
  "provenance": {
    "service": "OCI Language",
    "operation": "Language detection",
    "sourceRef": "supplier-message-001"
  }
}

Treat schemaVersion, status, result, and provenance as the tutorial's own response design. Normalize the actual action response into this structure. The language and score above are illustrative; the integration must return the actual service result and must not fabricate a success result if the action failed or reported an error.

Application-defined error response

{
  "schemaVersion": "1.0",
  "requestId": "supplier-msg-0002",
  "status": "FAILED",
  "error": {
    "category": "VALIDATION",
    "retryable": false,
    "message": "text must be a non-empty string"
  }
}

This is an application-defined envelope, not an Oracle error schema. Assign retryable according to a deliberate error-classification policy. Validation failures should not be retried as though they were transient infrastructure errors.

A REST trigger has a response schema as well as a response body. Make sure that schema and its mapper support both the success shape and the validation-error shape—for example, by defining branch-specific fields as optional in the schema where supported. A success-only sample does not include the error object and is insufficient by itself to define both shapes. Use a complete supported response schema with optional result/provenance and error branches, and inspect the resulting mapper targets before activation. JSON samples demonstrate values; they do not by themselves declare every required, optional, nullability, or strict-type constraint. Also, the body field status is application data; it does not by itself set the HTTP status code. Configure and test the OIC response/fault behavior separately, and do not expose raw internal fault details to an external caller.

Transport behavior for this baseline: Return handled validation failures through the normal REST response mapping using the FAILED envelope. Treat this as an application-level failure on the normal HTTP success response; clients must inspect the envelope. Service invocation faults use the configured OIC fault path unless you explicitly catch and normalize them. This tutorial does not promise that trigger-level parsing, authentication, and runtime faults all return the custom envelope. If your API requires HTTP 4xx/5xx with a custom body, implement and test the supported REST fault/status configuration separately.

Step 3 — Add the native OCI Language action

In the OIC integration canvas, use the Actions panel or the Add action control at the intended point in the orchestration, then select OCI Language. The following configuration uses the current documented native action path at Perform Text Analysis and Translation with a Language Action.

Field Selection Reason
Action name DetectSupplierMessageLanguage Tutorial-defined name for clarity in the integration canvas.
Select categories Actions The lab analyzes one incoming text synchronously rather than submitting an Object Storage-backed job.
Action Language detection Returns a detected language and an associated confidence score.
Compartment Select the compartment configured for the OIC instance's Language service access. The action's selected scope must align with service availability and IAM authorization.

No custom model or model endpoint is required for this pretrained language-detection example. Do not add an arbitrary model, prompt, temperature, or agent setting to this non-generative operation.

Complete the action wizard and open its mapper. Finishing the wizard only adds and configures the action; it does not complete the request mapping or prove that execution succeeds.

Step 4 — Map the request and normalize the result

The OCI Language action requires a document key and text. Oracle's guide instructs you to expand the target request, open Request Wrapper → Body → Documents, create the target nodes for Key and Text, then map the values.

Native action target Source Mapping purpose
Documents → Key REST request → requestId Identifies the document within the request. Use a value unique to that request.
Documents → Text REST request → text Supplies the actual text for language detection.

The OCI Language batch dominant-language detection API returns top-level document results and an errors collection. Each successful document result contains a languages collection (including code, name, and score). The native action generates its own mapper schema, so use the actual nodes shown by that mapper rather than assuming its labels exactly match the raw REST JSON. For this one-document example, confirm that the returned document key corresponds to the input key and that a usable language result exists.

For this single-document lab:

  1. Map the incoming requestId to the action's document key.
  2. Map the incoming text to the action's document text.
  3. Complete the response mapper between the Language action's output and the REST trigger's response wrapper. In the mapper, expand the actual action response source and the trigger response target; do not assume their generated field names are identical.
  4. Map the incoming requestId to the output envelope so the response stays correlated with the original request.
  5. Map the returned language code, name, and score into result.languageCode, result.languageName, and result.confidence in your public response schema. Map the tutorial-defined schemaVersion, status, service name, and operation name as constants in the response mapper.
  6. Map sourceRef from the original request to provenance.sourceRef when supplied. This value is caller-provided trace metadata, not a value attested by OCI Language.
  7. Inspect the action's error collection and fault outcome. If an error is reported, the result is missing, or the returned document cannot be correlated to the request, route through the configured error/fault path. Do not return COMPLETED for an unresolved action error or absent result.

For the one-document response, select the result by its matching key and map the single detected dominant-language entry. Require a non-empty language code and a numeric score in the documented 0–1 range before setting status to COMPLETED. Keep confidence numeric in the public response. A missing or malformed result belongs on the failure path, not a default English/zero-score mapping.

For a later batch implementation, do not assume that the first result corresponds to a particular input. Correlate documents by their keys and handle each returned result or error independently. The one-document mapping here is intentionally narrower.

Step 5 — Validate input before calling the service

Add a Switch before the service call. Place the OCI Language action inside the valid-input branch, so invalid requests cannot reach it after the branches rejoin. Use the other branch to prepare the application-defined validation response. Route to the error response when requestId is absent or whitespace-only, or when text is absent, null, empty, whitespace-only, or longer than the operation permits. Check the original JSON types at the request boundary; an OIC expression over a value already converted to a string cannot reliably prove its original JSON type. If the adapter coerces invalid types, add an explicit request-validation layer before orchestration. Route only valid input to the Language action. Implement the conditions with functions supported by your OIC mapper/expression builder and test null, missing, and whitespace cases individually; do not copy an unverified XPath expression from another OIC release.

For this lab, the rule is deliberately simple:

requestId must be a string containing at least one non-whitespace character
text must be a JSON string containing at least one non-whitespace character
text must contain no more than 5,000 characters as submitted
sourceRef, when supplied, must be a string

The nonblank-field rules are application-defined. Oracle's Language operation reference documents a maximum of 100 records per batch, 5,000 characters per record, and 20,000 total characters per request for batch dominant-language detection. This tutorial sends one document, so apply the 5,000-character limit to the original text; checking trimmed text must not accidentally allow a longer untrimmed payload through. Other Language operations can have different constraints. If the REST Adapter's request schema rejects a missing field or a wrong JSON type before the orchestration starts, capture that as a trigger-level failure rather than claiming the Switch branch handled it.

Step 6 — Activate, invoke, and inspect evidence

After completing the trigger schema, validation branch, action mapping, response mapping, and error handling, open Business Identifiers and select the incoming requestId as the primary tracking field. Oracle requires at least one business identifier. Save, resolve designer validation errors, and test the configured REST connection before activation. See Assign Business Identifiers. Then:

  1. Activate the integration.
  2. Use the activated endpoint shown by OIC and a REST client configured with the trigger's selected authentication. Send a synthetic JSON request matching Step 2; replace the sample endpoint and credentials with your own values rather than publishing them in the article.
  3. Inspect the HTTP response body and transport status separately. Check that requestId, the language code/name, confidence score, and provenance fields come from the intended source elements or documented constants.
  4. Inspect the OIC integration instance and action execution details to distinguish input validation, authorization, service invocation, and output-mapping failures.
  5. Retain the request correlation ID and the relevant execution reference for testing records. Do not persist raw supplier messages unnecessarily.

The language action's output score is a model-produced result. At this stage, the integration reports the score; it does not claim that the supplier's message is factually correct or that downstream business processing is authorized.

Step 7 — Define a reusable evaluation record

The request and response envelopes establish the integration contract. Evaluation needs a separate record that preserves the expected result and the observed result, the applied policy, and the evidence used to review discrepancies.

{
  "evaluationSetVersion": "proc-language-v1",
  "caseId": "lang-en-001",
  "requestId": "supplier-msg-0001",
  "capability": "language.detect",
  "expected": {
    "languageCode": "en"
  },
  "actual": {
    "languageCode": null,
    "confidence": null
  },
  "assessment": {
    "outcome": "NOT_REVIEWED",
    "reviewerDisposition": null,
    "ruleSetVersion": "language-routing-v1"
  },
  "evidence": {
    "sourceRef": "supplier-message-001",
    "oicInstanceRef": null,
    "serviceRegion": null,
    "modelOrEndpoint": null
  }
}

This is an application-defined evaluation envelope. Populate actual and execution evidence only after a real invocation, and use null when evidence is unavailable rather than inventing a model version, result, or test outcome. Change outcome to a controlled value such as PASS, REVIEW, or FAIL only after applying a documented assessment rule.

For other service families, preserve the same high-level record shape but adapt the expected and actual values to the capability: expected invoice fields for Document Understanding, object or text labels for Vision, reference transcripts for Speech, grounded answers and retrieved source checks for RAG, or generation criteria for Generative AI.

6. Test and Prove It

The following tests define what to verify. They have not been executed in an OIC tenant as part of this tutorial; treat every expected result below as a test criterion, not a passed test.

Case Expected behavior Evidence to inspect
Positive — English text
Not executed
The request passes validation; the action returns a language result and score, which are mapped to the public response contract. HTTP response, request ID, mapped language and confidence, OIC action result, integration instance.
Boundary — mixed-language text
Not executed
For accepted mixed-language input, the integration returns the service's single detected dominant-language result. This is the model's prediction and need not match the human-reviewed reference label. It does not claim to return a list of every language present. Returned language code, score, raw action result, and the evaluation case's human-reviewed expected label.
Invalid input — blank text
Not executed
The integration returns the application-defined validation error. The OCI Language action is not invoked. Error response envelope, branch execution evidence, absence of the Language call on this path.
Misuse/failure — denied service access
Not executed
The action fails through the service-access path rather than returning a fabricated detection result. The fault is classified and inspected. OIC instance fault details, dynamic-group matching rule, policy scope, selected compartment, region/realm availability.

Additional contract checks: Test absent and null text, whitespace-only request IDs, wrong JSON types, omitted sourceRef, and text at 5,000 and 5,001 characters. Confirm that the length check applies to the original text. Verify that a handled validation failure returns the chosen transport/envelope combination and that invalid input never invokes Language. Test service-level document errors and missing/malformed results separately from invocation faults; inspect the actual JSON types of returned confidence and retryability fields.

For a meaningful language-detection evaluation, label a representative set of synthetic or approved test messages before invoking the service. Include short texts, mixed-language messages, and the languages expected in the actual workload. Compare predicted labels with reference labels; use the result distribution to determine whether a later routing rule needs a human-review path.

Do not treat one successful result as evidence of quality across all supplier messages. And do not classify a test as passed merely because OIC returned HTTP success: verify the actual service result, mapping, and downstream business decision separately.

7. Troubleshooting and Recovery

Symptom Likely layer Targeted check and correction
OCI Language is absent from the action list. OIC feature availability, edition, region, or realm. Check the current AI Feature Availability page, the tenancy's edition, realm, and OIC region. Do not assume that underlying OCI service availability implies native action availability.
The action is configured but invocation is denied. Dynamic group, IAM policy, resource scope, or service access. Verify that the matching rule contains the correct OIC OAuth application client ID; check the service resource family and policy compartment; confirm the selected action scope. Re-test after the required policy change.
The response contains missing or unmapped values. Mapper or response interpretation. Inspect the generated native-action response schema, confirm the document result and error collections, and check the source-to-target mappings. Do not fabricate a score or language when no valid result was returned.
Mixed-language text is routed incorrectly. Service-result interpretation or business policy. Remember that the documented detector returns the dominant language, not a full multilingual inventory. Add labeled evaluation cases and an application-defined review route if the result is not sufficient for automatic routing.
A file-processing job is accepted but no output is available. Asynchronous lifecycle, Object Storage access, output location, or incomplete processing. Inspect the job's documented status, correlation ID, output bucket and object location, and item-level failures. Check the service's required storage permissions. Do not interpret job creation as completion.
A RAG answer omits a recent policy change. Knowledge-base freshness, retrieval quality, or answer generation. Verify that the approved source is present and current in the configured knowledge base, inspect relevant retrieved evidence and citations, and evaluate the answer against the current policy. Do not resolve the issue by assuming the model already knows the change.

When an action fails, first separate the layer that failed: public integration validation, OIC action configuration, OCI identity/authorization, service availability, action invocation, or response mapping. This prevents an IAM or schema problem from being misdiagnosed as low AI accuracy.

8. Enterprise Considerations

Operational and cost boundaries

The architecture should account for service-specific request volume, processing mode, payload size, model choice, and retained artifacts. Dedicated Generative AI hosting introduces endpoint and AI-cluster lifecycle considerations that differ from on-demand inference. Asynchronous document, image, and speech processing also introduces job tracking and Object Storage dependencies. Estimate cost only after identifying the chosen operation, supported model/serving mode, region, expected workload, and current published pricing.

Business controls stay outside the model result

Keep authorization, invoice reconciliation, approval decisions, duplicate prevention, and privileged system updates in the appropriate control plane. Treat supplier text, uploaded files, retrieved documents, and model responses as untrusted input. When a workflow uses generative models or RAG, evaluate unsupported instructions and prompt-injection content as part of the specific risk assessment; do not apply the same threat model mechanically to unrelated deterministic operations.

Keep provenance without creating unnecessary copies of sensitive content

Preserve the identifiers, source references, execution status, and evaluation evidence needed to explain a decision. Limit raw document, audio, image, and supplier-message retention to the approved business requirement. Decide what remains in OIC logs, fault notifications, Object Storage, evaluation records, and downstream payloads; successful masking of one response does not remove sensitive values from every earlier or later copy.

9. Completion Checklist and What Comes Next

Mark the items below complete only after checking the evidence in your own environment.

  • ☐ Select the appropriate OCI AI family for a realistic requirement and explain the boundary with deterministic business processing.
  • ☐ Verify OIC native-action availability for the selected edition, realm, and region.
  • ☐ Establish the documented OIC dynamic-group and OCI Language IAM prerequisite.
  • ☐ Define the public request, normalized result, error, and evaluation contracts.
  • ☐ Map the request key and text into the Language action and map the actual detected language and score back to the public contract.
  • ☐ Test positive, mixed-language boundary, blank-input, and authorization-failure cases.
  • ☐ Record actual observations separately from expectations and review results against labeled examples.

CORE outcome: A service-selection map and a documented native Language action implementation path, ready for tenant-specific configuration and verification. The next service-specific tutorial should implement its chosen operation fully, including configuration, request mapping, output handling, capability-specific evaluation, and recovery; it should not assume these OCI services are interchangeable.

DEFERRED: Custom models, detailed document extraction, vision and speech jobs, generative model selection, vector stores and embeddings, RAG knowledge-base construction, and multi-service orchestration belong in their own implementation modules. They are not prerequisites for the Language baseline described in this article.

10. Five Useful FAQs

10.1 Can OCI Generative AI replace Language, Document Understanding, Vision, and Speech?

Not by default. Generative models can support some adjacent tasks, but each specialized service has its own operation, input contract, output semantics, and failure modes. Choose the capability that meets the requirement and has a verified execution route. Keep deterministic business validation separate regardless of the model chosen.

10.2 If a native OCI AI action is available, do I still need to understand the OCI API?

Yes, to the level needed to understand the service contract, result semantics, supported scope, and failure lifecycle. The native action simplifies integration, but it exposes a documented subset. When the required operation is not exposed, verify the API and authentication route rather than assuming a hidden native option exists.

10.3 Does a high confidence score prove that an AI result is correct?

No. A score has meaning only in the context of its particular operation and output field. Validate the result against human-labeled data and the business cost of error. Confidence, relevance, sentiment classification, and factual correctness are different measurements.

10.4 Why do some AI integrations require Object Storage and job polling?

Some service operations process documents, images, audio, or batches asynchronously. The service may create a job first, then process the input and make an output artifact available later. The integration must track the job, inspect its documented lifecycle, retrieve the result, and account for partial failures. Job acceptance alone is not completion.

10.5 Does a successful OCI AI response make the business decision safe to execute?

No. Validate the output and its provenance, enforce permissions in the relevant identity and target-system layers, apply deterministic business rules, and route uncertain or consequential results for review. An AI result is evidence to evaluate, not a substitute for authorization or approval.

11. Verified References

Availability, supported operations, models, and IAM requirements can change; revisit the relevant pages when implementing a specific operation.

  1. Oracle Integration 3 — AI Feature Availability.
  2. Oracle Integration 3 — OCI AI Service Prerequisites.
  3. Oracle Integration 3 — Add the REST Adapter as a Trigger Connection.
  4. Oracle Integration 3 — Perform Text Analysis and Translation with a Language Action.
  5. OCI Language — Service Overview.
  6. OCI Language — Language Detection.
  7. Oracle Integration 3 — Document Understanding Action.
  8. OCI Document Understanding — Service Overview.
  9. Oracle Integration 3 — Vision Action.
  10. OCI Vision — Service Overview.
  11. Oracle Integration 3 — Speech Action.
  12. Oracle Integration 3 — Generative AI Action.
  13. OCI Generative AI — Overview.
  14. Oracle Integration 3 — Generative AI Agents RAG Action.
  15. OCI Generative AI Agents — Service Overview.
  16. OCI Generative AI Agents — IAM Policies.
  17. Oracle Integration 3 — Editions and OCI AI Services Entitlements.
  18. Oracle Integration 3 — Understand Integration Styles.
  19. Oracle Integration 3 — Assign Business Identifiers.
  20. OCI Language — Operation Reference and Dominant-Language Input Limits.

12. Finally — Summary

The central architecture decision is to choose an operation that matches the evidence you have and the outcome you need. Language analyzes text; Document Understanding extracts document structure and fields; Vision analyzes image content; Speech converts speech and text; Generative AI generates text, embeddings, and rankings; Generative AI Agents RAG answers questions using configured enterprise knowledge bases.

Native OIC actions are a practical default when the documented operation meets the requirement, but their availability and capabilities are not identical to those of the underlying OCI APIs. IAM identity, realm, region, compartments, endpoint selection, file representation, and job lifecycle all influence whether the design can run correctly.

The Language baseline establishes a reusable request/result contract and demonstrates how an OCI score should be reported without turning it into an unsupported business guarantee. The most important engineering lesson is simple: an AI response is a result to validate, not proof that the business decision is correct. The next service-specific modules can build on this foundation with operation-specific implementation and evaluation evidence.

Comments