# Business Logic — JKKUseFailMapperCC.mappingEKK0161A010SCInMsg() [42 LOC]

| Field | Value |
|-------|-------|
| Fully Qualified Name | `com.fujitsu.futurity.bp.custom.common.JKKUseFailMapperCC` |
| Layer | CC/Common Component (Custom Common Component) |
| Module | `common` (Package: `com.fujitsu.futurity.bp.custom.common`) |

## 1. Role

### JKKUseFailMapperCC.mappingEKK0161A010SCInMsg()

This method serves as the input message mapper for the Service Contract Cancellation execution Service Component (`EKK0161A010SC`). In the K-Opticom telecommunications billing system, when a customer initiates a service contract cancellation (cancelSvcKei), this mapper builds the CAANMsg request template that is sent downstream to the service component processing the cancellation. It performs three key business operations: first, it initializes all fields of the template to null to ensure no stale data leaks into the request; second, it sets the SIF (Service Interface) template ID to `"EKK0161A010"`; and third, it resolves the function code and populates the template with the appropriate contextual fields depending on whether the cancellation is a standard subscription agreement cancellation (function code `"1"`) or an alternative function code path. The method implements a dispatch-by-function-code pattern, branching into two distinct data-population paths — the standard path retrieves the service contract detail number and generation registration datetime from a separate message list class (`EKK0161B004CBSMsg1List`), while the alternative path retrieves them directly from the CBS message class (`EKK0161A010CBSMsg`). It acts as a shared utility called by cancellation-related CBS classes such as `JKKCancelSvcKeiCC` and `JKKCancelSvcKeiMapperCC`.

## 2. Processing Pattern (Detailed Business Logic)

```mermaid
flowchart TD
    START(["mappingEKK0161A010SCInMsg"]) --> NULL_MAP["fillCAANMSGNullMapping"]
    NULL_MAP --> SET_TEMPLATE["Set TEMPLATEID = 'EKK0161A010'"]
    SET_TEMPLATE --> GET_FUNC["Get funcCode from inHash FUNC_CODE"]
    GET_FUNC --> CHECK_NULL{"funcCode == null?"}
    CHECK_NULL -->|Yes| DEFAULT_FUNC["funcCode = FUNC_CODE_ONE"]
    CHECK_NULL -->|No| SET_FUNC["Set FUNC_CODE on template"]
    DEFAULT_FUNC --> SET_FUNC
    SET_FUNC --> CHECK_FUNC{"FUNC_CODE_ONE.equals(funcCode)?"}
    CHECK_FUNC -->|Yes| BRANCH_ONE["Branch: funcCode = '1'
(FTTH Subscription Agreement)"]
    CHECK_FUNC -->|No| BRANCH_OTHER["Branch: Other funcCode"]
    BRANCH_ONE --> SET_SVC_ONE["Set KEY_SVC_KEI_UCWK_NO from EKK0161B004CBSMsg1List"]
    BRANCH_ONE --> SET_GENE_ONE["Set KEY_GENE_ADD_DTM from EKK0161B004CBSMsg1List"]
    BRANCH_OTHER --> SET_SVC_OTHER["Set KEY_SVC_KEI_UCWK_NO from EKK0161A010CBSMsg"]
    BRANCH_OTHER --> SET_RSV_OTHER["Set KEY_RSV_APLY_YMD from EKK0161A010CBSMsg"]
    SET_GENE_ONE --> END_NODE(["Return"])
    SET_RSV_OTHER --> END_NODE
```

**Constant Resolution:**

| Constant | Resolved Value | Business Meaning |
|----------|---------------|------------------|
| `FUNC_CODE_ONE` | `"1"` (from `JPCModelConstant.FUNC_CD_1`) | Function code 1 — Standard service subscription agreement cancellation |
| `FUNC_CODE_TWO` | `"2"` (from `JPCModelConstant.FUNC_CD_2`) | Function code 2 — Alternative function path |
| `FUNC_CODE_THR` | `"3"` (from `JPCModelConstant.FUNC_CD_3`) | Function code 3 — Tertiary function path |
| `TEMPLATEID` | `"EKK0161A010"` | Service Interface ID for the cancellation service |

