---
# === IDENTITY ===
id: business/erp-integration/oracle-retail-xstore-pos-integration/2026
canonical_question: "How does Oracle Retail Xstore POS integration work - transaction posting, inventory sync, customer lookup?"
aliases:
  - "How do Xstore POS transactions flow to Oracle Retail Merchandising (RMS) via ReSA?"
  - "What APIs does Oracle Xstore Office Cloud Service expose for store data?"
  - "How does Xstore sync inventory and pricing with Oracle Merchandising Cloud?"
  - "What is the RTLog format and how does Xstore use it for transaction posting?"
entity_type: erp_integration
domain: business > erp-integration > oracle-retail-xstore-pos-integration
region: global
jurisdiction: global
temporal_scope: 2024-2026

# === SYSTEM PROFILE ===
systems:
  - name: "Oracle Retail Xstore Point of Service"
    vendor: "Oracle"
    version: "v24.0 / v23.0 / v22.0"
    edition: "All editions (Classic, Desktop, Thin Client, Tablet, Handheld)"
    deployment: "hybrid"
    api_surface: "REST, SOAP, RTLog file-based"
  - name: "Oracle Retail Merchandising System (RMS) / Merchandising Cloud Service (ORMCS)"
    vendor: "Oracle"
    version: "16.x / Cloud"
    edition: "All editions"
    deployment: "hybrid"
    api_surface: "Batch file-based, REST"
  - name: "Oracle Retail Sales Audit (ReSA)"
    vendor: "Oracle"
    version: "16.x / Cloud"
    edition: "All editions"
    deployment: "hybrid"
    api_surface: "REST, Batch import (saimptlog)"

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

# === TEMPORAL VALIDITY ===
temporal_validity:
  status: volatile
  last_breaking_change: "v24.0 containerized architecture (January 2025)"
  next_review: 2026-09-05
  change_sensitivity: high

# === CONSTRAINTS ===
constraints:
  - "Xstore does NOT manage store inventory directly when integrated with RMS/ORMCS -- inventory is managed by SIM/SIOCS"
  - "Direct transaction posting from Xstore to RMS bypassing Sales Audit (ReSA) is not supported"
  - "RTLog export jobs must run daily to prevent delta records from being purged before export"
  - "Mobile/tablet/handheld devices have no local database -- require mobile server connectivity for full functionality"
  - "Offline mode is limited to basic sales and return transactions on Desktop and Thin Client only"
  - "Foundation data exports (items, pricing, hierarchy) use pipe-delimited flat files -- not real-time APIs"
  - "REST broadcaster mapping changes take approximately 30 minutes to propagate"

# === SKIP CONDITIONS ===
skip_this_unit_if:
  - condition: "User needs Oracle Retail SIM/SIOCS inventory management details"
    use_instead: "Search knowledgelib.io for Oracle Retail SIOCS store inventory — no dedicated unit yet"
  - condition: "User needs Oracle Retail Customer Engagement (loyalty/CRM) integration"
    use_instead: "Search knowledgelib.io for Oracle Retail Customer Engagement — no dedicated unit yet"
  - condition: "User needs Oracle ERP Cloud (Financials/SCM) integration, not Retail"
    use_instead: "business/erp-integration/oracle-erp-cloud-rest-api-capabilities/2026"

# === AGENT HINTS ===
inputs_needed:
  - key: integration_pattern
    question: "What integration pattern do you need?"
    type: choice
    options:
      - "real-time transaction posting (REST broadcaster to ReSA)"
      - "batch/bulk foundation data sync (items, pricing, hierarchy)"
      - "event-driven (RTLog file-based posting)"
      - "customer lookup (DTXQL/REST queries)"
  - key: data_volume
    question: "What is your store count and daily transaction volume?"
    type: choice
    options:
      - "< 50 stores, < 10,000 transactions/day"
      - "50-500 stores, 10,000-100,000 transactions/day"
      - "> 500 stores, > 100,000 transactions/day"
  - key: direction
    question: "What is the data flow direction?"
    type: choice
    options:
      - "inbound to Xstore (foundation data: items, pricing, hierarchy from RMS)"
      - "outbound from Xstore (transactions to ReSA/RMS)"
      - "bidirectional (foundation data in + transactions out)"

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

# === RELATED UNITS ===
related_kos:
  depends_on: []
  related_to:
    - id: "business/erp-integration/oracle-erp-cloud-rest-api-capabilities/2026"
      label: "Oracle ERP Cloud (Fusion) REST API capabilities — 499-record pagination, expand vs fields, CRUD"
  solves: []
  alternative_to: []
  often_confused_with:
    - id: "business/erp-integration/oracle-erp-cloud-rest-api-capabilities/2026"
      label: "Oracle ERP Cloud (Fusion) REST API capabilities — 499-record pagination, expand vs fields, CRUD"

