orbit-code-ai 0.1.0

package/_agent_reference/components/error-handling.md

@@ -0,0 +1,117 @@
+# Error Handling
+
+Central error handling is provided by `ErrorHandler.subflow` + `ErrorHandler.esql`. Every flow MUST wire its exception terminal to the error handler.
+
+---
+
+## ErrorHandler.subflow
+
+**Purpose**: Catches all exceptions, builds a standardized error response, logs it, and routes to dead-letter or returns a business error.
+
+**Internal flow**:
+```
+Exception caught
+    ↓
+ErrorHandler.esql (build error structure)
+    ↓
+ErrorHandler_IsExceptionCaught.esql (filter: already handled?)
+    ↓
+LogError subflow (audit the error)
+    ↓
+[Route based on adapter type]
+    ├── MQ_Dead_Output_Node (async flows)
+    └── MWBusinessErrorResponse (sync/HTTP flows)
+```
+
+**ESQL modules**:
+| Module | Purpose |
+|---|---|
+| `ErrorHandler.esql` | Main: 43KB — builds error structure, maps error codes per backend |
+| `ErrorPoint.esql` | Create error message structure from exception |
+| `ErrorHandler_IsExceptionCaught.esql` | Filter: prevent double-handling |
+| `ErrorHandler_SetExceptionCaught.esql` | Mark exception as handled |
+| `ErrorHandler_IsFileSchemaValidationOccured.esql` | Detect file schema validation errors |
+| `ErrorHandler_PrepareFileDataForAudit.esql` | Prepare file error data for audit |
+| `ESBBusinessErrorResponse.esql` | Build ESB-standard business error response |
+
+---
+
+## MWBusinessErrorResponse.subflow
+
+**Purpose**: Returns a structured business error response to the caller (used in sync/HTTP flows).
+
+**When to use**: REST/HTTP flows where the caller expects a JSON error response.
+
+**Response structure**:
+```xml
+<ResponseStatus>
+  <Code>XXXXXXXX</Code>
+  <Status>Error</Status>
+  <EnglishMsg>Human readable message</EnglishMsg>
+</ResponseStatus>
+```
+
+---
+
+## Error Codes by Backend System
+
+Defined as constants in `CommonUtils.esql`:
+
+| Constant | Value | Backend |
+|---|---|---|
+| `ESB_SUCCESS_RESPONSE_CODE` | `'00000000'` | All |
+| `ESB_RUNTIME_TECHNICAL_ERROR_CODE` | `'99999999'` | All (generic) |
+| `ESB_MIDDLEWARE_DATABASE_ERROR_RESPONSE_CODE` | `'E0199998'` | DB errors |
+
+Additional backend-specific codes exist for:
+- **T24**: Core banking errors
+- **NIWS**: National Information and Workflow System
+- **ODM**: Operational Decision Manager
+- **Unifonic**: SMS/notification service
+- **MLSD**: Ministry of Labor and Social Development
+- **ICBS**: Core banking system
+
+Read `ErrorHandler.esql` directly for the full mapping if you need specific codes.
+
+---
+
+## Wiring the Error Handler in a New Flow
+
+Every node that can fail must connect its **failure/exception terminal** to `ErrorHandler`:
+
+```
+[Any Node]
+    │ failure terminal
+    ↓
+ErrorHandler.subflow
+    │
+    ├──[MQ flow]──→ MQ_Dead_Output_Node
+    └──[HTTP flow]─→ MWBusinessErrorResponse
+```
+
+**ESQL DECLARE for ErrorHandler behavior**:
+```esql
+-- Set which backend adapter this flow uses (controls error code mapping)
+DECLARE IsT24Adapter        EXTERNAL BOOLEAN FALSE;
+DECLARE IsODMWSAdapter      EXTERNAL BOOLEAN FALSE;
+DECLARE IsFrontEndJSONAdapter EXTERNAL BOOLEAN FALSE;
+DECLARE IsNIWSAdapter       EXTERNAL BOOLEAN FALSE;
+DECLARE IsUniFonicAdapter   EXTERNAL BOOLEAN FALSE;
+DECLARE IsMLSDAdapter       EXTERNAL BOOLEAN FALSE;
+DECLARE IsICBSAdapter       EXTERNAL BOOLEAN FALSE;
+```
+
+Set the appropriate flag to `TRUE` at the node level to get correct error codes for that backend.
+
+---
+
+## ErrorPoint Usage
+
+Use `ErrorPoint.esql` when you need to manually create an error structure (e.g., business validation failure before calling a backend):
+
+```esql
+-- Set error details on the Environment before routing to ErrorHandler
+SET Environment.ErrorDetails.Code = 'XXXXXXXX';
+SET Environment.ErrorDetails.EnglishMsg = 'Validation failed: ...';
+-- Then propagate to ErrorHandler via failure terminal
+```