## 3. Parameter Analysis

| No | Parameter Name | Type | Business Description |
|----|---------------|------|---------------------|
| 1 | `template` | `CAANMsg` | The output message template (request payload) for the `EKK0161A010SC` Service Component. This is a `CAANMsg` object that acts as a key-value message container used in the K-Opticom SIF (Service Integration Framework). It carries all the field-level data that will be sent to the downstream cancellation processing service. The method populates this object in-place. |
| 2 | `inHash` | `HashMap<String, Object>` | The input context map carrying cancellation request parameters. It contains the function code (`FUNC_CODE`) that determines which data-population branch to take, and may also contain the service contract detail number (`SVC_KEI_UCWK_NO`) and related fields from various CBS message list classes. The values in this hash are extracted by key and written into the template. |

**External/Instance fields read:**

| Field | Type | Business Description |
|-------|------|---------------------|
| `FUNC_CODE_ONE` | `static final String` | Constant `"1"` — represents the standard service subscription agreement cancellation function code. Resolved from `JPCModelConstant.FUNC_CD_1`. |
| `FUNC_CODE_TWO` | `static final String` | Constant `"2"` — available for future alternative function paths. |
| `FUNC_CODE_THR` | `static final String` | Constant `"3"` — available for future alternative function paths. |

## 4. CRUD Operations / Called Services

| CRUD | SC / CBS | SC Code | Entity / DB | Operation Description |
|------|----------|---------|-------------|----------------------|
| U | `JKKUseFailMapperCC.fillCAANMSGNullMapping` | - | - | Null-maps all fields of the `template` message by iterating over the schema contents of `EKK0161A010CBSMsg`. This is a cleanup/preparation operation that clears any stale or leftover field values before populating the template with fresh data. |
| U | `JKKUseFailMapperCC.template.set()` | - | - | Writes field values into the `CAANMsg` template at multiple keys: `TEMPLATEID`, `FUNC_CODE`, `KEY_SVC_KEI_UCWK_NO`, and either `KEY_GENE_ADD_DTM` or `KEY_RSV_APLY_YMD` depending on the function code branch. |
| R | `EKK0161A010CBSMsg.getContents()` | - | - | Retrieves the schema definition (field name and type pairs) for the `EKK0161A010SC` message template. Used as the reference for null-mapping to ensure all expected fields are initialized. |
| R | `inHash.get()` | - | - | Reads values from the input hash map by key. Called for `FUNC_CODE`, `SVC_KEI_UCWK_NO` (from two possible keys depending on branch), `GENE_ADD_DTM`, and `KEY_RSV_APLY_YMD`. |

**Classification reasoning:**
- `fillCAANMSGNullMapping` is a **U** (Update/Initialize) operation — it sets all fields of the template to null values.
- `template.set()` is a **U** (Update) operation — it writes field values into the message template.
- `getContents()` is an **R** (Read) operation — it reads the schema definition array.
- `inHash.get()` is an **R** (Read) operation — it reads values from the input context map.

This method does **not** directly call any service component (SC) or database-backed CBS method. It is purely a **mapper/preparer** method that transforms the input hash into a structured request message.

## 5. Dependency Trace

