# Com / Fujitsu / Futurity / Bp / Custom / Bpm

## Overview

This package resides within the K-Opticom customer base system (`koptBp`) and implements **BPM (Business Process Management) flows** for custom business operations specific to the K-Opticom platform. It sits in the business process layer of the Fujitsu Futurity framework, acting as the orchestrator between the presentation tier and the backend data components.

The module's purpose is to define structured, executable business processes that coordinate data retrieval, validation, and transformation across common components (CC) and service components (SC). Each flow is implemented as a stateless EJB session bean, making it suitable for pooled, concurrent invocation under the EJB container.

At a high level, this package does **not** contain standalone business logic. Instead, it provides the orchestration skeleton — setting up database connections, running common pre/post-process hooks, dispatching to configured brokers, and ensuring lifecycle operations (logging, error handling) are consistently applied. The actual data work is delegated to shared CC and SC components elsewhere in the codebase.

## Sub-module Guide

### KKSv0730 — Subscription New-Registration Confirmation Restoration

**Package path:** `com.fujitsu.futurity.bp.custom.bpm.kksv0730`

The KKSV0730 sub-module handles the business process for **restoring and displaying confirmation screen data** when a user navigates back to a subscription application confirmation screen within the K-Opticom customer base. It is responsible for reconstructing the state of a pending subscription registration form by orchestrating data retrieval from multiple sources.

This sub-module consists of two primary classes:

- **`KKSV0730Flow`** — The stateless EJB entry point. It manages the request lifecycle: logging, database configuration, operation ID validation, common pre/post-processing, and delegation to the core operation handler. It validates the `operationId` header (expecting `"KKSV0730OP"`) and returns an `EL988` error for invalid requests.

- **`KKSV0730OPOperation`** — The core business logic handler. It retrieves four categories of data in sequence: customer menu display data, new registration initialization data, conditional front-screen new application data (gated by a custom execution condition), and CX strategic WG data (always executed). Each retrieval step uses its own database connection with a dedicated DB code.

The conditional execution pattern — gating `KKSV007925SC` via an `ExeConditionReqChk` against the custom field — was introduced in ticket IT2-2017-0000014 to fix incorrect data handling for specific application types. A subsequent addition in ticket ANK-4092-00-00 brought in the CX strategic WG component (`KKSV007930SC`).

## Key Patterns and Architecture

### Orchestration Architecture

The module follows a consistent two-tier pattern across its flows:

```
Request arrives
    |
    v
Flow.run()           -- Lifecycle management, validation, pre/post-hooks
    |
    v
Operation.run()      -- Core business logic: coordinated data retrieval
    |
    v
CC / SC components   -- Actual data fetching and transformation
```

This separation allows the flow to handle cross-cutting concerns (logging, error handling, database selection) while the operation focuses purely on business logic composition.

### Broker Pattern

Each data retrieval step is encapsulated as a broker configuration:

- **`CCRequestBroker`** — Delegates to common component methods for shared data retrieval.
- **`ServiceComponentBroker`** — Delegates to service component methods for application-specific logic.
- **`OperationBroker`** — Delegates to other BPM operations for reusable business logic.

Brokers are configured at the class level via dependency injection or constructor injection, and invoked at runtime through the `BPMOperator`.

### Conditional Execution Pattern

For steps that should only run under certain conditions, the module uses an injected `ExeConditionReqChk` to evaluate a condition before execution:

```
ExeConditionReqChk.isExecuteCheck(RequestParameter, ExeCondition)
```

The condition object is lazily initialized on the first call and cached. This pattern allows dynamic feature gating without conditional logic inside the broker configuration itself.

### Database Connection Strategy

Each retrieval step in an operation uses a separate `DBConnectionInfo` with its own DB code. The flow sets up a `RandomDBSSelector` for round-robin load balancing across available database servers. Different DB codes route queries to different database contexts, allowing the system to separate concerns across data domains.

### Error Handling

Errors flow upward to the BPM engine rather than being caught locally. Exception classification is handled by `DefaultCCExceptionJudge` and `DefaultSCExceptionJudge` for each component call type. Unknown operation IDs produce an `EL988` error level with the Japanese error message returned directly.

### Code Generation

The classes are generated by a template (template version `3.2.0.a`, BPMXML version `2.6`). The boilerplate (imports, class structure, lifecycle methods) is generated and should not be hand-edited. Only the logic between the generation markers should be modified.