# === SOURCES (7 authoritative sources) ===
sources:
  - id: src1
    title: "Introduction to Oracle Retail Xstore POS"
    author: Oracle
    url: https://docs.oracle.com/en/industries/retail/retail-xstore-point-of-service/22.0/rpxmo/introduction-oracle-retail-xstore-pos.htm
    type: official_docs
    published: 2023-01-15
    reliability: authoritative
  - id: src2
    title: "Transaction Flow from Xstore to Sales Audit"
    author: Oracle
    url: https://docs.oracle.com/cd/F13595_01/xocs/pdf/210/html/xstore_merch_impl/xstore_to_resa.htm
    type: official_docs
    published: 2023-06-01
    reliability: authoritative
  - id: src3
    title: "Integration with Xstore -- RMS Operations Guide"
    author: Oracle
    url: https://docs.oracle.com/cd/E79623_01/rms/pdf/160025/html/operations_guide1/rms-integr_xstore.htm
    type: official_docs
    published: 2022-01-15
    reliability: authoritative
  - id: src4
    title: "Oracle Supercharges Retail Operations with New POS (Xstore 2025)"
    author: Oracle
    url: https://www.oracle.com/news/announcement/oraclexstore-2025-01-13/
    type: vendor_release_notes
    published: 2025-01-13
    reliability: high
  - id: src5
    title: "Implement Oracle Retail Xstore Point of Service on Oracle Cloud Infrastructure"
    author: Oracle
    url: https://docs.oracle.com/en/solutions/deploy-xstore-oci/index.html
    type: official_docs
    published: 2024-06-01
    reliability: authoritative
  - id: src6
    title: "Oracle Merchandising Cloud Integration Guide: POS and ERP Systems"
    author: SkillNet Solutions
    url: https://www.skillnetinc.com/resources/blogs/a-complete-guide-to-oracle-merchandising-cloud-service-integration-with-pos-erp-systems/
    type: technical_blog
    published: 2024-09-15
    reliability: moderate_high
  - id: src7
    title: "Xstore Office Cloud Service Administration Guide"
    author: Oracle
    url: https://docs.oracle.com/en/industries/retail/retail-xstore-cloud/24.0.101.0/xocag/F89761_01.pdf
    type: official_docs
    published: 2024-10-01
    reliability: authoritative
---

# Oracle Retail Xstore POS Integration

## TL;DR

- **Bottom line**: Xstore POS transactions flow to Oracle Retail Merchandising via Sales Audit (ReSA) using either REST broadcasting (near-real-time) or RTLog file-based export (batch); foundation data (items, pricing, hierarchy) flows from RMS to Xstore via daily pipe-delimited flat file exports.
- **Key limit**: Direct transaction posting to RMS bypassing ReSA is not supported -- all POS transactions must route through Sales Audit for validation before impacting inventory in Merchandising.
- **Watch out for**: Xstore does not manage store inventory when integrated with RMS -- inventory is handled by SIM/SIOCS. Many integrators mistakenly try to configure Xstore inventory features alongside RMS.
- **Best for**: Multi-format retailers needing unified POS across desktop, thin client, tablet, and handheld devices with transaction posting to Oracle Retail Merchandising and Sales Audit.
- **Authentication**: OAuth 2.0 for Xstore Office Cloud Service REST APIs; basic auth or certificate-based for on-premise Xcenter web services.

## System Profile

Oracle Retail Xstore Point of Service is Oracle's enterprise POS platform for specialty, department, and grocery retailers. The 2025 release introduced a containerized architecture on Oracle Cloud Infrastructure (OCI) and Oracle Autonomous Database, enabling independent deployment of Xstore components on POS terminals or cloud-hosted VMs. Xstore supports multiple form factors: Classic (traditional POS), Desktop (wide-screen), Thin Client (workstation), Tablet (iOS/Android, 8-11 inch), and Handheld (2x4 layout). [src1]

The integration ecosystem centers on three systems: Xstore POS (point of sale), Xcenter/Xstore Office Cloud Service (XOCS) as the central data hub, and Oracle Retail Merchandising System (RMS) / Merchandising Cloud Service (ORMCS) as the merchandise and inventory master. Sales Audit (ReSA) serves as the mandatory intermediary for transaction validation before data reaches Merchandising. [src2, src3]

| System | Role | API Surface | Direction |
|---|---|---|---|
| Xstore POS | Point of sale -- captures transactions, customer data, tender | POSLog XML (internal) | Outbound (transactions) |
| Xcenter / XOCS | Central store server -- aggregation, broadcasting, admin | REST API, SOAP, DTXQL | Orchestrator (bidirectional) |
| Oracle Retail Sales Audit (ReSA) | Transaction validation and audit | REST (v21+), RTLog file import | Inbound (receives transactions) |
| Oracle RMS / ORMCS | Merchandise master -- items, pricing, inventory | Batch file export, REST | Outbound (foundation data to Xstore) |
| Oracle Retail SIM / SIOCS | Store inventory management | REST, file-based | Bidirectional (inventory operations) |

## API Surfaces & Capabilities