| # | Caller (Screen/Batch) | Call Chain (Full Path to this Method) | Terminal (SC / CRUD / Entity) |
|---|----------------------|--------------------------------------|-------------------------------|
| 1 | CBS: `JKKCancelSvcKeiCC` | `JKKCancelSvcKeiCC` -> `cancelSvcKeiMapper.mappingEKK0161A010SCInMsg(template, inHash)` | `fillCAANMSGNullMapping [U] CAANMsg template` |
| 2 | CBS: `JKKCancelSvcKeiMapperCC` | `JKKCancelSvcKeiMapperCC` -> `mappingEKK0161A010SCInMsg(template, inHash)` (own class, lines 372) | `fillCAANMSGNullMapping [U] CAANMsg template` |
| 3 | CBS: `JKKAdchgHakkoSODCC` | `JKKAdchgHakkoSODCC.mappingEKK0161A010SCInMsg(template, inHash, funcCode)` -> `JKKUseFailMapperCC.mappingEKK0161A010SCInMsg` (3-param variant) | `fillCAANMSGNullMapping [U] CAANMsg template` |
| 4 | CBS: `JKKHakkoSODCC` | `JKKHakkoSODCC.mappingEKK0161A010SCInMsg(template, inHash, funcCode)` -> `JKKUseFailMapperCC.mappingEKK0161A010SCInMsg` (3-param variant) | `fillCAANMSGNullMapping [U] CAANMsg template` |
| 5 | CBS: `JKKAdchgCancelHakkoSODCC` | `JKKAdchgCancelHakkoSODCC.mappingEKK0161A010SCInMsg(template, inHash, funcCode)` -> `JKKUseFailMapperCC.mappingEKK0161A010SCInMsg` (3-param variant) | `fillCAANMSGNullMapping [U] CAANMsg template` |
| 6 | (Commented-out) `JKKSVUseFailAddCC` | `useFailMapper.mappingEKK0161A010SCInMsg(template, map)` (line 1318, commented) | `fillCAANMSGNullMapping [U] CAANMsg template` |
| 7 | (Commented-out) `JKKSVUseFailChgCC` | `useFailMapper.mappingEKK0161A010SCInMsg(template, map)` (line 1450, commented) | `fillCAANMSGNullMapping [U] CAANMsg template` |

**Notes:**
- The primary live callers are cancellation-related CBS classes: `JKKCancelSvcKeiCC`, `JKKCancelSvcKeiMapperCC`, `JKKAdchgHakkoSODCC`, `JKKHakkoSODCC`, and `JKKAdchgCancelHakkoSODCC`.
- `JKKAdchgHakkoSODCC`, `JKKHakkoSODCC`, and `JKKAdchgCancelHakkoSODCC` have their own 3-parameter `mappingEKK0161A010SCInMsg` overloads (with an extra `funcCode` parameter), which may delegate to or mirror this 2-parameter version.
- The callers in `JKKSVUseFailAddCC` and `JKKSVUseFailChgCC` are commented out, indicating this method was previously used by screen-add and screen-change failure handlers but may have been deprecated or replaced for those paths.
- This method is the terminal point of the mapper chain — it does not call any further SC or DB methods.

## 6. Per-Branch Detail Blocks

**Block 1** — [EXEC] Null-mapping initialization (L169)

> Initializes all fields of the template to null values using the schema contents of `EKK0161A010CBSMsg`. This ensures no stale data from prior usage leaks into the request.

| # | Type | Code |
|---|------|------|
| 1 | EXEC | `fillCAANMSGNullMapping(template, new EKK0161A010CBSMsg().getContents())` // Null-map all fields of template using EKK0161A010CBSMsg schema contents |

---

**Block 2** — [SET] Set template ID (SIF ID) (L172)

> Sets the Service Integration Framework (SIF) template identifier on the message template. This ID identifies the service interface contract that the downstream `EKK0161A010SC` component will use to parse the message.

| # | Type | Code |
|---|------|------|
| 1 | SET | `template.set(EKK0161A010CBSMsg.TEMPLATEID, "EKK0161A010")` // Set templateID field to service interface ID "EKK0161A010" |

---

**Block 3** — [IF] Resolve function code (OM-2013-0002675) (L185-L191)

> Retrieves the function code from the input hash. If the caller did not supply a function code (null), defaults to `FUNC_CODE_ONE` (`"1"`), which represents the standard service subscription agreement cancellation path. The function code is then written into the template.