package/_agent_reference/components/http-adapters.md

@@ -0,0 +1,134 @@
+# HTTP Adapters & Internal Service Caller
+
+Used for outbound HTTP calls (to backends or internal services) and for chaining ACE flows together.
+
+---
+
+## HTTPRequestAdapter.subflow
+
+**Purpose**: Makes an outbound HTTP or SOAP call to an external backend system.
+
+**Supported backends**: T24, NIWS, ODM, Unifonic, MLSD, ICBS, and any REST/SOAP service.
+
+**ESQL helpers**:
+| Module | Purpose |
+|---|---|
+| `HTTPResponseAdapter_CheckCallType.esql` | Determine INTERNAL vs EXTERNAL call |
+| `InternalHTTPRequestAdapter_Remove_MQRFH2.esql` | Strip MQRFH2 headers before HTTP call |
+
+**ESQL DECLARE flags** (set at node level):
+```esql
+DECLARE IsT24Adapter          EXTERNAL BOOLEAN FALSE;
+DECLARE IsODMWSAdapter        EXTERNAL BOOLEAN FALSE;
+DECLARE IsFrontEndJSONAdapter EXTERNAL BOOLEAN FALSE;
+DECLARE IsNIWSAdapter         EXTERNAL BOOLEAN FALSE;
+DECLARE IsUniFonicAdapter     EXTERNAL BOOLEAN FALSE;
+DECLARE IsMLSDAdapter         EXTERNAL BOOLEAN FALSE;
+DECLARE IsICBSAdapter         EXTERNAL BOOLEAN FALSE;
+```
+
+Set exactly ONE of these to `TRUE` to get correct request formatting and error code mapping for that backend.
+
+**URL/endpoint**: Set in `Environment.Destination.HTTP.RequestURL` before calling this subflow, or configure in `BankIdForRoutingService` properties group.
+
+---
+
+## HTTPResponseAdapter.subflow
+
+**Purpose**: Processes the HTTP response from a backend call, normalizes it to the standard ESB response structure.
+
+**ESQL helper**: `HTTPResponseAdapter_CheckCallType.esql`
+- Routes differently based on whether it was an `INTERNAL` or `EXTERNAL` call
+
+**Always pair with** `HTTPRequestAdapter` — use both or neither.
+
+---
+
+## InternalServiceCaller.subflow
+
+**Purpose**: Calls another ACE message flow in the same broker (service-to-service chaining without going through HTTP).
+
+**ESQL modules**:
+| Module | Purpose |
+|---|---|
+| `InternalServiceCaller_Compute.esql` | Build the internal call message |
+| `InternalServiceCaller_Filter.esql` | Route based on call success/failure |
+
+**Configuration** (from `Variables` group in Properties):
+```xml
+<group name="Variables">
+  <property name="callCorrIDOffset" value="1" />
+</group>
+```
+
+`callCorrIDOffset`: Offset added to correlation ID to uniquely identify this leg of the flow chain.
+
+**When to use**: When this flow needs to call another ESB service internally, without the overhead of an HTTP round-trip.
+
+---
+
+## HTTPInternalCaller.subflow
+
+**Purpose**: Calls an internal ACE service via HTTP (when the service is exposed as a REST endpoint).
+
+**When to use**: Internal HTTP calls where the target flow is REST-exposed. Prefer `InternalServiceCaller` for non-HTTP internal calls.
+
+**ESQL module**: `Internal_HTTP_CheckMessageDomain.esql` — checks if the message domain is correct for internal HTTP.
+
+---
+
+## InternalHTTPRequestAdapter.subflow
+
+**Purpose**: Variant of `HTTPRequestAdapter` optimized for internal (within-broker) HTTP calls.
+
+**ESQL helper**: `InternalHTTPRequestAdapter_Remove_MQRFH2.esql` — strips MQ headers that shouldn't be forwarded over HTTP.
+
+---
+
+## Call Type Reference
+
+| Scenario | Subflow to Use |
+|---|---|
+| Call T24 / NIWS / ODM / external backend | `HTTPRequestAdapter` + `HTTPResponseAdapter` |
+| Chain to another ACE flow (non-HTTP) | `InternalServiceCaller` |
+| Chain to another ACE REST flow | `HTTPInternalCaller` |
+| Internal HTTP (broker-to-broker) | `InternalHTTPRequestAdapter` |
+
+---
+
+## Wiring Pattern (External Backend Call)
+
+```
+[Your flow logic]
+    ↓
+HTTPRequestAdapter      ← set IsT24Adapter=TRUE (or relevant flag)
+    ↓
+HTTPResponseAdapter     ← normalizes response
+    ↓
+[Continue flow / LogOutgoingAudit / Output Adapter]
+
+Error path:
+HTTPRequestAdapter (failure) → ErrorHandler
+HTTPResponseAdapter (failure) → ErrorHandler
+```
+
+---
+
+## Setting the Target URL
+
+Via Properties `BankIdForRoutingService` group (multi-value):
+```xml
+<group name="BankIdForRoutingService">
+  <property name="qiwa">
+    <value>T24</value>                          <!-- bank/system ID -->
+    <value>SCALNT01</value>                     <!-- service name -->
+    <value>http://host:port/service/endpoint</value>  <!-- URL -->
+  </property>
+</group>
+```
+
+Access in ESQL:
+```esql
+DECLARE targetUrl CHARACTER;
+SET targetUrl = Environment.Properties.{AppLabel}.{flowName}.BankIdForRoutingService.qiwa[3];
+```

