Integration Layer between MACO APP and Oracle CCS — Process Specification (High-Level)#
Purpose: Describe the end‑to‑end process flow and responsibilities of the integration layer between MACO APP (BO4E domain) and Oracle CCS (Oracle domain). This document is intentionally technology‑agnostic: it explains what must happen, not how it is implemented.
1. Scope & Goals#
Provide a consistent, BO4E‑centric interface to MACO APP for reads, writes, and events.
Hide Oracle CCS specifics (structures, enums, endpoints) behind a Mapping Layer and a Communication Layer.
Ensure clear separation of concerns: Data Collection → Mapping → Communication.
Keep the design extensible (new BO4E objects / Oracle resources) and resilient (errors isolated, retries where appropriate).
Out of Scope#
Concrete technology choices (e.g., auth protocol details, message bus/vendor, storage type).
Physical deployment topology.
2. Glossary#
BO4E: Business Object for Energy — canonical domain model used by MACO APP.
Mapping Table: Maintained configuration that defines transformations Oracle ↔︎ BO4E (e.g., enum codes, attribute name harmonization, value normalization rules).
Data Collector: Logic that orchestrates one or more Oracle CCS REST calls to assemble the dataset needed for a single BO4E response or event.
Communication Layer: Request routing and protocol handling to/from Oracle CCS and MACO APP (without specifying concrete protocols here).
3. Conceptual Architecture#
BO4E is canonical toward MACO APP; Oracle details never leak outward.
Mapping Tables are the single source for value/code translations and can be curated without code changes.
Data Collector can fan‑out to multiple Oracle endpoints and recompose the result before mapping.
4. End‑to‑End Processes#
4.1 Read Operations (MACO APP → Oracle CCS)#
Trigger: MACO APP requests data via a BO4E‑oriented read interface.1.
Intent Validation: Integration layer validates requested BO4E object type and parameters.
2.
Collection Plan: Data Collector derives which Oracle CCS endpoints are needed and in which order (single call or multi‑call aggregation).
3.
Oracle Retrieval: Execute REST calls with the appropriate parameters; collect partial results.
4.
Aggregation: Merge/normalize Oracle fragments into a complete intermediate record set.
5.
Mapping: Apply Mapping Layer to convert intermediate Oracle representation → BO4E object(s) (attribute mapping, enum translation, unit normalization if applicable).
6.
Response Construction: Shape a BO4E‑compliant JSON response for MACO APP; include status and minimal diagnostics.
4.2 Write Operations (MACO APP → Oracle CCS)#
Trigger: MACO APP submits a BO4E JSON payload to create/update information.1.
Payload Validation: Check BO4E schema conformance and mandatory fields.
2.
Reverse Mapping: Use mapping tables to transform BO4E → Oracle representation (fields, codes, enums).
3.
Invocation Plan: Determine target Oracle CCS endpoint(s) and invocation order.
4.
Oracle Invocation: Call Oracle CCS REST endpoint(s) with the transformed payload.
5.
Result Normalization: Convert Oracle result/status to a normalized outcome for MACO APP (success, partial, or failure with reasons).
4.3 Event Handling (Oracle CCS → MACO APP)#
Trigger: Oracle CCS emits a JSON event (e.g., status change).1.
Event Intake: Integration layer accepts the Oracle event and validates its type and minimal fields.
2.
Context Enrichment (optional): Data Collector calls Oracle CCS to fetch any additional context required by MACO APP.
3.
Mapping: Transform Oracle event data → BO4E event using mapping tables.
4.
Delivery: Send the BO4E event to MACO APP’s event consumer.
5. Sequence Diagrams#
The following diagrams illustrate message order and responsibilities without implying specific protocols.
5.1 Read Flow — Sequence#
5.2 Write Flow — Sequence#
5.3 Event Flow — Sequence#
6. Mapping Strategy#
Centralized Mapping Tables:Store enum/code translations and field‑level mapping rules for Oracle ↔︎ BO4E.
Allow curation without code changes (e.g., configuration‑driven).
Support default values and fallbacks where Oracle lacks BO4E fields (and vice versa).
One clear rule per field/type; explicitly document precedence when multiple sources exist.
Declare how to handle unknown/unsupported Oracle values (e.g., map to a known BO4E placeholder + warning) and deprecated codes.
Maintain versioned mapping sets to enable safe rollouts and rollback.
Introduce a change review routine (4‑eyes principle) for enum/code updates.
7. Data Collection Strategy#
Collection Plans: Predefined per BO4E object/event type, describing which Oracle endpoints to call and in what order.
Aggregation Rules: How partial results are combined before mapping (merge keys, deduplication, field precedence).
Parameter Derivation: Translate BO4E request parameters into Oracle query parameters (naming, paging, filters) in a consistent, documented manner.
8. Error Handling & Resilience#
Client/Validation errors (missing/invalid BO4E fields).
Oracle invocation errors (endpoint unavailable, timeouts, throttling).
Mapping errors (no mapping for value, structural mismatch).
Map Oracle HTTP/functional errors to normalized outcomes for MACO APP (do not leak Oracle specifics by default).
Apply safe retries where idempotent and meaningful (reads; certain writes only if explicitly idempotent).
Return actionable diagnostics for operators (error category, location, correlation id).
On partial data during reads, prefer explicit partial success with clear field‑level omissions where acceptable.
On event mapping issues, queue for operator review (no duplicate delivery).
9. Observability (Technology‑Agnostic)#
Tracing: Correlate MACO request ↔︎ Oracle calls ↔︎ mapping steps.
Metrics: Request rates, latency, error rates by category, mapping misses, event backlog size.
Logging: Minimal PII; structured logs with correlation ids; redaction strategy defined.
10. Security & Compliance Boundaries#
Authentication/Authorization: The integration layer enforces inbound authorization from MACO APP and ensures authenticated calls to Oracle CCS. Details of mechanisms are intentionally out of scope here.
Data Minimization: Only required fields cross the boundary; redact or drop sensitive fields not needed by MACO APP.
Auditing: Record who/what initiated writes and which mappings were applied (version/hash), without exposing secrets.
11. Versioning & Compatibility#
BO4E Contract Stability: Changes to BO4E exposures require versioned endpoints/contracts toward MACO APP.
Mapping Set Versioning: Link every request/event processing run to a specific mapping version.
Deprecation Policy: Provide a defined grace period and migration guidance when retiring mappings or BO4E fields.
Read path: P50/P95 latency targets defined per BO4E object type (collection plan dependent).
Write path: End‑to‑ack SLA that includes Oracle processing round‑trip (if synchronous), or queued handoff with delivery guarantees (if asynchronous).
Event path: End‑to‑deliver target time, plus backlog thresholds and alerting rules.
13. Operational Considerations#
Configuration: Mapping tables and collection plans are editable artifacts; changes are rollable and auditable.
Idempotency: Define idempotency keys/semantics where writes may be retried.
Backpressure: Define policies when Oracle limits are hit (throttling, graceful degradation).
Disaster Scenarios: Reads degrade gracefully; writes queue; events buffered with bounded retries and dead‑letter handling.
14. Assumptions & Open Questions#
Oracle CCS exposes all required data via REST endpoints and emits relevant events.
MACO APP consumes BO4E contracts and BO4E‑formatted events as defined here.
Open Questions (to finalize):Are there BO4E objects that need composition from multiple Oracle domains requiring transactional consistency?
Which events must be delivered at‑least‑once vs exactly‑once?
What is the minimal diagnostic payload MACO APP expects on failures?
15. Summary#
The integration layer is a translator and orchestrator: it collects Oracle data, maps it to BO4E for MACO reads and events, and converts BO4E payloads back to Oracle for writes. Central mapping governance, clear collection plans, and standardized error/observability practices ensure the solution remains maintainable, extensible, and robust without exposing implementation details.Modified at 2025-09-22 11:24:22