| API Surface | Protocol | Best For | Direction | Real-time? | Bulk? |
|---|---|---|---|---|---|
| REST Broadcaster (ReSA) | HTTPS/JSON | Transaction posting from Xstore to Sales Audit | Outbound | Near-real-time | No |
| RTLog File Export | File-based (pipe-delimited) | Legacy transaction posting to ReSA | Outbound | No (batch) | Yes |
| XOCS REST API | HTTPS/JSON | Customer lookup, store data queries, admin operations | Bidirectional | Yes | No |
| DTXQL Queries | REST/HTTPS | Ad-hoc data queries against Xstore Office tables | Outbound | Yes | No |
| RMS Foundation Export | File-based (pipe-delimited) | Item master, pricing, hierarchy sync to Xstore | Inbound | No (daily batch) | Yes |
| Xcenter SOAP Services | SOAP/XML | Legacy integrations, inventory/tax engine calls | Bidirectional | Yes | No |
| Xcenter REST Services | HTTPS/JSON | Inventory (SIOCS), tax engine integration | Bidirectional | Yes | No |

[src1, src2, src3]

## Rate Limits & Quotas

### Per-Request Limits

| Limit Type | Value | Applies To | Notes |
|---|---|---|---|
| RTLog file size | System-dependent | RTLog generator | Files generated multiple times per day; size depends on transaction volume |
| REST broadcaster payload | Per-transaction JSON | ReSA REST endpoint | Each transaction posted individually in temporal order |
| DTXQL query results | Configurable page size | XOCS REST API | Pagination via GetByQueryResource |
| Foundation export file size | Unlimited (pipe-delimited) | RMS batch exports | One file per entity type per run; store-specific files for items |
| Bulk export threads | 1-20 threads | Item/location/VAT exports | Threading parameter Y/N with configurable thread count |

[src3, src7]

### Rolling / Daily Limits

| Limit Type | Value | Window | Notes |
|---|---|---|---|
| Foundation data exports | Must run daily | 24h | Delta records purged after 7 days -- daily runs mandatory |
| RTLog generation | Multiple per day | Configurable | Generated by Xcenter RTLog generator component |
| REST transaction posting | Near-real-time continuous | Ongoing | Temporal ordering preserved; no explicit rate cap documented |
| Rejected transaction query | Hourly | Scheduled | XOCS queries ReSA for rejected transactions hourly |
| Staging table purge | Weekly | 7-day retention | export_stg_purge.ksh removes all records older than 7 days |

[src2, src3]

## Authentication

| Flow | Use When | Token Lifetime | Refresh? | Notes |
|---|---|---|---|---|
| OAuth 2.0 (XOCS Cloud) | Accessing Xstore Office Cloud Service REST APIs | Session-based | Yes | Set up OAuth Client per XOCS Security Guide |
| Basic Authentication | On-premise Xcenter web services | Session-based | N/A | Legacy; used for SOAP and some REST endpoints |
| Certificate-based | Server-to-server integration (on-premise) | Certificate validity | N/A | Used for secure Xcenter-to-ReSA communication |
| IDCS/OCI IAM | Cloud-native deployments on OCI | Token-based | Yes | Required for OCI Container Instances deployment |

[src5, src7]

### Authentication Gotchas

- OAuth Client setup for XOCS requires following the Oracle Retail Xstore Office Cloud Service Security Guide exactly -- missing scopes cause silent permission failures [src7]
- On-premise to cloud migration requires switching from basic auth / certificates to OAuth 2.0 -- this is not backward-compatible and breaks existing integrations if not re-configured [src5]
- REST broadcaster authentication to ReSA Cloud Service uses a separate credential set from the XOCS admin credentials -- these must be configured independently [src2]

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

- Xstore inventory functionality must be disabled when integrated with RMS -- no inventory data is exchanged between Xstore and RMS other than sales-related data. Store inventory must be managed by SIM or SIOCS. [src3]
- All POS transaction data must flow through Sales Audit (ReSA) before reaching Merchandising. Direct Xstore-to-RMS transaction posting is not supported. [src2]
- Foundation data (items, pricing, hierarchy) flows only from RMS to Xstore -- Xstore cannot write back master data changes to RMS. [src3]
- RTLog/foundation export delta mode relies on staging tables that are purged weekly. If export jobs do not run daily, delta records are permanently lost. [src3]
- Handheld devices (2x4 form factor) do not support offline transactions, reporting, employee maintenance, or training mode. [src1]
- Mobile devices (tablet, handheld, thin client) have no local database and require persistent mobile server connectivity for all operations. [src1]
- REST broadcaster mapping changes take approximately 30 minutes to propagate through the system. [src2]

## Integration Pattern Decision Tree