package/_agent_reference/components/input-adapters.md

@@ -0,0 +1,101 @@
+# Input Adapters
+
+All input adapters live in `Qiwa/Framework/Lib/`. Use them as the entry point of every message flow.
+
+---
+
+## MQ_Input_Node.subflow
+
+**Purpose**: MQ asynchronous input. Reads from a queue, loads properties, optionally audits, validates, and supports retry/rollback.
+
+**Internal wiring** (what it does inside):
+1. Reads message from MQ queue
+2. Calls `PropertyReader` to load flow config into `Environment.Properties`
+3. Checks `IsPropertiesEnabled` → `IsAuditEnabled` → `IsRetryEnabled` → `IsRollBackEnabled` → `IsSchemaValidationNeeded`
+4. Prepares audit message via `MQ_Input_Node_PrepareAuditMessage.esql`
+5. Routes to `LogAudit` subflow
+
+**ESQL helper modules used**:
+| Module | Purpose |
+|---|---|
+| `MQ_Input_Node_IsAuditEnabled.esql` | Filter: check if audit is on |
+| `MQ_Input_Node_IsPropertiesEnabled.esql` | Filter: check if properties loaded |
+| `MQ_Input_Node_IsRetryEnabled.esql` | Filter: check if retry is on |
+| `MQ_Input_Node_IsRollBackEnabled.esql` | Filter: check if rollback is on |
+| `MQ_Input_Node_PrepareAuditMessage.esql` | Compute: build audit payload |
+
+**Configuration flags** (set in Properties XML under `Logging` group):
+```
+AuditEnabled      TRUE/FALSE
+LogEnabled        TRUE/FALSE
+RetryEnabled      TRUE/FALSE   (also under Retry group)
+ValidationEnabled TRUE/FALSE   (under SchemaValidation group)
+```
+
+**ESQL DECLARE for this node**:
+```esql
+DECLARE IsAuditEnabled   EXTERNAL BOOLEAN FALSE;
+DECLARE IsRetryEnabled   EXTERNAL BOOLEAN FALSE;
+DECLARE IsRollBackEnabled EXTERNAL BOOLEAN FALSE;
+```
+
+**When to use**: Any flow that reads from an IBM MQ queue asynchronously.
+
+---
+
+## File_Input_Node.subflow
+
+**Purpose**: Reads files from the file system. Supports audit, schema validation, and property loading.
+
+**ESQL helper modules used**:
+| Module | Purpose |
+|---|---|
+| `File_Input_Node_IsAuditEnabled.esql` | Filter: audit check |
+| `File_Input_Node_IsPropertiesEnabled.esql` | Filter: properties check |
+| `File_Input_Node_IsSchemaValidationNeeded.esql` | Filter: validate file schema |
+| `File_Input_Node_PrepareAuditMessage.esql` | Compute: build audit payload |
+
+**Configuration flags**:
+```
+AuditEnabled      TRUE/FALSE
+LogEnabled        TRUE/FALSE
+ValidationEnabled TRUE/FALSE
+```
+
+**When to use**: Any flow triggered by a file drop (batch processing, file-based integration).
+
+---
+
+## Rest_Input_Node.subflow
+
+**Purpose**: HTTP REST input. Accepts JSON requests, loads properties, supports audit.
+
+**When to use**: Any flow exposed as a REST endpoint.
+
+**Notes**:
+- JSON body is parsed into `XMLNSC` domain internally
+- Standard `Header` structure must be present in the request
+
+---
+
+## Common Pattern Across All Input Adapters
+
+Every input adapter follows this sequence:
+```
+[Input Node]
+    ↓
+PropertyReader          ← load XML config into Environment tree
+    ↓
+AuditPoint (incoming)   ← log request if AuditEnabled=TRUE
+    ↓
+[Your flow logic]
+    ↓
+AuditPoint (outgoing)   ← log response if AuditEnabled=TRUE
+    ↓
+[Output Adapter]
+```
+
+Error path from any point:
+```
+[Any Node] → ErrorHandler → LogError → MQ_Dead_Output_Node / MWBusinessErrorResponse
+```

