---
# === IDENTITY ===
id: business/erp-integration/oracle-vbcs-erp-extensions/2026
canonical_question: "When should you use Oracle VBCS vs custom pages vs embedded analytics for ERP UI extensions?"
aliases:
  - "Oracle Visual Builder Cloud Service ERP extension patterns"
  - "VBCS vs Page Composer vs App Composer for Oracle Fusion"
  - "Oracle Visual Builder Studio extension types and limitations"
  - "When to use VBCS standalone vs embedded for Fusion Cloud ERP"
entity_type: erp_integration
domain: business > erp-integration > oracle-vbcs-erp-extensions
region: global
jurisdiction: global
temporal_scope: 2025-2026

# === SYSTEM PROFILE ===
systems:
  - name: "Oracle Visual Builder Studio (VBS)"
    vendor: "Oracle"
    version: "26.01"
    edition: "Included with Fusion Apps"
    deployment: cloud
    api_surface: "REST"
  - name: "Oracle Visual Builder Cloud Service (VBCS)"
    vendor: "Oracle"
    version: "26.01"
    edition: "Standalone (OIC component)"
    deployment: cloud
    api_surface: "REST"

# === VERIFICATION ===
last_verified: 2026-03-09
confidence: 0.87
version: 1.0
first_published: 2026-03-09

# === TEMPORAL VALIDITY ===
temporal_validity:
  status: volatile
  last_breaking_change: "26.01 (January 2026) — maintenance release with Redwood rollout fixes"
  next_review: 2026-09-05
  change_sensitivity: high

# === CONSTRAINTS ===
constraints:
  - "VBS (embedded) cannot connect to external databases or create custom business objects — use standalone VBCS or APEX for that"
  - "VBS (embedded) restricts secured external REST calls unless Oracle Fusion IAM is configured — unsecured REST is allowed"
  - "Standalone VBCS requires separate OCI tenancy and Oracle Integration Cloud license — not included in Fusion Apps subscription"
  - "Page Composer cannot modify application logic — only UI layout changes (show/hide/reorder fields)"
  - "Application Composer custom objects are limited to simple data storage and forms — no complex UI workflows"
  - "200 Visual Builder instances per region per OCI tenancy (service limit)"
  - "Extensions must follow Redwood design guidelines — non-Redwood custom UI breaks upgrade compatibility"
  - "OTBI/BIP embedded analytics cannot be modified via VBCS — they require separate OTBI/BIP authoring tools"

# === SKIP CONDITIONS ===
skip_this_unit_if:
  - condition: "User needs to build a standalone web/mobile app not related to Oracle Fusion"
    use_instead: "Oracle APEX or standalone VBCS documentation"
  - condition: "User needs to integrate data between ERP systems (not UI extensions)"
    use_instead: "business/erp-integration/oracle-integration-cloud-capabilities/2026"
  - condition: "User needs embedded analytics or reporting within Fusion pages"
    use_instead: "Oracle OTBI or Oracle Analytics Cloud documentation"

# === AGENT HINTS ===
inputs_needed:
  - key: extension_type
    question: "What type of UI extension do you need?"
    type: choice
    options:
      - "modify existing Fusion Redwood page (add/remove/reorder fields)"
      - "create entirely new application page within Fusion"
      - "build standalone app with external data sources"
      - "embed analytics or reports in Fusion pages"
  - key: user_audience
    question: "Who will use the extended UI?"
    type: choice
    options:
      - "internal Fusion users only"
      - "external users (partners, suppliers, customers)"
      - "both internal and external"
  - key: data_source
    question: "Where does the data come from?"
    type: choice
    options:
      - "Fusion business objects only (Service Catalog)"
      - "Fusion data + external REST APIs"
      - "custom database (ATP/DBCS) + Fusion data"
      - "third-party SaaS APIs only"

# === DISTRIBUTION ===
canonical_source: "https://knowledgelib.io/business/erp-integration/oracle-vbcs-erp-extensions/2026"
suggested_citation: "Source: knowledgelib.io — AI Knowledge Library (verified 2026-03-09)"

# === RELATED UNITS ===
related_kos:
  depends_on: []
  related_to: []
  solves: []
  alternative_to: []
  often_confused_with: []