```
START -- Integrating Oracle Retail Xstore POS
|-- What data are you integrating?
|   |-- POS Transactions (sales, returns, voids)
|   |   |-- Xstore version >= 21.0?
|   |   |   |-- YES -> REST Broadcaster to ReSA (near-real-time, recommended)
|   |   |   |-- NO -> RTLog file-based export to ReSA (batch)
|   |   |-- Need real-time transaction visibility?
|   |   |   |-- YES -> REST Broadcaster (temporal ordering preserved)
|   |   |   |-- NO -> RTLog files (multiple times/day or once daily)
|   |   |-- Validation?
|   |       |-- ReSA validates all transactions before they reach Merchandising
|   |       |-- Rejected transactions -> XOCS hourly query + Xadmin UI for republish
|   |
|   |-- Foundation Data (items, pricing, hierarchy, stores)
|   |   |-- Initial load or ongoing sync?
|   |   |   |-- Initial -> RMS FULL mode export (all current records)
|   |   |   |-- Ongoing -> RMS DELTA mode export (changes since last run)
|   |   |-- Which entities?
|   |       |-- Items -> export_itemmaster.ksh + export_itemloc.ksh
|   |       |-- Pricing -> RPM price export integration
|   |       |-- Hierarchy -> export_merchhier.ksh + export_orghier.ksh
|   |       |-- Stores -> export_stores.ksh
|   |       |-- VAT/Tax -> export_itemvat.ksh + export_vat.ksh
|   |
|   |-- Customer Data (lookup, enrollment)
|   |   |-- Cloud (XOCS)?
|   |   |   |-- YES -> XOCS REST API with OAuth 2.0 + DTXQL queries
|   |   |   |-- NO -> Xcenter SOAP/REST web services
|   |   |-- Need loyalty/engagement?
|   |       |-- YES -> Integrate Oracle Retail Customer Engagement separately
|   |       |-- NO -> Use XOCS customer REST endpoints
|   |
|   |-- Inventory Data
|       |-- DO NOT use Xstore inventory features when integrated with RMS
|       |-- Use Oracle Retail SIM/SIOCS for store inventory management
|       |-- SIM/SIOCS integrates with both Xstore and RMS
|
|-- Deployment model?
|   |-- Cloud-native (OCI)
|   |   |-- Use containerized Xstore on OCI Container Instances
|   |   |-- Oracle Autonomous Database for persistence
|   |   |-- OCI Roving Edge for limited-connectivity locations
|   |-- On-premise -> Traditional Xcenter server deployment
|   |-- Hybrid -> Cloud Xcenter/XOCS with on-premise POS terminals
|
|-- Error handling?
    |-- REST Broadcaster -> Rejected transactions queried hourly, viewable in Xadmin
    |-- RTLog files -> saimptlog/saimptlogi validates and creates auditor errors
    |-- Foundation exports -> Monitor staging table purge schedule (weekly)
```

## Quick Reference

### Transaction Posting Flow

| Step | Source | Action | Target | Data Format | Failure Handling |
|---|---|---|---|---|---|
| 1 | Xstore POS Register | Captures sale/return/void | Local POSLog | POSLog XML | Stored locally until broadcast |
| 2 | Xcenter Broadcaster | Translates POSLog to JSON or RTLog | ReSA | JSON (REST) or RTLog (file) | Retry; rejected queue |
| 3 | ReSA REST Endpoint | Validates and accepts transaction | Staging tables | JSON | Returns success/reject; hourly reject query |
| 4 | ReSA Batch Process | Generates RTLog from staging (REST) or imports directly (file) | ReSA tables | RTLog | saimptlog/saimptlogi validation + auditor errors |
| 5 | ReSA Export | Exports validated transactions to Merchandising | RMS/ORMCS | Batch export | Impacts perpetual inventory via uploadsales_all.ksh |

### Foundation Data Export Jobs

| Job Script | Entity | Output File Pattern | Mode | Contract |
|---|---|---|---|---|
| export_itemmaster.ksh | Item master data | itemhdr_{date}_{scope}_{mode}_{lines}.dat | Full/Delta | IntCon000208 |
| export_itemloc.ksh | Item-location data | itemloc_{date}_{loc}_{mode}_{lines}.dat | Full/Delta | IntCon000209 |
| export_merchhier.ksh | Merchandise hierarchy | merchhierarchy_{date}_{mode}_{lines}.dat | Full/Delta | IntCon000207 |
| export_orghier.ksh | Org hierarchy | orghierarchy_{date}_{mode}_{lines}.dat | Full/Delta | IntCon000203 |
| export_stores.ksh | Store master + addresses | store_{date}_{mode}_{lines}.dat | Full/Delta | IntCon000204 |
| export_itemvat.ksh | Item VAT by region | vatitem_{date}_{scope}_{mode}_{lines}.dat | Full/Delta | IntCon000214 |
| export_vat.ksh | VAT regions/codes/rates | vat_{date}_{mode}_{lines}.dat | Full/Delta | IntCon000215 |
| export_diffs.ksh | Differentiators | diffs_{date}_{mode}_{lines}.dat | Full/Delta | IntCon000206 |
| export_relitem.ksh | Related items | relitemhead_{date}_{scope}_{mode}_{lines}.dat | Full/Delta | IntCon000210 |
| export_stg_purge.ksh | Staging cleanup | N/A | Purge (weekly) | RMS265 |

[src3]

## Step-by-Step Integration Guide

### 1. Configure Xstore-to-ReSA REST Broadcasting (v21+)