package/_agent_reference/components/output-adapters.md

@@ -0,0 +1,124 @@
+# Output Adapters
+
+All output adapters live in `Qiwa/Framework/Lib/`. Use them as the exit point of every message flow.
+
+---
+
+## MQ_Output_Node.subflow
+
+**Purpose**: Standard MQ output. Writes message to a target queue.
+
+**ESQL module**: `MQ_Output_Node.esql`
+- Copies message headers (`CopyMessageHeaders`)
+- Sets MQ destination queue from `Environment.Destination.MQ.DestinationData.queueName`
+
+**When to use**: Standard async MQ output for any request or response message.
+
+---
+
+## MQ_Dead_Output_Node.subflow
+
+**Purpose**: Routes failed/unprocessable messages to a backout/dead-letter queue.
+
+**ESQL module**: `MQ_OutputNode_IsDeadFlow.esql`
+
+**When to use**: Always wire this as the terminal node on the error path of every MQ flow.
+
+**Queue naming**: `<ORIGINAL_QUEUE_NAME>.BACKOUT`
+
+---
+
+## MQ_Dynamic_Output_Node.subflow
+
+**Purpose**: Selects the target queue at runtime (from message content or environment).
+
+**When to use**: Flows where the destination queue varies per message (e.g., routing based on `ServiceCode`).
+
+**How it works**: Reads queue name from `Environment.Destination.MQ.DestinationData.queueName` — set this dynamically in your compute ESQL before calling this subflow.
+
+---
+
+## MQ_ReplyToQ_Node.subflow
+
+**Purpose**: Sends response back to the `ReplyToQ` specified in the incoming MQ message header.
+
+**When to use**: Synchronous request/reply MQ patterns where the caller specifies a reply-to queue.
+
+**How it works**: Uses `InputRoot.MQMD.ReplyToQ` automatically.
+
+---
+
+## File_Output_Node.subflow
+
+**Purpose**: Writes output to the file system.
+
+**ESQL helper modules**:
+| Module | Purpose |
+|---|---|
+| `File_Output_Node_PrepareData.esql` | Format data for file output |
+| `File_Output_Node_PrepareAuditData.esql` | Prepare audit record for file operations |
+
+**When to use**: File-based output (batch export, file drop for downstream systems).
+
+---
+
+## HTTPRequestAdapter.subflow
+
+**Purpose**: Makes outbound HTTP/SOAP calls to backend services.
+
+**ESQL helper**: `HTTPResponseAdapter_CheckCallType.esql`
+- Determines `INTERNAL` vs `EXTERNAL` call type
+
+**When to use**: Any flow that calls an external REST or SOAP service (T24, NIWS, ODM, Unifonic, MLSD, etc.).
+
+**Call types**:
+- `INTERNAL`: service-to-service within ACE
+- `EXTERNAL`: calls to backend systems outside ACE
+
+---
+
+## HTTPResponseAdapter.subflow
+
+**Purpose**: Handles and normalizes HTTP responses from backend calls.
+
+**ESQL helper**: `HTTPResponseAdapter_CheckCallType.esql`
+
+**When to use**: Always paired with `HTTPRequestAdapter`. Handles both success and fault responses.
+
+---
+
+## FileCopy.subflow
+
+**Purpose**: Copies a file from one location to another within a flow.
+
+**When to use**: File routing/archival scenarios.
+
+---
+
+## Output Adapter Selection Guide
+
+| Scenario | Use |
+|---|---|
+| Async MQ send | `MQ_Output_Node` |
+| Failed message / error terminal | `MQ_Dead_Output_Node` |
+| Queue chosen at runtime | `MQ_Dynamic_Output_Node` |
+| Sync MQ reply | `MQ_ReplyToQ_Node` |
+| Write to file system | `File_Output_Node` |
+| Call backend HTTP/SOAP service | `HTTPRequestAdapter` + `HTTPResponseAdapter` |
+| Copy file | `FileCopy` |
+
+---
+
+## ESQL Copy Utilities (used in all adapters)
+
+Every output adapter uses these standard procedures from `copy_Compute.esql`:
+
+```esql
+-- Copy all MQ and transport headers
+CALL CopyMessageHeaders();
+
+-- Copy entire message tree
+CALL CopyEntireMessage();
+```
+
+Always call `CopyMessageHeaders()` before modifying output to preserve MQ metadata (MQMD, MQRFH2).