# === SOURCES ===
sources:
  - id: src1
    title: "Extending Oracle Cloud Applications with Visual Builder Studio"
    author: Oracle
    url: https://docs.oracle.com/en/cloud/paas/visual-builder/visualbuilder-building-appui/what-is-extension.html
    type: official_docs
    published: 2025-10-01
    reliability: authoritative
  - id: src2
    title: "Creating Extensions for Oracle Cloud Applications Using Visual Builder Studio (VBS)"
    author: Cloudare
    url: https://blogs.cloudare.in/2025/08/creating-extensions-for-oracle-cloud-applications-using-visual-builder-studio-vbs/
    type: technical_blog
    published: 2025-08-01
    reliability: moderate_high
  - id: src3
    title: "Customization Options for Oracle Fusion SaaS Applications"
    author: Apps Associates
    url: https://appsassociates.com/blog/customization-options-for-oracle-cloud-infrastructure/
    type: technical_blog
    published: 2025-01-15
    reliability: moderate_high
  - id: src4
    title: "Oracle VBCS Redwood Adoption"
    author: Apps Associates
    url: https://appsassociates.com/blog/oracle-vbcs-redwood-adoption/
    type: technical_blog
    published: 2025-06-01
    reliability: moderate_high
  - id: src5
    title: "Oracle Visual Builder Service Limits"
    author: Oracle
    url: https://docs.oracle.com/en-us/iaas/visual-builder/doc/service-limits.html
    type: official_docs
    published: 2025-10-01
    reliability: authoritative
  - id: src6
    title: "What's New in Oracle Visual Builder Studio 26.01.0"
    author: Oracle
    url: https://docs.oracle.com/en/cloud/paas/visual-builder/visualbuilder-whats-new/index.html
    type: vendor_release_notes
    published: 2026-01-01
    reliability: authoritative
  - id: src7
    title: "Visual Builder Service Connections - Advanced Topics"
    author: Oracle
    url: https://blogs.oracle.com/vbcs/post/visual-builder-service-connections-advanced-topics
    type: official_docs
    published: 2024-06-01
    reliability: high
---

# Oracle VBCS vs Custom Pages vs Embedded Analytics for ERP UI Extensions

## TL;DR

- **Bottom line**: Use Visual Builder Studio (VBS, embedded in Fusion) for modifying Redwood pages and creating new internal-facing App UIs; use standalone VBCS only when you need external user access, custom database storage, or secured third-party REST APIs.
- **Key limit**: VBS (embedded) cannot connect to external databases or create custom business objects — it can only access Fusion Business Objects via the Service Catalog and call unsecured external REST endpoints. [src1, src3]
- **Watch out for**: Confusing VBS (embedded, free with Fusion license) with standalone VBCS (requires separate OIC license) — they share the same UI builder but have different deployment models, data access, and licensing. [src3, src4]
- **Best for**: Organizations extending Oracle Fusion Cloud ERP/HCM/CX with custom Redwood pages, conditional field visibility, new App UIs, and embedded workflows — all without leaving the Fusion security context.
- **Authentication**: VBS extensions inherit Fusion's identity and SSO automatically; standalone VBCS requires OAuth 2.0 or SAML configuration for Fusion REST API access. [src4, src7]

## System Profile

Oracle provides two deployment modes for Visual Builder that share the same low-code development environment but differ significantly in capability, licensing, and integration scope. Visual Builder Studio (VBS) is embedded within Oracle Fusion Cloud Applications and included in the SaaS license. It enables developers to modify delivered Redwood pages, create new App UIs, and extend existing workflows — all within the Fusion security perimeter. Standalone Visual Builder Cloud Service (VBCS), part of Oracle Integration Cloud (OIC), runs on a separate OCI tenancy and can connect to external databases, custom business objects, and secured third-party REST services. This card covers both modes and when to choose each, alongside Page Composer, Application Composer, and embedded analytics (OTBI/BIP) as alternative extension approaches. [src1, src3, src4]