Set up the REST broadcaster in Xcenter to post transactions to Sales Audit in near-real-time. The broadcaster translates POSLog XML from Xstore registers into JSON payloads for the ReSA REST endpoint. [src2]

```
Endpoint: POST https://<resa-host>:<port>/<tenancyId>/ResaReSTServices/services/private/Resa/salesService

Payload format: JSON (translated from POSLog XML by Xcenter broadcaster)

Configuration steps:
1. Configure ReSA REST endpoint URL in Xcenter broadcaster settings
2. Set authentication credentials (OAuth 2.0 for cloud, basic auth for on-premise)
3. Enable temporal ordering to preserve transaction sequence
4. Configure Broadcaster Customize tab for any custom YAML mapping
```

**Verify**: Check Xadmin SystemTools > Publish PosLog Data for transaction status. Successfully posted transactions should not appear in rejected queue.

### 2. Set Up Foundation Data Exports from RMS

Configure daily batch exports to push item master, pricing, and hierarchy data from RMS to Xcenter/Xstore. [src3]

```bash
# Run full export for initial load (all current records)
./export_itemmaster.ksh <db_connection> full N

# Run delta export for daily sync (changes since last run)
./export_itemmaster.ksh <db_connection> delta Y

# Run item location export (store-specific files)
./export_itemloc.ksh <db_connection> delta Y <store_number>

# Run hierarchy exports
./export_merchhier.ksh <db_connection> delta
./export_orghier.ksh <db_connection> delta
./export_stores.ksh <db_connection> delta
```

**Verify**: Check output files in the configured export directory. File naming pattern: `itemhdr_{date}_corp_{mode}_{linecount}.dat`. Verify line counts match expected record counts.

### 3. Configure Customer Lookup via XOCS REST API

Set up OAuth 2.0 client and use DTXQL queries for customer lookup operations via the Xstore Office Cloud Service REST API. [src7]

```bash
# Step 1: Set up OAuth Client per XOCS Security Guide
# Configure in Oracle Identity Cloud Service (IDCS)

# Step 2: Obtain access token
curl -X POST "https://<idcs-host>/oauth2/v1/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials&scope=<xocs-scope>" \
  -u "<client_id>:<client_secret>"

# Step 3: Query customer data using DTXQL via REST
curl -X GET "https://<xocs-host>/xocs/rest/v1/query" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT * FROM crm_customer WHERE last_name = :lastName", "params": {"lastName": "Smith"}}'
```

**Verify**: Response should return customer records matching the query. Check HTTP 200 status and valid JSON response body.

### 4. Monitor Rejected Transactions

Configure the hourly rejected transaction query to catch validation failures and enable republishing from the Xadmin UI. [src2]

```
# Rejected transactions are queried automatically on an hourly schedule
Endpoint: GET https://<resa-host>/<tenancyId>/ResaReSTServices/services/private/Resa/getRejectedTransactions

# Rejected transactions are marked in the TRN_POSLOG_WORK_ITEM table:
# WORK_STATUS = "REJECTED"

# Republish via Xadmin UI:
# Xadmin > SystemTools > Publish PosLog Data > Select rejected transactions > Republish
```

**Verify**: Check TRN_POSLOG_WORK_ITEM table for records with WORK_STATUS = 'REJECTED'. Count should decrease after republishing.

## Code Examples

### Python: Query Customer Data via XOCS REST API

```python
# Input:  XOCS host, OAuth credentials, customer search criteria
# Output: Customer records matching the query

import requests

def get_xocs_token(idcs_host, client_id, client_secret, scope):
    """Obtain OAuth 2.0 access token from IDCS."""
    resp = requests.post(
        f"https://{idcs_host}/oauth2/v1/token",
        data={"grant_type": "client_credentials", "scope": scope},
        auth=(client_id, client_secret),
        timeout=30
    )
    resp.raise_for_status()
    return resp.json()["access_token"]

def lookup_customer(xocs_host, token, last_name):
    """Query customer by last name via DTXQL."""
    resp = requests.get(
        f"https://{xocs_host}/xocs/rest/v1/query",
        headers={"Authorization": f"Bearer {token}"},
        params={"q": f"last_name = '{last_name}'", "table": "crm_customer"},
        timeout=30
    )
    resp.raise_for_status()
    return resp.json()
```

### Bash: Monitor RTLog Export and Staging Table Health

```bash
# Input:  Database connection string, export directory path
# Output: Status of export jobs and staging table record counts

# Check if daily exports ran today
EXPORT_DIR="/path/to/exports"
TODAY=$(date +%Y%m%d)

echo "=== Foundation Data Export Status ==="
for entity in itemhdr itemloc merchhierarchy orghierarchy store; do
  FILE=$(ls ${EXPORT_DIR}/${entity}_${TODAY}_* 2>/dev/null | head -1)
  if [ -n "$FILE" ]; then
    LINES=$(wc -l < "$FILE")
    echo "OK: ${entity} exported (${LINES} records)"
  else
    echo "MISSING: ${entity} -- no export file for today"
  fi
done

# Check staging table health (run via sqlplus)
echo "=== Staging Table Record Counts ==="
sqlplus -S $DB_CONN <<EOF
SELECT 'ITEM_EXPORT_STG' AS table_name, COUNT(*) AS records FROM ITEM_EXPORT_STG
UNION ALL
SELECT 'MERCHHIER_EXPORT_STG', COUNT(*) FROM MERCHHIER_EXPORT_STG
UNION ALL
SELECT 'STORE_EXPORT_STG', COUNT(*) FROM STORE_EXPORT_STG;
EOF
```