package/_agent_reference/components/property-reader.md

@@ -0,0 +1,100 @@
+# Property Reader
+
+`PropertyReader.subflow` loads external XML configuration into the `Environment.Properties` tree at runtime. It MUST be the first subflow called in every message flow.
+
+---
+
+## Components
+
+| Component | Type | Purpose |
+|---|---|---|
+| `PropertyReader.subflow` | subflow | Load XML config file into Environment tree |
+| `PropertyReader_LoadProperties.esql` | esql | Parse properties XML and build Environment tree |
+
+---
+
+## How It Works
+
+1. Reads the XML properties file (e.g., `ACCOUNT-PROPERTIES.xml`)
+2. Parses the hierarchical group structure
+3. Builds the `Environment.Properties` tree matching the XML hierarchy
+4. Substitutes runtime variables: `${broker.name}`, `${execution.group}`, `${flow.name}`, etc.
+
+---
+
+## Accessing Properties in ESQL
+
+Properties are accessed via the path:
+```
+Environment.Properties.{ApplicationLabel}.{FlowName}.{Group}.{PropertyName}
+```
+
+Examples:
+```esql
+-- Check if audit is enabled
+Environment.Properties.BS_Account.GetAccountDetails.Logging.AuditEnabled
+
+-- Get retry max count
+Environment.Properties.BS_Account.GetAccountDetails.Retry.maxRetryCount
+
+-- Get a routing service URL
+Environment.Properties.BS_Account.GetAccountDetails.BankIdForRoutingService.qiwa[1]
+```
+
+---
+
+## Properties File Structure
+
+See `config/properties-template.md` for the full XML template.
+
+**Key groups** available for every flow:
+
+| Group | Properties |
+|---|---|
+| `Logging` | `LogEnabled`, `AuditEnabled`, `MaskingEnabled`, `key1-key10`, `value1-value10`, `maskingIn`, `maskingOut` |
+| `Retry` | `RetryEnabled`, `maxRetryCount`, `minWaitDurationSec` |
+| `Variables` | `callCorrIDOffset` |
+| `SchemaValidation` | `ValidationEnabled` |
+| `Priority` | `Priority` (MQ message priority 0-9) |
+| `BankIdForRoutingService` | Multi-value: bank ID, routing service name, URL |
+
+---
+
+## Runtime Variable Substitution
+
+These tokens in property values are replaced at runtime:
+
+| Token | Replaced With |
+|---|---|
+| `${broker.name}` | ACE broker/integration node name |
+| `${execution.group}` | Execution group / integration server name |
+| `${flow.name}` | Message flow name |
+| `${application.name}` | Application name |
+
+---
+
+## ESQL Node Properties for PropertyReader
+
+```esql
+-- Required EXTERNAL declarations in the module using PropertyReader
+DECLARE ApplicationLabel EXTERNAL CHARACTER '';
+DECLARE PropertiesFileName EXTERNAL CHARACTER '';
+```
+
+Set `ApplicationLabel` and `PropertiesFileName` at the node level in the flow:
+- `ApplicationLabel`: e.g., `BS_Account`
+- `PropertiesFileName`: e.g., `ACCOUNT-PROPERTIES.xml`
+
+---
+
+## Wiring
+
+```
+[Input Node]
+    ↓
+PropertyReader          ← ALWAYS first
+    ↓
+[rest of flow]
+```
+
+Never call `AuditPoint`, `RetryPoint`, or any other framework component before `PropertyReader` — they all depend on `Environment.Properties` being populated.