| Property | Value |
|---|---|
| **Vendor** | Oracle |
| **System** | Oracle Visual Builder Studio 26.01 (embedded) / VBCS 26.01 (standalone) |
| **API Surface** | REST (Fusion Service Catalog, external REST endpoints) |
| **Current Release** | 26.01 (January 2026) |
| **Editions Covered** | Fusion Apps SaaS (all editions for embedded VBS); OIC Standard/Enterprise (for standalone VBCS) |
| **Deployment** | Cloud |
| **API Docs URL** | [Visual Builder Studio Docs](https://docs.oracle.com/en/cloud/paas/visual-builder/) |
| **Status** | GA |

## API Surfaces & Capabilities

This section maps the UI extension tools available for Oracle Fusion Cloud, not traditional API surfaces. Each tool addresses a different extension need. [src1, src3, src4]

| Extension Tool | Type | Best For | Can Modify Logic? | External Data? | Custom DB? | License |
|---|---|---|---|---|---|---|
| VBS (embedded) | Low-code IDE | New App UIs, page extensions, layout rules | Yes (action chains, JS) | Unsecured REST only | No | Included with Fusion |
| Standalone VBCS | Low-code IDE | Standalone apps, external-facing portals | Yes (action chains, JS) | Any REST (secured) | Yes (ATP/DBCS) | Requires OIC license |
| Page Composer | Declarative config | Show/hide/reorder fields, add tabs | No | No | No | Included with Fusion |
| Application Composer | Declarative config | Custom objects, simple fields, groovy scripts | Limited (Groovy) | No | No | Included with Fusion |
| OTBI | Embedded analytics | Operational reports embedded in Fusion pages | No | No | No | Included with Fusion |
| BIP (BI Publisher) | Report generation | Pixel-perfect reports, PDF/Excel output | No | No | No | Included with Fusion |
| Oracle APEX | Full-stack low-code | Custom apps, EBS migration, complex logic | Yes (PL/SQL) | Yes | Yes (ADB/ATP) | Separate OCI license |

## Rate Limits & Quotas

### Per-Instance Limits

Visual Builder does not expose traditional API rate limits in the same way as transactional ERP APIs. Instead, limits are expressed as service limits on the OCI tenancy level and as Fusion REST API quotas that the extensions consume. [src5]

| Limit Type | Value | Applies To | Notes |
|---|---|---|---|
| VB instances per region | 200 | OCI tenancy | Raise via service limit increase request |
| Concurrent users per VBS workspace | No hard limit | Embedded VBS | Bound by Fusion App user license count |
| Fusion REST API calls | Subject to Fusion API quotas | All VBS/VBCS apps | Extensions share the org's Fusion API quota pool |
| Action chain timeout | 300 seconds | VBS/VBCS | Long-running processes should use ESS jobs |
| Max file upload size | 50 MB | VBS/VBCS file components | Larger files require OCI Object Storage |
| Custom business objects | Unlimited (standalone) / None (embedded) | VBCS / VBS | Embedded VBS cannot create business objects |

[src5]

### Rolling / Daily Limits

| Limit Type | Value | Window | Notes |
|---|---|---|---|
| Fusion REST API calls | Shared with org quota | 24h rolling | No separate quota for VBS-originated calls |
| ESS job submissions | 50 concurrent per pod | Per pod | Extensions submitting ESS jobs share pod-level limits |
| OIC message packs (standalone) | Based on OIC license tier | Monthly | Standalone VBCS REST calls consume OIC message credits |
| Git operations (VBS) | No documented limit | Per project | Built-in Git; external Git repos also supported |

[src5, src6]

## Authentication

| Scenario | Auth Method | Token Lifetime | Refresh? | Notes |
|---|---|---|---|---|
| VBS extension accessing Fusion BOs | Identity propagation (SSO) | Session-scoped | Auto | No configuration needed — inherits Fusion user context |
| VBS calling unsecured external REST | None / API key in header | N/A | N/A | Only unsecured endpoints unless IAM is configured |
| Standalone VBCS to Fusion REST | OAuth 2.0 (Authorization Code) | Access: 1h, Refresh: configurable | Yes | Requires Connected App setup in Fusion IAM |
| Standalone VBCS to external REST | OAuth 2.0 / Basic / API Key | Varies | Varies | Full auth flexibility on standalone instances |
| VBCS to OCI services | OCI IAM / Resource Principal | Session-scoped | Auto | For Oracle Functions, Object Storage, ATP |

[src4, src7]

### Authentication Gotchas

- VBS (embedded) identity propagation means all REST calls run as the logged-in Fusion user — field-level security and data security policies apply to API responses, which can cause different users to see different data in the same custom page. [src1]
- Standalone VBCS connecting back to Fusion REST requires a Connected App registration in Fusion IAM (IDCS or OCI IAM) — this is a multi-step setup that involves redirect URIs, scope definitions, and token endpoints. [src7]
- When VBS extensions call external REST endpoints, the call originates from Oracle's cloud infrastructure IP ranges — firewalls on the target service must allowlist Oracle Cloud IP ranges, not individual user IPs. [src7]

## Constraints
<!-- Agents: read this section before recommending any integration approach from this unit.
     These are hard constraints that must not be violated. -->

- VBS (embedded) is limited to Fusion Business Objects via the Service Catalog — it cannot create or access custom database tables. If the requirement includes custom data persistence, use standalone VBCS with ATP/DBCS. [src3]
- VBS (embedded) can only call unsecured external REST endpoints natively — secured external REST requires Oracle Fusion IAM domain configuration (not trivial). [src3, src7]
- Page Composer modifications are metadata-only — they cannot add application logic, custom validations, or complex conditional workflows. [src3]
- Application Composer custom objects support simple forms and Groovy scripts but not complex multi-step UIs or Redwood layouts. [src3]
- All VBS extensions must follow Redwood design guidelines — custom CSS or non-Redwood components risk breaking during quarterly Fusion updates. [src2]
- Extensions should be modular and not hardcode dependencies on specific Fusion application versions — Oracle delivers quarterly updates that can change internal page structures. [src2]
- OTBI reports can be embedded in Fusion pages but cannot be authored or modified via VBCS — they require OTBI/BIP authoring tools. [src3]
- Standalone VBCS apps deployed outside Fusion do not inherit Fusion's navigation, Springboard, or role-based menu — they run as separate web applications. [src4]

## Integration Pattern Decision Tree

```
START — User needs to extend Oracle Fusion Cloud ERP UI
|
+-- What type of extension?
|   |
|   +-- Modify existing Redwood page (add/remove/reorder fields)?
|   |   |
|   |   +-- Simple field show/hide/reorder only?
|   |   |   +-- YES -> Page Composer (no code, instant)
|   |   |   +-- NO (need conditional logic, action chains) -> VBS Page Extension
|   |   |
|   |   +-- Need to add new custom fields to data model?
|   |       +-- YES -> Application Composer (custom fields + Groovy)
|   |       +-- Then use VBS to control UI rendering
|   |
|   +-- Create entirely new application page?
|   |   |
|   |   +-- Internal Fusion users only?
|   |   |   +-- Data from Fusion BOs only?
|   |   |   |   +-- YES -> VBS App UI (embedded, free)
|   |   |   |   +-- NO -> Need custom DB?
|   |   |   |       +-- YES -> Standalone VBCS + ATP
|   |   |   |       +-- NO (external unsecured REST) -> VBS App UI
|   |   |   +-- Need secured external REST?
|   |   |       +-- Configure Fusion IAM for VBS, or use Standalone VBCS
|   |   |
|   |   +-- External users (partners, suppliers, customers)?
|   |       +-- YES -> Standalone VBCS (separate URL, own auth)
|   |       +-- Consider Oracle APEX for complex external portals
|   |
|   +-- Embed analytics/reports in Fusion pages?
|   |   |
|   |   +-- Operational reporting (real-time Fusion data)?
|   |   |   +-- OTBI (embedded, included in license)
|   |   |
|   |   +-- Pixel-perfect output (PDF, Excel)?
|   |   |   +-- BIP (BI Publisher)
|   |   |
|   |   +-- Advanced analytics (ML, cross-source)?
|   |       +-- Oracle Analytics Cloud (separate license)
|   |
|   +-- Need complex custom logic + database + full-stack?
|       +-- Oracle APEX (PL/SQL, full DB access)
|       +-- Or OCI custom app (ADF is deprecated for new development)
|
+-- Licensing check
    +-- Embedded VBS -> Included in Fusion Apps license
    +-- Standalone VBCS -> Requires Oracle Integration Cloud license
    +-- APEX -> Requires OCI/ATP license
    +-- OAC -> Requires separate Oracle Analytics Cloud license
```

## Quick Reference

| Extension Need | Recommended Tool | Alternative | Licensing | Complexity |
|---|---|---|---|---|
| Show/hide fields based on role | Page Composer | VBS Layout Extension | Included | Low |
| Conditional field rendering with business rules | VBS (Dynamic Forms + Rule Sets) | Application Composer (limited) | Included | Medium |
| New multi-step workflow page (internal) | VBS App UI | APEX | Included / Separate | Medium-High |
| Custom data entry with custom DB tables | Standalone VBCS + ATP | APEX | OIC license | High |
| External-facing portal | Standalone VBCS | APEX | OIC license | High |
| Embedded operational report | OTBI | OAC | Included / Separate | Low-Medium |
| PDF/Excel document generation | BIP (BI Publisher) | — | Included | Medium |
| Dashboard with cross-source data | Oracle Analytics Cloud | OTBI (limited) | Separate | Medium-High |
| Custom object with simple form | Application Composer | VBS App UI | Included | Low |
| ESS job monitoring dashboard | VBS App UI (poll ESS REST) | Custom OCI app | Included | Medium |
| Mass data upload/import UI | VBS App UI + FBDI REST | Standalone VBCS + OIC | Included | Medium-High |

## Step-by-Step Integration Guide

### 1. Determine extension type and tool selection

Audit the business requirement against the decision tree above. Key questions: Does the extension need custom database storage? Does it serve external users? Does it need secured external REST calls? If all answers are "no," VBS (embedded) is the correct choice and requires no additional licensing. [src3, src4]

**Verify**: Check your Oracle Fusion Cloud subscription includes Visual Builder Studio access -> navigate to Developer Tools in Fusion navigator.

### 2. Create a VBS workspace and project

In Oracle Fusion, navigate to Configuration -> Visual Builder Studio. Create a new workspace, select the target Fusion environment, and create an extension project. VBS automatically provisions a Git repository for version control. [src2]

```
Fusion Navigator -> Tools -> Visual Builder Studio
-> Create Workspace -> Select Environment
-> Create Extension Project -> Select target module (ERP, HCM, CX)
```

**Verify**: Workspace dashboard shows connected environment with green status indicator.

### 3. Create an App UI or Page Extension

For a new page: create an App UI within the extension. For modifying an existing page: create a Page Extension targeting the specific delivered page. Use Dynamic Forms and Dynamic Containers for conditional content. Configure rule sets to control which fields or sections display based on user role, record type, or business rules. [src1]

```
Extension Project -> + New -> App UI (for new page)
                           -> Page Extension (to modify existing)
-> Drag components (Forms, Tables, Containers)
-> Bind to Fusion Business Objects via Service Catalog
-> Configure rule sets for conditional display
```

**Verify**: Preview the extension in the VBS design-time preview -> confirm data binding shows live Fusion data.

### 4. Configure REST service connections

For Fusion Business Objects: use the built-in Service Catalog (no configuration needed). For external REST APIs (unsecured): add a Service Connection with the endpoint URL. For external REST APIs (secured): configure the connection through Fusion IAM domain with appropriate OAuth scopes. [src7]

```
App UI -> Services tab -> + Service Connection
-> From Service Catalog (Fusion BOs) — auto-discovered
-> From Endpoint URL (external REST) — paste URL, test
-> Authentication: None (unsecured) or configure in IAM
```

**Verify**: Test the service connection from the VBS Services tab -> should return HTTP 200 with sample data.

### 5. Implement action chains and business logic

Use action chains for event-driven logic: button clicks, page load, value changes. Action chains support REST calls, navigation, variable assignment, conditional branching, and JavaScript functions. For complex logic, use JavaScript action steps with the Oracle JET framework. [src1, src2]

```
Page Designer -> Select component -> Events tab
-> Add Event Listener (e.g., on value-change)
-> Create Action Chain:
   1. Call REST endpoint (Service Catalog BO)
   2. Assign result to page variable
   3. If/Else branch on response
   4. Navigate or show notification
```

**Verify**: Run the action chain in design-time debugger -> step through each action and confirm variable assignments.

### 6. Deploy the extension to sandbox and production

VBS uses a sandbox model: deploy to a sandbox first for testing, then publish to production. The CI/CD pipeline in VBS supports automated packaging and deployment. Extensions are versioned in Git and can be rolled back. [src2]

```
VBS -> Build -> Package Extension
    -> Deploy to Sandbox (test with sandbox users)
    -> Verify in Fusion UI (sandbox mode)
    -> Publish to Production
    -> Monitor via VBS deployment history
```

**Verify**: Access the target Fusion page in sandbox mode -> confirm extension is active and functional.

## Code Examples

### JavaScript: Action Chain — Call Fusion REST API and Process Response

```javascript
// Input:  Fusion Business Object name (e.g., "purchaseOrders"), filter criteria
// Output: Filtered records displayed in a table component

// In a VBS Action Chain JavaScript function step:
define([], function () {
  'use strict';
  var PageModule = function PageModule() {};

  PageModule.prototype.filterPurchaseOrders = function (status, dateFrom) {
    // Build REST query filter for Fusion BO
    var filter = 'Status eq "' + status + '"';
    if (dateFrom) {
      filter += ' and CreationDate ge "' + dateFrom + '"';
    }
    return filter;
  };

  return PageModule;
});
```

### cURL: Test Fusion REST API from Standalone VBCS

```bash
# Input:  OAuth access token, Fusion instance URL
# Output: List of purchase orders in JSON format

# 1. Obtain OAuth token (standalone VBCS to Fusion)
curl -X POST "https://{fusion-instance}/oauth2/v1/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code&code={auth_code}&client_id={client_id}&client_secret={secret}&redirect_uri={redirect}"

# 2. Query Purchase Orders via Fusion REST API
curl -X GET "https://{fusion-instance}/fscmRestApi/resources/11.13.18.05/purchaseOrders?limit=25&onlyData=true" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json"

# Expected response: JSON array of PO records with OrderNumber, Status, Supplier, etc.
```

### JavaScript: Embed OTBI Report in VBS Page via iframe

```javascript
// Input:  OTBI analysis path, context parameters (e.g., department ID)
// Output: Embedded analytics dashboard within Fusion page

// In VBS page HTML template, use an iframe to embed OTBI:
// Note: OTBI analytics cannot be created in VBS — only embedded
var otbiUrl = '/analytics/saw.dll?Go&Path=' +
  encodeURIComponent('/shared/Custom/ERP/PO Spend Analysis') +
  '&Options=rfd&Action=Navigate&P0=1&P1=eq&P2=Department_Id&P3=' +
  departmentId;
// Assign to iframe src variable bound to the iframe component
```

## Data Mapping

### Extension Tool Capability Matrix

| Capability | Page Composer | App Composer | VBS (Embedded) | VBCS (Standalone) | APEX |
|---|---|---|---|---|---|
| Modify delivered page layout | Yes | Limited | Yes | No (separate app) | No |
| Add custom fields to BOs | No | Yes | No (use App Composer) | Yes (custom BOs) | Yes |
| Custom business logic | No | Groovy scripts | Action chains + JS | Action chains + JS | PL/SQL |
| Redwood UX compliance | Automatic | Automatic | Template-based | Template-based | Manual |
| External REST integration | No | No | Unsecured only | Full (any auth) | Full |
| Custom database tables | No | No | No | Yes (ATP/DBCS) | Yes |
| Version control (Git) | No | No | Built-in | Manual setup | No |
| CI/CD pipeline | No | No | Built-in | Manual setup | No |
| Upgrade safety | High | High | Medium (follow guidelines) | High (separate) | High |

### Data Type Gotchas

- Fusion REST API date fields use ISO 8601 format (YYYY-MM-DDThh:mm:ss+00:00) but the VBS date picker component may default to the user's locale format — always use explicit date formatting in action chains. [src1]
- Fusion Business Object LOVs (List of Values) require a separate REST call to fetch valid values — do not hardcode LOV options in VBS pages as they may change with Fusion updates. [src1]
- Custom fields added via Application Composer appear in the Fusion REST API with a "__c" suffix (e.g., "CustomField__c") — use the Service Catalog in VBS to discover the correct field names. [src3]

## Error Handling & Failure Points

### Common Error Scenarios

| Error | Meaning | Cause | Resolution |
|---|---|---|---|
| 401 Unauthorized | Token expired or invalid | OAuth token expired on standalone VBCS | Refresh token; check Connected App configuration in IAM |
| 403 Forbidden | Insufficient privileges | Fusion data security policy blocks the user | Verify role/data security for the integration user |
| 404 Not Found | BO endpoint does not exist | Wrong API version or BO not exposed | Check Fusion REST API version; verify BO in Service Catalog |
| 500 Internal Server Error | Fusion server error | Malformed REST payload or Fusion bug | Check payload format; retry; file SR with Oracle |
| Extension not visible | Extension not deployed to correct sandbox | Sandbox mismatch or deployment failure | Verify sandbox assignment; redeploy from VBS |
| CORS error | Cross-origin request blocked | Standalone VBCS calling Fusion without proper CORS config | Configure CORS in Fusion IAM; use server-side proxy |

[src1, src7]

### Failure Points in Production

- **Quarterly update breaks extension**: Oracle delivers quarterly Fusion updates that can change internal page structures. Extensions that hardcode selectors or depend on specific DOM elements break silently. Fix: `Follow Redwood extension guidelines; use only supported extension points (Dynamic Forms, Dynamic Containers); test in sandbox before update goes live.` [src2]
- **Identity propagation failure after IAM migration**: When Fusion migrates from IDCS to OCI IAM, VBS service connections may lose identity propagation. Fix: `Reconfigure service connections in VBS after IAM migration; update redirect URIs and token endpoints.` [src7]
- **VBS Git merge conflicts on multi-developer projects**: Multiple developers modifying the same extension in VBS can create JSON merge conflicts in the underlying page model. Fix: `Use feature branches; merge frequently; resolve conflicts in VBS merge tool, not text editors.` [src2]
- **Standalone VBCS OIC message quota exhaustion**: Each REST call from standalone VBCS consumes OIC message credits. High-traffic apps can exhaust the monthly quota. Fix: `Monitor OIC message consumption; implement client-side caching; consider upgrading OIC license tier.` [src3]
- **Embedded OTBI report parameters not passing correctly**: When embedding OTBI reports via iframe in VBS pages, URL-encoded parameters can be double-encoded. Fix: `Use single encodeURIComponent call; test parameter passthrough in browser dev tools.` [src3]

## Anti-Patterns

### Wrong: Building a standalone VBCS app when embedded VBS suffices

```
// BAD — Creates licensing cost, deployment complexity, and SSO configuration overhead
// when the requirement is simply a new internal Fusion page
Requirement: "Add a custom PO approval dashboard for internal procurement team"
Approach: Deploy standalone VBCS on OIC, configure OAuth, build separate app
Result: $5K-15K/year additional OIC licensing, weeks of IAM configuration
```

### Correct: Use VBS App UI for internal-only pages

```
// GOOD — No additional licensing, inherits Fusion SSO, follows Redwood UX
Requirement: "Add a custom PO approval dashboard for internal procurement team"
Approach: Create VBS App UI, bind to PO Business Objects via Service Catalog
Result: Included in existing license, deployed in hours, consistent UX
```

### Wrong: Using Page Composer for complex conditional logic

```
// BAD — Page Composer can only show/hide fields based on simple conditions
// It cannot implement multi-step workflows or call external services
Requirement: "Show different form sections based on PO amount and supplier risk score"
Approach: Use Page Composer to create conditional visibility rules
Result: Partial solution at best; no way to call risk scoring API or chain conditions
```

### Correct: Use VBS Dynamic Forms with Rule Sets

```
// GOOD — Full conditional logic with action chains and rule sets
Requirement: "Show different form sections based on PO amount and supplier risk score"
Approach: VBS Dynamic Form with rule sets; action chain calls risk API; conditional containers
Result: Full business logic support, maintainable, version-controlled
```

### Wrong: Hardcoding Fusion REST API URLs in extensions

```javascript
// BAD — URL changes with Fusion updates and environment differences
var poUrl = "https://fa-prod.oraclecloud.com/fscmRestApi/resources/11.13.18.05/purchaseOrders";
```

### Correct: Use Service Catalog bindings in VBS

```javascript
// GOOD — Service Catalog abstracts the URL and handles versioning
// In VBS, bind to Service Catalog BO "purchaseOrders"
// VBS resolves the correct endpoint at runtime
// No hardcoded URLs, works across dev/test/prod environments
```

## Common Pitfalls

- **Confusing VBS and standalone VBCS licensing**: VBS (embedded in Fusion) is free with your Fusion license. Standalone VBCS requires an Oracle Integration Cloud license. Choosing standalone when embedded would suffice wastes budget. Fix: `Use the decision tree above — choose standalone only when external users, custom DB, or secured external REST is required.` [src3, src4]
- **Not testing extensions in sandbox before quarterly updates**: Oracle's quarterly Fusion updates can break extensions that use unsupported extension points. Fix: `Always deploy to sandbox before production; subscribe to Oracle release readiness notifications; test critical extensions 4-6 weeks before update.` [src2]
- **Ignoring Redwood design guidelines**: Custom CSS, non-standard components, or third-party UI libraries in VBS extensions create upgrade risk and inconsistent UX. Fix: `Use only Redwood-approved components from the VBS component palette; follow Oracle's Redwood Design System documentation.` [src2, src4]
- **Over-engineering with Application Composer when VBS is needed**: Application Composer is great for simple custom fields and basic Groovy scripts, but attempts to build complex UIs with it lead to unmaintainable solutions. Fix: `Use Application Composer for data model extensions (custom fields/objects); use VBS for UI logic and complex workflows.` [src3]
- **Not planning for IAM changes**: Oracle is migrating Fusion customers from IDCS to OCI IAM. Extensions with hardcoded IDCS endpoints or token URLs break during migration. Fix: `Use relative URLs for auth endpoints; monitor Oracle's IAM migration timeline for your pod.` [src7]
- **Embedding OTBI reports without considering performance**: Iframe-embedded OTBI reports load asynchronously and can slow down the host VBS page. Multiple embedded reports compound the issue. Fix: `Limit to 1-2 embedded reports per page; use lazy loading; consider OAC for dashboard-heavy pages.` [src3]

## Diagnostic Commands

```bash
# Check VBS workspace status and connected environments
# Navigate to: Fusion -> Tools -> Visual Builder Studio -> Environments tab
# Verify: Environment shows "Connected" with green indicator

# Test Fusion REST API availability (from standalone VBCS or external)
curl -s -o /dev/null -w "%{http_code}" \
  "https://{fusion-instance}/fscmRestApi/resources/11.13.18.05/purchaseOrders?limit=1" \
  -H "Authorization: Bearer {token}"
# Expected: 200

# Check VBS extension deployment status
# Navigate to: VBS -> Environments -> {target env} -> Deployments
# Verify: Extension shows "Deployed" with version number

# Verify Service Catalog BO availability in VBS
# In VBS App UI: Services tab -> Service Catalog -> Search for BO name
# Verify: BO appears with available operations (GET, POST, PATCH, DELETE)

# Check OIC message consumption (standalone VBCS)
# Navigate to: OCI Console -> Integration -> Monitoring -> Message Usage
# Verify: Usage is within licensed message pack limit

# Test identity propagation from VBS to Fusion BO
# In VBS: Create test Action Chain -> Call REST BO -> Check response includes user-scoped data
# Verify: Response data matches logged-in user's data security scope
```

## Version History & Compatibility

| Release | Date | Status | Key Changes | Notes |
|---|---|---|---|---|
| 26.01 | 2026-01 | Current | Maintenance release — Redwood rollout fixes, security updates | No new extension features |
| 25.10 | 2025-07 | Supported | Enhanced Dynamic Container support, improved rule sets | Major extension framework update |
| 25.07 | 2025-04 | Supported | VBS performance improvements, new Redwood components | — |
| 25.04 | 2025-01 | Supported | Redwood page extension GA for ERP modules | First broad ERP Redwood extension support |
| 22B | 2022-07 | Legacy | First VBS support for extending VBCS (JET) pages | Limited to select pages |

[src6]

### Deprecation Policy

Oracle does not deprecate VBS features in the traditional API sense. Instead, the underlying Oracle JET framework version is updated quarterly, and extensions built on older JET patterns may require migration. Oracle provides a minimum 2-release advance notice for breaking changes to extension points. Page Composer and Application Composer remain available alongside VBS with no announced deprecation. ADF (Java Cloud Service) is considered outdated and not recommended for new development. [src3, src6]

## When to Use / When Not to Use

| Use When | Don't Use When | Use Instead |
|---|---|---|
| Need to modify existing Redwood pages (field visibility, layout) | Only need to add a custom field to a BO | Application Composer |
| Building a new internal-facing page with Fusion data only | Need external user access (partners, suppliers) | Standalone VBCS or APEX |
| Need conditional UI logic with action chains | Only need a simple operational report | OTBI |
| Need Git version control and CI/CD for UI extensions | Building a data-heavy analytical dashboard | Oracle Analytics Cloud |
| Want Redwood UX consistency across custom and delivered pages | Need custom database tables for non-Fusion data | Standalone VBCS + ATP or APEX |
| Need to embed VBCS page within a Fusion page tab | Need to call secured third-party REST APIs without IAM config | Standalone VBCS |

## Cross-System Comparison

| Capability | VBS (Embedded) | Standalone VBCS | Page Composer | App Composer | APEX |
|---|---|---|---|---|---|
| Custom UI pages | Yes (App UI) | Yes | No | No | Yes |
| Modify delivered pages | Yes (Page/Layout Extension) | No | Yes (limited) | Limited | No |
| Custom business logic | Action chains + JS | Action chains + JS | No | Groovy | PL/SQL |
| External REST APIs | Unsecured only | Any (secured) | No | No | Yes |
| Custom database | No | Yes (ATP/DBCS) | No | No | Yes |
| Git/CI/CD | Built-in | Manual | No | No | No |
| Redwood UX | Automatic | Templates | Automatic | Automatic | Manual |
| Licensing | Included | OIC license | Included | Included | OCI/ATP license |
| Upgrade risk | Medium (follow guidelines) | Low (separate) | Low | Low | Low |
| Learning curve | Medium | Medium | Low | Low | Medium-High |
| External user support | No | Yes | No | No | Yes |
| Mobile support | PWA (Redwood) | PWA + native | No | No | PWA |

## Important Caveats

- VBS extension capabilities vary by Fusion module — ERP, HCM, and CX have different extension point coverage. Not all delivered pages support Page Extensions or Dynamic Containers yet. Always check Oracle's extension availability matrix for your specific module and release. [src1]
- The distinction between VBS (embedded, free) and standalone VBCS (requires OIC license) is critical for budgeting. Many implementation partners conflate the two, leading to unexpected licensing costs. [src3, src4]
- Oracle's quarterly update cadence means extensions need ongoing maintenance. Budget for 2-4 hours of testing per extension per quarterly update. [src2]
- OTBI and BIP reports embedded in Fusion pages cannot be modified or authored via VBS — they require separate OTBI/BIP authoring tools and have their own development lifecycle. [src3]
- Oracle is actively expanding Redwood page coverage across Fusion modules. Pages still on the Classic (ADF) UI cannot be extended via VBS — they require Page Composer or Application Composer. Check Oracle's Redwood readiness documentation for your module. [src4, src6]

## Related Units
<!-- Generated from related_kos frontmatter -->

No directly related units currently published. Future units will cover Oracle Integration Cloud capabilities, Oracle Fusion REST API reference, and APEX vs VBCS detailed comparison.