## Dependencies and Integration

### External Dependencies

| Dependency | Purpose |
|---|---|
| `eo.business.service` | Framework layer services used by the BPM engine |
| `com.fujitsu.futurity.bp.custom.common` | Shared common components (CC) |
| `eo.business.common` | Common business utilities |

### Internal Integration

The BPM flows integrate with components across the broader K-Opticom architecture:

| Component | Layer | Purpose |
|---|---|---|
| `JKKGetMskmDmenCC` | Common Component | Retrieves customer menu display data |
| `JKKGetMskmNewInitCC` | Common Component | Initializes new registration form data |
| `KKSV007925SC` | Service Component | Retrieves front-screen new application data |
| `KKSV007930SC` | Service Component | Retrieves CX strategic WG data |
| `JKKSV073005ReqChk` | Request Checker | Custom validation condition |
| `BpOperationMapping` | Mapping | Maps `OperationBroker` invocations |
| Various mappers | Mapping | Maps service component calls to their implementations |

### BPM Framework Infrastructure

Both classes rely heavily on the Futurity BPM framework (`com.fujitsu.futurity.bp.x21.bpm`):

- **`AbstractService` / `AbstractOperation`** — Base classes providing `getBPMOperator()`, `getBeanFactory()`, and lifecycle methods.
- **`BPMOperator`** — The central orchestrator that executes the brokers.
- **`CCRequestBroker` / `ServiceComponentBroker` / `OperationBroker`** — Delegates to common components, service components, and operations respectively.
- **`MappingInitializer`** — Provides common pre/post-process hooks for request/response mapping setup and cleanup.

## Module Interaction Diagram

```mermaid
flowchart TD
    subgraph BPM["Com / Fujitsu / Futurity / Bp / Custom / Bpm"]
        subgraph KKSV0730["KKSV0730
Subscription Confirmation Restoration"]
            Flow["KKSV0730Flow
BPM Entry Point
@Stateless EJB"]
            Operation["KKSV0730OPOperation
Business Logic Handler"]
            Flow -->|"invokes via BPMOperator"| Operation
        end
        subgraph Components["Integrated Components"]
            CC_DMenu["JKKGetMskmDmenCC
Customer menu display"]
            CC_NewInit["JKKGetMskmNewInitCC
New registration init"]
            SC_Front["KKSV007925SC
Front-screen data [conditional]"]
            SC_CX["KKSV007930SC
CX strategic WG data"]
        end
        Operation -->|"target3"| CC_DMenu
        Operation -->|"target4"| CC_NewInit
        Operation -->|"target5 [conditional]"| SC_Front
        Operation -->|"target6 [always]"| SC_CX
    end
    BPM -->|"delegates to"| BPMEngine["Futurity BPM Engine"]
    BPMEngine -->|"manages"| Components
```

## Notes for Developers

### Adding New Data Retrieval Steps

To add a new data retrieval step to an existing operation:

1. Configure a new `CCRequestBroker` or `ServiceComponentBroker` field on the operation class.
2. Invoke it in the operation's `run()` method following the established pattern: set the bean factory, set the BPM operator, get the DB code from the `FUDB` connection, get the system-level DB code, create a `DBConnectionInfo`, and execute via the `BPMOperator`.
3. If the step should be conditional, initialize an `ExeCondition` on first call and gate execution with `ecrc.isExecuteCheck()`.

### Database Connection Notes

- Each step uses a separate `DBConnectionInfo` with its own DB code.
- The `RandomDBSSelector` at the flow level provides round-robin load balancing.
- Target components configured with `useDBCode=false` may use a different database routing strategy — inspect the mapper configuration to understand the actual behavior.

### Thread Safety

Flows are `@Stateless` EJBs, so the EJB container handles thread safety automatically. Instance fields hold immutable references to broker instances — no mutable state is shared between requests.

### Error Handling Conventions

- The flow catches no exceptions itself; they propagate up to the BPM engine.
- All CC/SC calls use the appropriate default exception judge for their type.
- Always verify the `operationId` before delegating — invalid IDs produce an `EL988` error immediately.

### Change History Tracking

Changes are tracked via ticket references in source code comments:
- **IT2-2017-0000014** (2017/06/01): Added conditional execution support for front-screen new application data.
- **ANK-4092-00-00** (2021/08/06): Added CX strategic WG data retrieval.

When making changes, preserve these references and follow the existing conditional execution pattern for any new gating logic.