### cURL: Test ReSA REST Endpoint Connectivity

```bash
# Input:  ReSA host, tenancy ID, auth credentials
# Output: HTTP status confirming endpoint is reachable

# Test ReSA REST service health
curl -s -o /dev/null -w "%{http_code}" \
  "https://<resa-host>:<port>/<tenancyId>/ResaReSTServices/services/private/Resa/salesService" \
  -H "Authorization: Bearer <token>"
# Expected: 200 or 405 (Method Not Allowed for GET on POST-only endpoint)

# Query rejected transactions
curl -X GET \
  "https://<resa-host>/<tenancyId>/ResaReSTServices/services/private/Resa/getRejectedTransactions" \
  -H "Authorization: Bearer <token>" \
  -H "Accept: application/json"
# Expected: JSON array of rejected transaction records (empty array if none)
```

## Data Mapping

### RTLog Record Types

| Record Type | Code | Description | Fields | Frequency |
|---|---|---|---|---|
| File Header | FHEAD | File-level metadata | File ID, creation timestamp, store ID | 1 per file (required) |
| Transaction Header | THEAD | Transaction-level header | Transaction ID, register, timestamp, type | 1 per transaction |
| Customer Record | TCUST | Customer associated with transaction | Customer ID, name, loyalty number | 0-1 per transaction |
| Item Record | TITEM | Line item detail | Item ID, quantity, price, UPC | 1+ per transaction |
| Discount Record | IDISC | Discount applied to item | Discount type, amount, reason code | 0+ per item |
| Tax Record | IGTAX | Tax applied to item | Tax type, rate, amount, jurisdiction | 0+ per item |

### Foundation Data Field Mapping (RMS to Xstore)

| RMS Source | Xstore Target | Type | Transform | Gotcha |
|---|---|---|---|---|
| ITEM_MASTER.ITEM | Xstore item ID | String | Direct mapping | Parent items exported as separate records |
| ITEM_MASTER.ITEM_DESC | Xstore item description | String | Direct | Truncation may occur on handheld displays |
| ITEM_LOC.UNIT_RETAIL | Xstore selling price | Currency | Direct | Multi-currency requires separate VAT export |
| SUBCLASS.SUB | Xstore subclass | String | Via hierarchy export | Must match merchandise hierarchy export |
| STORE.STORE | Xstore location ID | Integer | Direct | Store-specific item files filter by ITEM_LOC |
| VAT_CODE_RATES.VAT_RATE | Xstore tax rate | Decimal | Percentage to decimal | Exempt VAT regions (SVAT type) excluded from exports |

[src3]

### Data Type Gotchas

- POSLog XML uses UTC timestamps internally, but Xstore displays in store-local timezone. RTLog exports use the store timezone, causing potential mismatches in cross-timezone reporting. [src2]
- RMS foundation exports use pipe-delimited flat files. Any pipe characters in source data (item descriptions, addresses) will corrupt the file parsing. Ensure pipe characters are escaped or stripped in RMS data. [src3]
- FULL mode exports exclude deleted records entirely, while DELTA mode includes deletion markers. Downstream systems must handle both patterns. [src3]
- Store-specific item files only include items ranged to that store via ITEM_LOC. A "corporate" file includes all items but does not indicate store-level ranging. [src3]

## Error Handling & Failure Points

### Common Error Scenarios

| Scenario | Symptom | Cause | Resolution |
|---|---|---|---|
| REST broadcast rejection | Transaction in REJECTED status in TRN_POSLOG_WORK_ITEM | ReSA validation failure (missing item, invalid tender) | Review in Xadmin SystemTools > Publish PosLog Data; fix data and republish |
| RTLog import failure | saimptlog error log entries | Malformed RTLog file, missing FHEAD record, corrupt data | Check RTLogMappingConfig.xml; verify POSLog-to-RTLog mapping |
| Foundation export empty | Zero-line .dat files | No delta changes since last run, or staging table already purged | Run FULL mode export; verify export_stg_purge.ksh schedule |
| Lost delta records | Items missing in Xstore after export | Export jobs not run for > 7 days; purge removed unextracted records | Run FULL mode export to resync all current records |
| OAuth token expiration | HTTP 401 on XOCS REST API calls | Token expired, scope insufficient | Refresh token; verify OAuth client configuration in IDCS |
| Mobile server disconnection | Tablet/handheld cannot process transactions | Network outage to mobile server | Desktop/thin client can go offline; mobile devices cannot |

[src2, src3, src7]

### Failure Points in Production