| # | Type | Code |
|---|------|------|
| 1 | SET | `funcCode = (String) inHash.get(EKK0161A010CBSMsg.FUNC_CODE)` // Get function code from input hash |
| 2 | IF | `funcCode == null` [L186] |
| 2.1 | SET | `funcCode = FUNC_CODE_ONE` // [-> FUNC_CODE_ONE = "1"] Default to function code 1 when not provided |
| 3 | SET | `template.set(EKK0161A010CBSMsg.FUNC_CODE, funcCode)` // Write resolved function code into template |

---

**Block 4** — [IF/ELSE] Function code dispatch: standard vs. alternative path (L193)

> Branches based on the resolved function code. If the function code equals `FUNC_CODE_ONE` (`"1"`), it is the standard subscription agreement cancellation path, and the service contract detail number and generation registration datetime are sourced from `EKK0161B004CBSMsg1List`. Otherwise, it is an alternative function path, and both values are sourced directly from `EKK0161A010CBSMsg`.

**Block 4.1** — [ELSE-IF] `FUNC_CODE_ONE.equals(funcCode)` — Standard path (L194)

> The standard service subscription agreement cancellation flow. Retrieves the service contract detail number (`SVC_KEI_UCWK_NO`) and the generation registration datetime (`GENE_ADD_DTM`) from the input hash, using keys defined in the `EKK0161B004CBSMsg1List` message list class. This indicates the data originates from a prior subscription registration context.

| # | Type | Code |
|---|------|------|
| 1 | SET | `template.set(EKK0161A010CBSMsg.KEY_SVC_KEI_UCWK_NO, inHash.get(EKK0161B004CBSMsg1List.SVC_KEI_UCWK_NO))` // Set K-Opticom service contract detail number from EKK0161B004CBSMsg1List |
| 2 | SET | `template.set(EKK0161A010CBSMsg.KEY_GENE_ADD_DTM, inHash.get(EKK0161B004CBSMsg1List.GENE_ADD_DTM))` // Set K-Opticom generation registration datetime from EKK0161B004CBSMsg1List |

---

**Block 4.2** — [ELSE] Alternative function code path (L197)

> When the function code is not `"1"`, the method takes an alternative data-sourcing path. Both the service contract detail number and the reservation application date are read directly from `EKK0161A010CBSMsg` keys in the input hash, rather than from the separate `EKK0161B004CBSMsg1List` class. This path uses the reservation application date (`KEY_RSV_APLY_YMD`) instead of the generation registration datetime, suggesting a different business context (possibly a reservation-based cancellation rather than a post-registration cancellation).

| # | Type | Code |
|---|------|------|
| 1 | SET | `template.set(EKK0161A010CBSMsg.KEY_SVC_KEI_UCWK_NO, inHash.get(EKK0161A010CBSMsg.KEY_SVC_KEI_UCWK_NO))` // Set K-Opticom service contract detail number from EKK0161A010CBSMsg |
| 2 | SET | `template.set(EKK0161A010CBSMsg.KEY_RSV_APLY_YMD, inHash.get(EKK0161A010CBSMsg.KEY_RSV_APLY_YMD))` // Set K-Opticom reservation application date from EKK0161A010CBSMsg |

---

## 7. Glossary