package/_agent_reference/components/retry.md

@@ -0,0 +1,107 @@
+# Retry Mechanism
+
+The framework provides configurable retry for MQ-based flows using `RetryPoint.subflow`.
+
+---
+
+## Components
+
+| Component | Type | Purpose |
+|---|---|---|
+| `RetryPoint.subflow` | subflow | Re-queue message after failure with delay |
+| `SetRetryProperties.esql` | esql | Set retry tracking headers on MQRFH2 |
+
+---
+
+## How It Works
+
+1. On failure, message is caught by `ErrorHandler`
+2. `ErrorHandler` checks `RetryEnabled` from Properties
+3. If enabled, routes to `RetryPoint`
+4. `SetRetryProperties.esql` increments retry count in `MQRFH2.usr.retry`
+5. Message is re-queued to `MQRFH2.usr.sourceQueue` after `minWaitDurationSec`
+6. When `maxRetryCount` is reached → route to `MQ_Dead_Output_Node`
+
+---
+
+## Configuration (Properties XML)
+
+Under the `Retry` group for each flow:
+
+```xml
+<group name="Retry">
+  <property name="RetryEnabled"        value="TRUE" />
+  <property name="maxRetryCount"       value="5" />
+  <property name="minWaitDurationSec"  value="60" />
+</group>
+```
+
+| Property | Default | Description |
+|---|---|---|
+| `RetryEnabled` | `FALSE` | Enable/disable retry |
+| `maxRetryCount` | `5` | Max attempts before dead-lettering |
+| `minWaitDurationSec` | `60` | Seconds to wait before re-queue |
+
+---
+
+## MQRFH2 Headers Used
+
+| Header | Purpose |
+|---|---|
+| `MQRFH2.usr.retry` | Current retry attempt count |
+| `MQRFH2.usr.sourceQueue` | Original queue to re-queue to |
+
+---
+
+## ESQL for Retry Check
+
+```esql
+-- Check current retry count
+DECLARE retryCount INT;
+SET retryCount = InputRoot.MQRFH2.usr.retry;
+
+-- Get max from properties
+DECLARE maxRetry INT;
+SET maxRetry = Environment.Properties.{AppLabel}.{flowName}.Retry.maxRetryCount;
+
+IF retryCount >= maxRetry THEN
+    -- route to dead letter
+ELSE
+    -- increment and re-queue
+    SET OutputRoot.MQRFH2.usr.retry = retryCount + 1;
+END IF;
+```
+
+---
+
+## Wiring in a Flow
+
+Retry is an alternative path to dead-letter on the error route:
+
+```
+[Failure]
+    ↓
+ErrorHandler
+    ↓
+[RetryEnabled=TRUE AND retryCount < maxRetryCount]
+    ↓
+RetryPoint          ← re-queue with delay
+    
+[RetryEnabled=FALSE OR retryCount >= maxRetryCount]
+    ↓
+MQ_Dead_Output_Node ← permanent failure
+```
+
+---
+
+## When to Enable Retry
+
+Enable retry for:
+- Backend service temporarily unavailable
+- Database connectivity issues
+- Transient network failures
+
+Do NOT enable retry for:
+- Business validation failures (bad input data won't get better)
+- Schema validation failures
+- Security/authorization errors