- **Staging table purge destroys unextracted deltas**: If export_stg_purge.ksh runs before delta exports, changed records are permanently lost. Fix: `Schedule export jobs to run daily BEFORE the weekly purge job. Monitor DATA_EXPORT_HIST for gaps.` [src3]
- **REST broadcaster mapping propagation delay**: Custom YAML mapping changes take approximately 30 minutes to propagate. Transactions posted during this window use the old mapping. Fix: `Schedule mapping changes during low-transaction periods. Verify mapping propagation before peak hours.` [src2]
- **Offline transactions not syncing after reconnection**: Desktop/thin client offline transactions may not automatically broadcast upon reconnection if Xcenter service is not properly restarted. Fix: `Monitor the offline transaction queue in Xstore. Force a manual broadcast via Xadmin if needed.` [src1]
- **saimptlogi vs saimptlog confusion**: Using the wrong import process causes either incomplete loading (saimptlogi expects incremental flow) or duplicate processing (saimptlog expects once-daily batch). Fix: `Use saimptlogi for continuous intraday loading; use saimptlog for once-daily batch. Never mix both on the same data set.` [src2]
- **Store-specific vs corporate item files**: Using corporate item files for a specific store includes items not ranged to that store, causing phantom inventory. Fix: `Always use store-specific files (with location parameter) for individual store loads. Use corporate files only for system-wide reference.` [src3]

## Anti-Patterns

### Wrong: Bypassing ReSA for Direct RMS Transaction Posting

```
// BAD -- Attempting to post Xstore transactions directly to RMS
// This is not supported and will cause inventory discrepancies
Xstore -> Custom middleware -> RMS (direct insert to inventory tables)
```

### Correct: Route All Transactions Through Sales Audit

```
// GOOD -- Mandatory transaction flow through ReSA
Xstore -> Xcenter Broadcaster -> ReSA (validation) -> RMS (inventory impact)
// ReSA validates transaction integrity before affecting Merchandising
```

### Wrong: Enabling Xstore Inventory Features with RMS Integration

```
// BAD -- Configuring Xstore inventory management when RMS is active
// Xstore inventory must be DISABLED when integrated with RMS
// Inventory data exchange is limited to sales impact via ReSA
```

### Correct: Use SIM/SIOCS for Store Inventory Management

```
// GOOD -- Proper inventory architecture with RMS
Xstore (sales only) -> ReSA -> RMS (inventory impact via uploadsales_all.ksh)
SIM/SIOCS (inventory management) <-> RMS (inventory master)
Xstore (inventory lookup) <-> SIM/SIOCS (real-time stock queries)
```

### Wrong: Running Exports Only When Changes Are Expected

```bash
# BAD -- Skipping daily exports because "nothing changed"
# Delta records in staging tables are purged after 7 days
# If exports don't run, those deltas are permanently lost
if [ "$CHANGES_EXPECTED" = "true" ]; then
    ./export_itemmaster.ksh $DB delta Y
fi
```

### Correct: Run Export Jobs on a Fixed Daily Schedule

```bash
# GOOD -- Always run exports daily regardless of expected changes
# This prevents delta record loss from staging table purge
# Use delta mode for efficiency; switch to full mode for resync
./export_itemmaster.ksh $DB delta Y
./export_itemloc.ksh $DB delta Y
./export_merchhier.ksh $DB delta
./export_orghier.ksh $DB delta
./export_stores.ksh $DB delta
```

## Common Pitfalls

- **Confusing Oracle Retail with Oracle ERP Cloud**: Oracle Retail Xstore is part of the Oracle Retail suite (RMS, ReSA, SIM, RPM), NOT part of Oracle ERP Cloud (Financials, SCM, HCM). Integration patterns, APIs, and data models are completely different. Fix: `Verify you are referencing Oracle Retail documentation (docs.oracle.com/en/industries/retail/), not Oracle ERP Cloud documentation.` [src1]
- **Not pinning the export mode (FULL vs DELTA)**: Running FULL mode daily wastes processing time and can overwrite downstream delta tracking. Running DELTA mode for initial loads misses all pre-existing records. Fix: `Use FULL mode for initial load and periodic resync. Use DELTA mode for daily incremental updates. Never swap modes without downstream notification.` [src3]
- **Ignoring the threading parameter on large exports**: Single-threaded item exports on retailers with 500K+ items can take hours and overlap with store opening. Fix: `Enable threading (Y parameter) with 5-10 threads for item, location, and VAT exports. Monitor thread completion before declaring export complete.` [src3]
- **Deploying tablet/handheld devices without offline fallback planning**: Tablet and handheld devices have no local database and cannot process transactions when the mobile server is unreachable. Fix: `Ensure at least one Desktop or Thin Client register per store for offline capability. Implement network monitoring and failover procedures.` [src1]
- **Assuming REST broadcaster is instantaneous**: While near-real-time, the REST broadcaster preserves temporal ordering, which means high-volume stores may experience posting delays during peak hours. Fix: `Monitor the broadcaster queue depth. Scale Xcenter broadcaster instances for high-volume stores.` [src2]
- **Not monitoring the rejected transactions queue**: Rejected transactions silently fail to post to ReSA and never reach Merchandising, causing inventory and financial discrepancies. Fix: `Configure alerting on TRN_POSLOG_WORK_ITEM table for WORK_STATUS = 'REJECTED'. Review rejected transactions in Xadmin daily.` [src2]