| Term | Type | Business Meaning |
|------|------|------------------|
| `template` | Field | CAANMsg template — the request message object built and populated by this method, passed downstream to the `EKK0161A010SC` service component for cancellation processing. |
| `inHash` | Field | Input context hash map — carries cancellation request parameters including function code, service contract number, and related fields. |
| `FUNC_CODE_ONE` | Constant | Function code `"1"` — represents the standard service subscription agreement cancellation path. Resolved from `JPCModelConstant.FUNC_CD_1`. |
| `TEMPLATEID` | Field | Service Interface ID — the message template identifier (`"EKK0161A010"`) that tells the receiving SC which message schema to use. |
| `FUNC_CODE` | Field | Function code — distinguishes between different cancellation business modes (standard vs. alternative). |
| `KEY_SVC_KEI_UCWK_NO` | Field | K-Opticom service contract detail number — an internal tracking ID for a specific line item within a service contract. Used to identify which subscription is being cancelled. |
| `KEY_GENE_ADD_DTM` | Field | K-Opticom generation registration datetime — the timestamp when the service subscription was originally registered/generated in the system. |
| `KEY_RSV_APLY_YMD` | Field | K-Opticom reservation application date — the date when a service reservation was applied, used in alternative cancellation flows instead of the generation registration datetime. |
| `EKK0161A010SC` | SC Code | Service Component code for Service Contract Cancellation execution. The downstream SC that processes the actual cancellation logic. |
| `EKK0161A010CBSMsg` | Message Class | CBS Message schema definition for the `EKK0161A010SC` request/response. Defines all field names and types (e.g., `func_code`, `key_svc_kei_ucwk_no`). |
| `EKK0161B004CBSMsg1List` | Message List Class | A separate message list class whose keys (`SVC_KEI_UCWK_NO`, `GENE_ADD_DTM`) are used in the standard (function code 1) cancellation path to source data from a prior subscription registration context. |
| `fillCAANMSGNullMapping` | Method | A utility method in `JKKUseFailMapperCC` that iterates over a schema definition and sets all corresponding fields in a `CAANMsg` to null, clearing any stale data. |
| `CAANMsg` | Class | K-Opticom's message container class (key-value based) used for SIF (Service Integration Framework) communication between CBS layers and SCs. |
| `CAANSchemaInfo` | Class | Base class for CBS message definitions that provides schema contents (field name/type pairs) and field key constants. |
| `AbstractCommonComponent` | Class | Base class extended by `JKKUseFailMapperCC`, providing shared component infrastructure for common components in the BP custom layer. |
| `JKKCancelSvcKeiCC` | CBS Class | Cancellation Service Contract CBS class — a primary caller of this method. Handles the cancellation service contract business logic flow. |
| `JKKHakkoSODCC` | CBS Class | Service Order Data (SOD) issuance CBS class — calls this mapper when generating/cancelling service orders. |
| `JKKAdchgHakkoSODCC` | CBS Class | Service Order Data (SOD) issuance change/adhesion CBS class — handles adhesion (new service attachment) and cancellation changes. |
| `JKKAdchgCancelHakkoSODCC` | CBS Class | Adhesion cancellation Service Order Data issuance CBS class — handles cancellation changes within the adhesion workflow. |
| `JKKUseFailMapperCC` | CC Class | Service Contract Cancellation Execution CC class — the custom mapper component class containing this method. Handles message mapping for cancellation operations. |
| `SIF` | Acronym | Service Integration Framework — Fujitsu's middleware integration framework used for communication between CBS layers and service components in the K-Opticom system. |
| `SC` | Acronym | Service Component — a granular business logic unit in the K-Opticom architecture that processes specific operations (e.g., cancellation, registration). |
| `CBS` | Acronym | Call Back System (also interpreted as Contract Back-Office System) — the core business logic layer in the K-Opticom architecture that handles service contract operations. |
| `SOD` | Acronym | Service Order Data — telecom order fulfillment entity representing a service order in the system. |
| `EKK` | Prefix | K-Opticom module/coding prefix convention used for service contract related CBS classes, messages, and service components. |
| `CAAN` | Acronym | K-Opticom message framework class prefix used for request/response message types in the integration layer. |
| `ANK-4245-00-00` | Change Request | Change request identifier from 2022/04/05 (plainsville) — the most recent modification to `JKKUseFailMapperCC`. |
| `OM-2013-0002675` | Change Request | Change request from 2013/09/30 (T.TORIKAI) — the modification that replaced the hardcoded `FUNC_CODE_ONE` and `EKK0161B004CBSMsg1List` references with the dynamic function code resolution branching. |