## Diagnostic Commands

```bash
# Check RTLog export file generation (today's files)
ls -la /path/to/exports/*_$(date +%Y%m%d)_*.dat

# Verify staging table record counts (indicates pending exports)
sqlplus -S $DB_CONN <<EOF
SELECT 'ITEM_EXPORT_STG' AS tbl, COUNT(*) AS cnt FROM ITEM_EXPORT_STG
UNION ALL SELECT 'STORE_EXPORT_STG', COUNT(*) FROM STORE_EXPORT_STG
UNION ALL SELECT 'MERCHHIER_EXPORT_STG', COUNT(*) FROM MERCHHIER_EXPORT_STG;
EOF

# Check rejected transaction count in XOCS
curl -X GET "https://<xocs-host>/ResaReSTServices/services/private/Resa/getRejectedTransactions" \
  -H "Authorization: Bearer <token>" | python -c "import sys,json; print(len(json.load(sys.stdin)))"

# Test XOCS REST API authentication
curl -s -o /dev/null -w "%{http_code}" \
  "https://<xocs-host>/xocs/rest/v1/health" \
  -H "Authorization: Bearer <token>"

# Monitor Xcenter broadcaster queue depth
# (Check via Xadmin UI: SystemTools > Publish PosLog Data)

# Verify foundation data export schedule compliance
find /path/to/exports -name "*.dat" -mtime +1 -printf "%f -- STALE (>1 day old)\n"
```

## Version History & Compatibility

| Version | Release Date | Status | Key Changes | Migration Notes |
|---|---|---|---|---|
| v24.0 | 2024-10 | Current | Containerized architecture on OCI; OCI Roving Edge support | Major architecture change; requires OCI infrastructure for new deployment model |
| v23.0 | 2023-10 | Supported | Pay By Link tenders; enhanced mobile support | Incremental upgrade from v22; REST APIs backward-compatible |
| v22.0 | 2023-01 | Supported | Dark mode; enhanced accessibility | Standard upgrade path |
| v21.0 | 2022-01 | Supported (EOL approaching) | REST broadcaster for ReSA introduced | First version with REST-based transaction posting; upgrade recommended |
| v20.0 | 2021-01 | EOL | Last version before REST broadcaster | RTLog file-based only; upgrade to v21+ for REST posting |

[src1, src4]

### Deprecation Policy

Oracle Retail follows a minimum 2-year support policy for major Xstore releases. New features and security patches are only delivered on the current and previous major versions. The 2025 containerized architecture on OCI represents a generational shift -- retailers on v20.0 or earlier should plan migration. [src4]

## When to Use / When Not to Use

| Use When | Don't Use When | Use Instead |
|---|---|---|
| You need to integrate Oracle Retail POS with RMS/ORMCS for merchandise and transaction management | You need financial ERP integration (AP, AR, GL) | Oracle ERP Cloud REST API or Financials integration |
| You are deploying multi-format retail POS (desktop + tablet + handheld) | You need e-commerce / digital commerce integration | Oracle Commerce Cloud / ATG integration |
| You need to post POS transactions through Sales Audit (ReSA) for validation | You need warehouse management integration | Oracle WMS or SIM/SIOCS integration |
| You need to sync foundation data (items, pricing, hierarchy) from RMS to POS | You need real-time inventory availability across channels | Oracle Retail SIOCS or OMS integration |
| You are an Oracle Retail ecosystem customer (RMS, RPM, SIM, ReSA) | You use a non-Oracle merchandising system | Custom POS integration or alternative POS platform |

## Important Caveats

- Xstore integration architecture varies significantly between on-premise (Xcenter server) and cloud (XOCS) deployments. API authentication, endpoint URLs, and configuration methods differ. Always verify your deployment model before following integration instructions.
- The 2025 containerized architecture (v24+) is a major shift that may affect existing custom integrations. Custom Xcenter extensions may need to be re-containerized.
- Foundation data exports are file-based and batch-oriented. There is no real-time API for pushing item/pricing changes from RMS to Xstore. Expect a minimum 24-hour delay for master data changes to reach POS.
- Offline transaction capability is only available on Desktop and Thin Client form factors. Retailers relying heavily on mobile (tablet/handheld) POS must ensure robust network infrastructure.
- Rate limits and throughput for REST broadcaster transaction posting are not explicitly documented by Oracle. Performance depends on Xcenter server capacity, network bandwidth, and ReSA processing speed.
- This card covers the Oracle Retail-specific integration. Oracle ERP Cloud (Fusion) uses completely different APIs (REST, SOAP, FBDI) and is a separate product line.

## Related Units

- [Oracle ERP Cloud REST API](/business/erp-integration/oracle-erp-cloud-rest-api/2026) -- Different Oracle product line (Financials/SCM, not Retail)