Skill: shoaibkhan/rsad-copilot (version 1.0.0)

--- name: ibm-rsad-copilot description: > Use this skill when working with IBM Rational Software Architect Designer (RSAD/RSA) in the context of IBM FTM (Financial Transaction Manager) development. Trigger when the user mentions: IBM RSA, IBM RSAD, Rational Software Architect, UML modeling in FTM, Service Participant design, Channel design, FSM modeling in RSA, state machine diagrams, UML sequence diagrams for payments, UML use case diagrams, class diagrams, RSA stereotypes, PMP_Alert, PMP_Terminal, PMP_OpsControl, FSM export to SQL, RSA config scripts, RSA workspace, RSA profiles, model-driven development for FTM, design artifacts for FTM, producing FTM design artifacts, RSA transformations, UML to SQL export, FTM design phase, modeling payment flows, designing FTM interfaces, or any RSA/RSAD design-time task in the FTM development workflow. Also trigger when the user is in the DESIGN step of the FTM methodology (Design → Build → Deploy → Operate). When in doubt, trigger this skill. license: MIT metadata: version: 1.0.0 tags: - ibm - rsad - rsa - rational-software-architect - uml - ftm - payments - modeling - fsm - design author: name: Shoaib Khan github: https://github.com/ShoaibKhan email: [REDACTED_SECRET] --- # IBM RSAD Copilot You are an expert IBM Rational Software Architect Designer (RSAD) practitioner specializing in IBM FTM (Financial Transaction Manager) development. You help teams produce design artifacts, model Service Participants and FSMs, create UML diagrams, and export configuration to DB2 — all within the FTM design methodology. > Note: IBM RSA and IBM RSAD refer to the same Eclipse-based modeling tool. "RSA" is the common > shorthand used in FTM documentation. ## Role of RSAD in FTM RSAD is the **design-time tool** in the FTM development lifecycle: ``` 1. DESIGN (RSAD) → Model SPs, Channels, FSMs, sequence diagrams → export SQL config scripts 2. BUILD (ACE) → Implement mapper flows + action subflows → package as BAR files 3. DEPLOY → Import config to DB2 + deploy BARs to integration node 4. OPERATE (OAC) → Monitor transaction states, resolve alerts, manage SP lifecycle ``` Every FTM interface begins in RSAD. The models you create here drive both the DB2 configuration and the ACE implementation. ## Core References - [UML Modeling](references/uml-modeling.md) — Diagram types, when to use each, FTM-specific content - [FTM Design Workflow](references/ftm-design-workflow.md) — Step-by-step interface design process, SP/Channel modeling - [FSM Design](references/fsm-design.md) — State machines: states, transitions, events, stereotypes, export - [Mapping Design](references/mapping-design.md) — Mapping strategies, metadata modeling, technology selection - [Patterns & Artifacts](references/patterns-artifacts.md) — All 15 FTM patterns with required RSAD artifacts ## Key Concepts | Concept | Description | |---|---| | **Service Participant (SP)** | Represents an external system or internal FTM service; has channels, FSMs, and configuration | | **Channel** | Communication path on an SP; carries a specific message format and transport | | **FSM (Finite State Machine)** | Defines transaction/transmission lifecycle; modeled as UML state machine in RSAD | | **ISF** | Internal Standard Format — IBM's ISO 20022-based canonical XML (`http://www.ibm.com/xmlns/prod/ftm/isf/v3`) | | **UML Profile** | RSAD's mechanism for adding FTM-specific stereotypes (PMP_Alert, PMP_Terminal, etc.) to UML elements | | **SQL Export** | RSAD generates DB2 INSERT scripts from models; these are the deployment config artifacts | | **Transformation** | RSAD feature that generates code/config from UML models (model-to-text or model-to-model) | ## Standard Design Artifacts Every FTM interface requires these 7 artifacts produced in RSAD: | # | Artifact | Diagram Type | Purpose | |---|---|---|---| | 1 | Functional Use Case | Use Case | Shows actors, the new interface, and related SPs | | 2 | Functional Sequence | Sequence | End-to-end message flow across systems | | 3 | Object Lifecycle | State Machine | FSM for transaction or transmission object | | 4 | SP/Channel Config | Class / RSA Model | Defines SP attributes, channels, mapper references | | 5 | Service Interaction | Sequence | Detailed technical flow within FTM components | | 6 | Deployment Topology | Deployment | Integration node, servers, MQ queues, external systems | | 7 | SQL Config Scripts | (Export) | DB2 INSERT statements generated from the RSAD model | ## FTM UML Profiles and Stereotypes RSAD uses stereotypes to annotate FTM-specific semantics on UML states: | Stereotype | Applies To | Meaning | |---|---|---| | `PMP_Alert` | State | Operator-visible alert in OAC; requires `Constraints` tag | | `PMP_Terminal` | State | Final lifecycle state (e.g., Completed, Cancelled) | | `PMP_OpsControl` | State | Requires operator interaction; not an alert | **PMP_Alert Constraints** (tagged values): `Cancel`, `Resubmit`, `Release`, `Continue` Always apply `PMP_Alert` on every failure path. Every alert state must have at least one Constraint. ## Quick Design Checklist When designing a new FTM interface in RSAD: - [ ] Identify the FTM pattern (9.1–9.15) for this interface - [ ] Draw functional use case diagram (actors + new SP + related SPs) - [ ] Draw functional sequence diagram (inbound PT flow → EP flow → action → outbound) - [ ] Model the SP with channels, mapper references, and transport config - [ ] Model the FSM(s): states, transitions, events, actions - [ ] Every path has a terminal state - [ ] Every path has a `PMP_Alert` state with Constraints - [ ] Heartbeat transitions use Object Filter on `timeout` - [ ] Select mapping technology (ESQL / Java / XSLT / WTX) - [ ] Export SQL config scripts from RSAD model - [ ] Validate exported SQL against DB2 schema ## Typical Workflow (JIRA → RSAD → ACE → PR) When a JIRA ticket requires a new or modified FTM interface: 1. Read JIRA ticket and Confluence description to understand the change 2. Open RSAD workspace and locate the relevant SP/Channel model 3. Modify or create the required UML diagrams (use case, sequence, FSM) 4. Apply correct stereotypes and tagged values to FSM states 5. Export updated SQL config scripts from the model 6. Hand off to ACE implementation: implement mapper flows and action subflows 7. Commit design artifacts and SQL scripts; open Bitbucket PR for human review

path: references/uml-modeling.md
content: # UML Modeling in RSAD

RSAD supports the full UML 2.x specification via an Eclipse-based graphical editor. In FTM
development, specific diagram types are used for specific design purposes.

---

## Diagram Types Used in FTM

### Use Case Diagram
**FTM Purpose:** High-level functional view of a new interface — who sends/receives, what FTM
facilitates, which existing SPs are involved.

Key elements:
- **Actors**: External systems, internal FTM services, operators
- **Use Cases**: Interface capabilities (e.g., "Process Inbound Payment", "Send Acknowledgement")
- **Include/Extend relationships**: Shared sub-use cases (e.g., error handling, logging)
- **System boundary**: Draw FTM as the boundary enclosing all use cases

Typical FTM use case diagram contains:
- Sending bank actor → "Submit Payment" use case
- FTM system boundary with: Receive Payment, Validate, Route, Send Confirmation
- Receiving bank actor ← "Deliver Payment" use case
- Operator actor ← "Resolve Alert" use case

---

### Sequence Diagram
**FTM Purpose:** Shows the message flow and interactions between FTM components and external
systems in time order. Two types are used:

**Functional Sequence Diagram** (high-level):
- Lifelines: External System, PT Flow, MQ Event Queue, EP Flow, Action Subflow, External System
- Shows: message arrival → PT flow processing → ISF creation → event raising → EP processing →
  FSM action → outbound message
- Captures the happy path and key error paths

**Service Interaction Diagram** (technical detail):
- Lifelines: ACE integration server components, DB2, MQ queues
- Shows: DB2 reads/writes, MQ put/get operations, mapper invocations
- Used to validate implementation against design

Standard sequence for inbound payment (Pattern 9.1):
```
ExternalSystem → PTFlow: Raw message (MQ/HTTP)
PTFlow → Mapper: Map to ISF
Mapper → PTFlow: ISF document
PTFlow → DB2: INSERT Transmission + Transaction rows
PTFlow → MQEventQueue: PUT E_MpInMappingComplete event
MQEventQueue → EPFlow: GET event
EPFlow → DB2: SELECT FSM transitions
EPFlow → ActionSubflow: Execute action
ActionSubflow → DB2: UPDATE object state
ActionSubflow → OutboundMQ: PUT outbound message
```

---

### State Machine Diagram (FSM)
**FTM Purpose:** This is the most critical RSAD artifact in FTM. It defines the lifecycle of a
Transaction or Transmission object. RSAD exports this directly to DB2 SQL.

See `fsm-design.md` for full details on states, transitions, events, and stereotypes.

---

### Class Diagram
**FTM Purpose:** Models the Service Participant configuration — attributes, channels, mapper
references, and relationships between SPs.

Key elements for FTM:
- **SP Class**: One class per Service Participant; attributes include SP name, type, role
- **Channel Class**: One per channel; attributes include format, transport, mapper class, queue names
- **Relationships**: SP has-many Channels; Channel references Mapper
- **Tagged values**: Transport endpoint (queue name, URL), format identifier, mapper reference

SP class attributes:
```
ServiceParticipant
  - name: String         // DB2 SERVICE_PARTICIPANT_BASE.SP_NAME
  - type: String         // e.g., BANK, INTERNAL
  - role: String         // e.g., DEBTOR_AGENT, CREDITOR_AGENT
  - status: String       // ACTIVE / INACTIVE
```

Channel attributes:
```
Channel
  - channelName: String
  - format: String       // e.g., SWIFT_MT103, ISO20022_PACS008
  - mapper: String       // ACE subflow name
  - inputQueue: String   // MQ queue name
  - outputQueue: String
  - transport: String    // MQ / HTTP / FILE
```

---

### Activity Diagram
**FTM Purpose:** Models the internal logic of a mapper or action subflow — decision points,
parallel paths, loops. Used when the logic is too complex to capture in a sequence diagram.

Elements:
- Initial/final nodes, actions, decisions, forks/joins, swim lanes
- Swim lanes map to: ESQL module, Java class, external service call

---

### Component Diagram
**FTM Purpose:** Shows the ACE application/library structure and dependencies. Maps RSAD design
to actual ACE project structure.

Typical FTM component diagram:
- FTM_PT_Application → depends on → FTM_Library (shared subflows)
- FTM_EP_Application → depends on → FTM_Actions_Library
- Mapper_Application → depends on → ISF_Schema_Library

---

### Deployment Diagram
**FTM Purpose:** Shows where ACE integration nodes, integration servers, MQ queue managers, DB2,
and WAS run — and how they connect.

Elements for FTM:
- Integration Node (ACE broker)
- Integration Servers (execution groups): PT_Server, EP_Server, Action_Server
- MQ Queue Manager with queue names
- DB2 instance
- WAS node (hosting OAC)
- External system endpoints (banks, clearinghouses)

---

## UML Profile Application

RSAD profiles extend UML with domain-specific stereotypes. In FTM, always apply the FTM UML
Profile before modeling FSMs.

To apply a profile in RSAD:
1. Right-click the UML model → Properties → Profiles
2. Add the FTM profile (available in the RSAD FTM plugin)
3. Stereotypes become available in the state machine diagram palette

---

## RSAD Workspace Organization

```
RSA Workspace/
├── FTM_Design/                  # Master design project
│   ├── UseCases/                # Use case diagrams per interface
│   ├── SequenceDiagrams/        # Functional + technical sequences
│   ├── FSMs/                    # State machine models
│   │   ├── Transaction_FSMs/
│   │   └── Transmission_FSMs/
│   ├── ServiceParticipants/     # SP + Channel class models
│   └── Deployment/              # Deployment topology diagrams
├── FTM_Config/                  # Generated SQL export directory
│   ├── sp_config.sql
│   ├── channel_config.sql
│   ├── fsm_config.sql
│   └── event_type_config.sql
└── FTM_Profiles/                # FTM UML profile definitions
```

---

## Common RSAD Operations

### Creating a new State Machine
1. New → UML Model → State Machine Diagram
2. Apply FTM UML Profile to the model
3. Add Initial pseudostate
4. Add states; apply `PMP_Alert` / `PMP_Terminal` stereotypes as needed
5. Add transitions; set Event, Guard (Object Filter), and Effect (FSM Action = ACE subflow name)
6. Add Final state for each terminal path
7. Right-click model → Transform → Export to SQL

### Exporting SQL from RSAD
1. Select the SP/Channel/FSM model(s) to export
2. Right-click → IBM FTM → Export Configuration
3. Choose output directory (FTM_Config/)
4. Review generated SQL before loading to DB2:
   - `INSERT INTO FSM` — FSM root record
   - `INSERT INTO FSM_STATE_REL` — state records
   - `INSERT INTO FSM_TRANSITION` — transition rules
   - `INSERT INTO SERVICE_PARTICIPANT_BASE` — SP records
   - `INSERT INTO CHANNEL_BASE` — channel records

### Editing an existing model
1. Open the model in RSAD (`.emx` or `.uml` file)
2. Navigate to the specific diagram
3. Make changes — add states, modify transition events, update channel attributes
4. Re-export SQL (generates new INSERT scripts; apply delta to DB2)
5. Commit `.emx` / `.uml` files and updated SQL to version control


path: references/patterns-artifacts.md
content: # FTM Patterns and RSAD Artifacts

Each of the 15 FTM patterns requires a specific set of RSAD design artifacts. This reference maps
every pattern to the diagrams, FSMs, and configuration it needs.

---

## Pattern Selection Guide

| # | Pattern | Trigger |
|---|---|---|
| 9.1 | Outbound Message/File | Send a message/file to an external system |
| 9.2 | Routing + ODM | Dynamic routing; message goes to one of N targets |
| 9.3 | Inbound Acknowledgement | Correlate response/ACK/NACK to a prior request |
| 9.4 | Store and Release | Hold transactions until a gateway opens (cut-off window) |
| 9.5 | Transformation/Mapping | Convert format between external systems |
| 9.6 | Debulking | Split inbound batch into individual transactions |
| 9.7 | Bulking | Aggregate multiple transactions into an outbound batch |
| 9.8 | Scheduler-driven Store/Release | Release held transactions at a scheduled cut-off time |
| 9.9 | External Services | Invoke an external service (sync or async) from FTM |
| 9.10 | Hosting Services | FTM exposes a service for external systems to call |
| 9.11 | Collating Information | Wait for N related messages before processing |
| 9.12 | Scheduled Activity | Trigger an activity at a configured schedule |
| 9.13 | Scheduled Expectation | Raise an alert if an expected event doesn't arrive in time |
| 9.14 | Heartbeat Monitoring | Send/receive periodic pings to check SP availability |
| 9.15 | Error Handling + Alerts | Operator-facing notification and resolution flow |

---

## Required RSAD Artifacts per Pattern

Every FTM interface produces these 7 standard artifacts. The table below shows what each
contains, specialized per pattern.

### Pattern 9.1 — Outbound Message/File

| Artifact | Content |
|---|---|
| Use Case Diagram | Actors: Originating System, FTM, Target SP. Use cases: Submit Payment, Deliver Payment, Handle Delivery Failure |
| Functional Sequence | PT → Mapper → DB2 INSERT Txn/Trans → E_MpInMappingComplete → EP → ActRoute → E_TxnOutCreated → ACE Outbound |
| Object Lifecycle (FSM) | INITIAL → (E_MpInMappingComplete) → VALIDATED → (E_TxnOutCreated) → SENT → COMPLETED |
| Alert States | MAPPING_ERROR_ALERT (Cancel, Resubmit), SEND_FAILED_ALERT (Cancel, Resubmit) |
| SP/Channel Config | Outbound channel; output queue; mapper reference |
| SQL Export | FSM + transitions + SP + Channel |

---

### Pattern 9.2 — Routing + ODM

Additional RSAD elements:
- Sequence diagram must show ODM service invocation (ActRouteViaODM action)
- FSM adds ROUTING state between VALIDATED and SENT
- Activity diagram recommended for routing logic (ODM ruleset name + parameters)
- SP config includes `ODM_RULESET_NAME` channel attribute

```
INITIAL → VALIDATED → ROUTING → SENT → COMPLETED
ROUTING → ROUTING_FAILED_ALERT (Cancel, Resubmit)
```

---

### Pattern 9.3 — Inbound Acknowledgement

Additional RSAD elements:
- Separate Transmission FSM for inbound ACK
- Transaction FSM adds WAITING_FOR_ACK state after SENT
- Correlation key documented in sequence diagram (how ACK is linked to original request)
- Events: `E_CorrelationSuccessful`, `E_CorrelationFailure`

```
Transaction FSM:
  SENT → (E_CorrelationSuccessful) → ACKNOWLEDGED → COMPLETED
  SENT → (E_CorrelationFailure) → CORRELATION_FAILED_ALERT (Cancel, Resubmit)
  SENT → (E_Heartbeat [timeout < NOW()]) → TIMEOUT_ALERT (Cancel, Continue)

Transmission FSM (ACK):
  RECEIVED → (E_MpInMappingComplete) → CORRELATED → COMPLETED
```

---

### Pattern 9.4 — Store and Release

Additional RSAD elements:
- Transaction FSM has HELD state (gateway closed)
- Release trigger modeled in sequence diagram (manual operator release or scheduled)
- PMP_OpsControl stereotype on HELD state (operator can release)
- Channel config: `STORE_AND_RELEASE=Y`, gateway schedule reference

```
INITIAL → VALIDATED → HELD «PMP_OpsControl»
HELD → (Release / ActSendToSP) → SENT → COMPLETED
HELD → (Cancel / ActCancel) → CANCELLED «PMP_Terminal»
```

---

### Pattern 9.5 — Transformation/Mapping

Additional RSAD elements:
- Mapping design artifacts are central (see `mapping-design.md`)
- Two channels: inbound channel (format A) + outbound channel (format B)
- Two mappers: MapIn<FormatA> + MapOut<FormatB>
- Sequence diagram shows double-transform: raw → ISF → raw-output

---

### Pattern 9.6 — Debulking

Additional RSAD elements:
- Batch object lifecycle (Transmission FSM for batch)
- Transaction FSM for each debulked child transaction
- Sequence diagram shows: PT Flow inserts 1 Transmission + N Transactions; raises N events
- Batch FSM: RECEIVED → (all children complete) → COMPLETED
- Child count tracking in class diagram

```
Batch Transmission FSM:
  RECEIVED → PROCESSING → (E_AllChildrenComplete) → COMPLETED
  PROCESSING → (E_Heartbeat [timeout]) → BATCH_TIMEOUT_ALERT (Cancel, Continue)

Child Transaction FSM: standard outbound pattern (9.1)
```

---

### Pattern 9.7 — Bulking

Additional RSAD elements:
- Batch object lifecycle (outbound batch)
- Sequence diagram: N individual transactions → ACT_Bulk action → 1 outbound batch
- Batch FSM: transitions driven by trigger (count/timer/manual)
- `OBJ_OBJ_REL` relationship modeled in class diagram (transactions belong to batch)

```
Batch Transmission FSM:
  OPEN → (E_ActivityEvent [count >= threshold]) → CLOSING → SENT → COMPLETED
  OPEN → (E_Heartbeat [cutoff time]) → CLOSING → ...
```

---

### Pattern 9.8 — Scheduler-driven Store/Release

Additional RSAD elements:
- Scheduler Task object lifecycle (FSM for SchedulerTask)
- Transaction FSM has HELD state (as in 9.4)
- Sequence diagram shows: Scheduler fires E_ActivityEvent → ActReleaseBatch → releases held transactions
- Scheduler config: cron expression or fixed interval in `SCHEDULER_TASK_BASE`

---

### Pattern 9.9 — External Services

Additional RSAD elements:
- Sequence diagram shows synchronous or async service call
  - Sync: ActCallService → service response → continue in same action
  - Async: ActCallService → WAITING_FOR_RESPONSE state → E_ServiceResponse → continue
- Component diagram shows external service endpoint (SOAP/REST)
- Channel config: `SERVICE_URL`, `TIMEOUT_SECONDS` attributes

---

### Pattern 9.10 — Hosting Services

Additional RSAD elements:
- FTM exposes a service endpoint (modeled as actor/component in use case diagram)
- Sequence diagram: External caller → FTM (HTTP/MQ input) → processing → synchronous response
- No outbound SP needed — response goes back to caller on same connection
- Channel config: `INPUT_QUEUE` or `HTTP_ENDPOINT`

---

### Pattern 9.11 — Collating Information

Additional RSAD elements:
- Collation object lifecycle (special FSM tracking N expected messages)
- Event: `E_ChildTxnArrived` raised when each component arrives
- Object Filter on transition: `CHILD_COUNT >= EXPECTED_COUNT`
- Sequence diagram: N inbound → FTM holds each → ActCollate when all arrived → single ISF

```
Collation Transaction FSM:
  COLLECTING → (E_ChildTxnArrived [childCount >= expected] / ActProcess) → PROCESSING
  COLLECTING → (E_Heartbeat [timeout] / ActAlert) → TIMEOUT_ALERT (Cancel, Continue)
```

---

### Pattern 9.12 — Scheduled Activity

Additional RSAD elements:
- Scheduler Task FSM (SCHEDULED → RUNNING → COMPLETED)
- Sequence diagram: E_ActivityEvent → ActPerformScheduledWork → result
- Scheduler config in class diagram: interval/cron expression, target action

---

### Pattern 9.13 — Scheduled Expectation

Additional RSAD elements:
- Expectation deadline modeled as `timeout` on the waiting state
- Heartbeat transition: `E_Heartbeat [timeout < NOW()] → EXPECTATION_FAILED_ALERT`
- Sequence diagram shows both paths: expectation met (happy) and deadline missed (alert)

```
WAITING_FOR_MESSAGE → (E_MessageArrived) → PROCESSING → COMPLETED
WAITING_FOR_MESSAGE → (E_Heartbeat [timeout < NOW()]) → DEADLINE_MISSED_ALERT (Cancel, Continue)
```

---

### Pattern 9.14 — Heartbeat Monitoring

Additional RSAD elements:
- Dedicated Heartbeat Transaction FSM
- Sequence diagram: FTM sends ping → waits → receives pong OR timeout alert
- Events: `E_HeartbeatStart`, `E_Heartbeat`
- SP config: heartbeat interval, expected response queue

---

### Pattern 9.15 — Error Handling + Alerts

This pattern is present in ALL interfaces (not standalone). Every interface in RSAD must include:
- `PMP_Alert` states on every error path
- Constraints tagged values: at minimum `Cancel`; add `Resubmit` if retry is safe
- OAC will surface these alerts to operators
- Sequence diagram includes alert resolution flows (Cancel path, Resubmit path)

When designing standalone error/retry infrastructure:
- Model a dedicated Alert Monitor FSM with escalation states
- Include timeout escalation: `E_Heartbeat [unresolved > N hours] → ESCALATED_ALERT`

---

## Standard RSAD Design Package (per interface)

Commit to version control in the design repository:

```
design/<InterfaceName>/
├── diagrams/
│   ├── use-case.emx              # Use case diagram
│   ├── sequence-functional.emx   # Functional sequence
│   ├── sequence-technical.emx    # Technical service interaction
│   ├── fsm-transaction.emx       # Transaction FSM
│   ├── fsm-transmission.emx      # Transmission FSM (if applicable)
│   └── deployment.emx            # Deployment topology
├── config/
│   ├── sp_config.sql             # SERVICE_PARTICIPANT_BASE inserts
│   ├── channel_config.sql        # CHANNEL_BASE inserts
│   ├── fsm_config.sql            # FSM + FSM_STATE_REL + FSM_TRANSITION inserts
│   ├── event_type_config.sql     # EVENT_TYPE inserts
│   └── value_config.sql          # VALUE table inserts (SUBTYPE registration)
└── mapping/
    └── field-mapping-<format>.md  # Field-level mapping table
```


path: references/fsm-design.md
content: # FSM Design in RSAD

The Finite State Machine (FSM) is the heart of FTM. Every transaction and transmission in FTM
has a lifecycle defined by an FSM. RSAD is where you model these FSMs, apply stereotypes, and
export them to SQL. This reference covers everything needed to design correct FTM FSMs.

---

## FSM Fundamentals

An FSM in FTM defines: given an object in STATE X, when EVENT Y arrives, execute ACTION Z and
transition to STATE W.

FTM selects the right FSM at runtime using:
- **Object type**: TRANSACTION / TRANSMISSION / BATCH
- **SUBTYPE**: Unique identifier for this interface (e.g., `SWIFT_OUTBOUND_TXN`)
- **OBJECT_SELECTION_TEMPLATE**: SQL WHERE predicate for dynamic selection

The FSM runs inside the Event Processing (EP) flow on ACE. When an event arrives on the MQ
event queue, EP reads the object's current state, queries `FSM_TRANSITION`, selects the matching
transition, and invokes the named ACE action subflow.

---

## DB2 FSM Tables

| Table | Purpose |
|---|---|
| `FSM` | Root: FSM name, object type, subtype, selection template |
| `FSM_STATE_REL` | All states belonging to an FSM |
| `FSM_TRANSITION` | Transition rules: (FSM, FromState, Event) → (Action, ToState) |
| `EVENT_TYPE` | Named events with logging/processing configuration |
| `OBJ_BASE` | Runtime: object's current `STATE`, `SUBTYPE`, `LAST_UPDATED_TS` |

---

## States

### State Types
- **Normal state**: Standard processing state (e.g., `INITIAL`, `VALIDATED`, `SENT`)
- **Alert state** (`PMP_Alert`): Object needs operator intervention; visible in OAC
- **Terminal state** (`PMP_Terminal`): Lifecycle ends here; no further transitions
- **OpsControl state** (`PMP_OpsControl`): Requires operator action; not surfaced as alert

### Naming Conventions
- Use ALL_CAPS with underscores: `WAITING_FOR_ACK`, `SEND_FAILED`
- Terminal states: `COMPLETED`, `CANCELLED`, `REJECTED`
- Alert states: `SEND_FAILED_ALERT`, `MAPPING_ERROR_ALERT`, `TIMEOUT_ALERT`

### Applying Stereotypes in RSAD
1. Draw state in the state machine diagram
2. Right-click state → Add Stereotype
3. Select `PMP_Alert`, `PMP_Terminal`, or `PMP_OpsControl`
4. For `PMP_Alert`: right-click state → Add Tagged Value → `Constraints`
   - Value is comma-separated list: `Cancel,Resubmit,Release`

---

## Transitions

Each transition has:
- **From State**: the current object state
- **Event Type**: the event that triggers this transition
- **Guard (Object Filter)**: optional SQL WHERE predicate on object data
- **Guard (Event Filter)**: optional ESQL boolean condition on event context
- **Action**: ACE subflow name to invoke (or blank for no-op transitions)
- **To State**: state to move the object to after action completes
- **Priority**: integer; lower = higher priority (used when multiple transitions match)

### Transition in RSAD
1. Draw arrow from source state to target state
2. Label arrow: `EventTypeName [Guard] / ActionSubflowName`
3. In transition properties:
   - Event: select from EVENT_TYPE list
   - Guard/Constraint: enter SQL or ESQL expression
   - Effect: enter ACE subflow name

### Transition Guards
```sql
-- Object Filter (SQL): restrict by object data
SUBTYPE = 'SWIFT_OUTBOUND_TXN' AND AMOUNT > 1000000

-- Event Filter (ESQL): inspect event context variables
$ContextNULL{BATCH}           -- true if event has no BATCH context
$Context{SP_NAME} = 'SWIFT'  -- true if event SP_NAME = SWIFT
```

---

## Events

### Standard Events (use these wherever possible)

| Event | Raised By | Meaning |
|---|---|---|
| `E_MpInMappingComplete` | PT Flow | Inbound mapping succeeded |
| `E_MpInMappingAborted` | PT Flow | Inbound mapping failed |
| `E_TransOutSent` | Action Subflow | Outbound transmission was sent |
| `E_TxnOutCreated` | Action Subflow | Outbound transaction created |
| `E_CorrelationSuccessful` | EP Flow | Response correlated to prior request |
| `E_CorrelationFailure` | EP Flow | Correlation failed |
| `E_Heartbeat` | ACE Timer (~60s) | Periodic tick for timeout checking |
| `E_HeartbeatStart` | ACE Startup | Broker startup event |
| `E_ActivityEvent` | Scheduler | Scheduled activity triggered |
| `E_ChildTxnArrived` | Action Subflow | Child transaction arrived (collating) |

### Custom Events
For interface-specific needs, define custom events in `EVENT_TYPE`:
- Name: `E_<Interface>_<Meaning>` (e.g., `E_SWIFT_AckReceived`)
- `EVENT_LOGGING`: Y / N — whether to log event instances
- `RENDER_AS_MESSAGE`: Y (async via MQ queue) / N (inline synchronous)
- `AGGREGATE_THRESHOLD`: max events to aggregate before processing

---

## Generic (Pre-built) FSMs

Always check if a generic FSM covers your use case before designing a custom one.
Generic FSMs are pre-built in FTM and just need SUBTYPE registration.

| Generic FSM | Use For |
|---|---|
| Generic Inbound Transmission FSM | Simple inbound: receive → map → complete |
| Generic Outbound Transmission FSM | Simple outbound: create → send → complete |
| Generic Outbound Transaction FSM | Standard outbound transaction lifecycle |
| Generic Inbound Acknowledgement Transaction FSM | Correlated ACK/NACK processing |

To use a generic FSM:
1. Do not model a custom FSM in RSAD
2. Register the new SUBTYPE in `VALUE` table pointing to the generic FSM
3. Configure `OBJECT_SELECTION_TEMPLATE` in `FSM` table to select objects of this SUBTYPE

---

## FSM Design Patterns by Object Type

### Transaction FSM (most common)
```
[Initial] →(E_MpInMappingComplete / ActValidate)→ [Validated]
[Validated] →(E_TxnOutCreated / ActSendToSP)→ [Sent]
[Sent] →(E_CorrelationSuccessful / ActComplete)→ [Completed] «PMP_Terminal»
[Sent] →(E_CorrelationFailure / ActRaiseAlert)→ [SendFailed_Alert] «PMP_Alert» Constraints: Cancel,Resubmit
[SendFailed_Alert] →(Cancel / ActCancel)→ [Cancelled] «PMP_Terminal»
[SendFailed_Alert] →(Resubmit / ActSendToSP)→ [Sent]
[Initial] →(E_MpInMappingAborted / ActRaiseAlert)→ [MappingError_Alert] «PMP_Alert» Constraints: Cancel,Resubmit
[MappingError_Alert] →(Cancel / ActCancel)→ [Cancelled] «PMP_Terminal»
```

### Transmission FSM (inbound)
```
[Received] →(E_MpInMappingComplete)→ [Processed] «PMP_Terminal»
[Received] →(E_MpInMappingAborted / ActRaiseAlert)→ [MapError_Alert] «PMP_Alert» Constraints: Cancel,Resubmit
[MapError_Alert] →(Cancel)→ [Cancelled] «PMP_Terminal»
[MapError_Alert] →(Resubmit / ActRetryMapper)→ [Received]
```

### Heartbeat/Timeout pattern
```
[Sent] →(E_Heartbeat [timeout < NOW()] / ActTimeout)→ [Timeout_Alert] «PMP_Alert» Constraints: Cancel,Continue
```
Object Filter on Heartbeat transition: `TIMEOUT < CURRENT TIMESTAMP`

---

## FSM Design Checklist

Before exporting from RSAD:

- [ ] FSM name is unique and follows convention: `<ObjectType>FSM_<Interface>`
- [ ] SUBTYPE is unique; registered in `VALUE` table
- [ ] OBJECT_SELECTION_TEMPLATE is correct SQL (test against DB2)
- [ ] Every processing state has at least one outgoing transition
- [ ] Every path terminates at a `PMP_Terminal` state
- [ ] Every error path has a `PMP_Alert` state
- [ ] Every `PMP_Alert` state has Constraints tagged value (Cancel/Resubmit/Release)
- [ ] Heartbeat transitions use Object Filter on `timeout` field
- [ ] Generic FSMs used where applicable (no redundant custom modeling)
- [ ] Action names match ACE subflow naming convention: `Act<PascalCase>`
- [ ] Transition priorities set correctly (no ambiguous transitions at same priority)
- [ ] Custom events defined in EVENT_TYPE with correct RENDER_AS_MESSAGE setting

---

## Exported SQL Example

```sql
-- FSM root
INSERT INTO FSM (FSM_NAME, OBJECT_TYPE, OBJECT_CLASS, SUBTYPE, OBJECT_SELECTION_TEMPLATE, DESCRIPTION)
VALUES ('TxnFSM_SWIFT_OUT', 'TRANSACTION', 'PAYMENT', 'SWIFT_OUTBOUND_TXN',
        'SUBTYPE = ''SWIFT_OUTBOUND_TXN''', 'SWIFT MT103 Outbound Transaction FSM');

-- States
INSERT INTO FSM_STATE_REL (FSM_NAME, STATE_NAME, STATE_TYPE, DESCRIPTION)
VALUES ('TxnFSM_SWIFT_OUT', 'INITIAL', 'NORMAL', 'Transaction received, awaiting validation');

INSERT INTO FSM_STATE_REL (FSM_NAME, STATE_NAME, STATE_TYPE, DESCRIPTION)
VALUES ('TxnFSM_SWIFT_OUT', 'COMPLETED', 'TERMINAL', 'Transaction successfully processed');

INSERT INTO FSM_STATE_REL (FSM_NAME, STATE_NAME, STATE_TYPE, STEREOTYPE, CONSTRAINTS, DESCRIPTION)
VALUES ('TxnFSM_SWIFT_OUT', 'SEND_FAILED_ALERT', 'ALERT', 'PMP_Alert', 'Cancel,Resubmit',
        'Outbound send failed — operator action required');

-- Transitions
INSERT INTO FSM_TRANSITION (FSM_NAME, FROM_STATE, EVENT_TYPE, ACTION_SUBFLOW, TO_STATE,
                            TRANSITION_PRIORITY, OBJECT_FILTER, EVENT_FILTER)
VALUES ('TxnFSM_SWIFT_OUT', 'INITIAL', 'E_MpInMappingComplete', 'ActValidateAndRoute',
        'VALIDATED', 1, NULL, NULL);

INSERT INTO FSM_TRANSITION (FSM_NAME, FROM_STATE, EVENT_TYPE, ACTION_SUBFLOW, TO_STATE,
                            TRANSITION_PRIORITY, OBJECT_FILTER, EVENT_FILTER)
VALUES ('TxnFSM_SWIFT_OUT', 'INITIAL', 'E_MpInMappingAborted', 'ActRaiseMappingAlert',
        'MAPPING_ERROR_ALERT', 1, NULL, NULL);
```


path: references/mapping-design.md
content: # Mapping Design in RSAD

Mapping is the conversion between external message formats and ISF (Internal Standard Format).
The mapping technology decision is made during RSAD design and documented before ACE implementation.

---

## ISF Overview

ISF (Internal Standard Format) is FTM's canonical XML format. All messages inside FTM are in ISF.

- **Namespace**: `http://www.ibm.com/xmlns/prod/ftm/isf/v3`
- **Schema**: `ISF_V3.xsd` — part of the FTM toolkit, included in ACE library projects
- **Root element**: `ISFDocument`
- **Key child elements**:
  - `Header` — message metadata (type, version, correlation IDs)
  - `Body` — payment content (CreditTransfer, DirectDebit, etc.)
  - `Party` — debtor, creditor, agents
  - `Amount` — instructed amount with currency attribute
  - `RemittanceInformation` — optional remittance data

ISF is stored in DB2 `TRANSACTION_BASE.ISF_BLOB` column as a CLOB.

---

## Mapping Strategies

### Pass-Through (no mapping)
- Used when the external format IS ISF, or when no field transformation is needed
- PT Flow passes message through without invoking a mapper
- Rare in practice — most external systems use native formats (SWIFT MT, ISO 20022, etc.)

### Shallow Mapping
- 1:1 field mapping from external format to ISF fields
- No structural transformation; just field renaming/reordering
- Implemented easily in ESQL
- Example: map SWIFT MT103 field 32A (value date + currency + amount) → ISF InstructedAmount

### Deep Mapping
- Structural transformation required (1:N, N:1, conditional logic, loops)
- Typical for batch debulking, format normalization, multi-part messages
- May require Java or WTX for complex cases
- Example: ISO 20022 pain.001 (multi-transaction batch) → multiple ISF CreditTransfer elements

---

## Mapping Technology Selection

| Technology | Strengths | Use When |
|---|---|---|
| **ESQL** | Native ACE language; fast; full ISF/MQ tree access; easy to debug | Default choice for most FTM mappers |
| **Java** | OO design; external library use; recursion; unit testable | Complex business logic; non-XML parsing; external API calls |
| **XSLT** | Declarative; stylesheet-based; no ACE-specific knowledge needed | Pure XML-to-XML structural transforms |
| **WTX/ITX** | IBM Transform Extender; handles EDI, positional, binary formats; batch | Legacy EDI (SWIFT FIN, ACH NACHA), binary/positional formats, very large transforms |

**Decision guide:**
1. Is the source format XML? → Consider ESQL or XSLT
2. Is it flat/positional/binary? → WTX/ITX
3. Simple field mapping? → ESQL
4. Need external library or complex OO logic? → Java
5. Team skill set? → Default to ESQL unless there's a reason not to

---

## Metadata Modeling

FTM's ISF uses `xsd:any` elements in certain places to allow custom metadata. This must be
modeled in RSAD before implementation so the ACE developer knows what fields to set.

### xsd:any Pattern in ISF
```xml
<ISFDocument xmlns="http://www.ibm.com/xmlns/prod/ftm/isf/v3">
  <Header>
    <MessageType>CreditTransfer</MessageType>
    <CorrelationId>TXN-001</CorrelationId>
  </Header>
  <Body>
    <CreditTransfer>
      <InstructedAmount Currency="USD">1000.00</InstructedAmount>
      <Debtor>...</Debtor>
      <Creditor>...</Creditor>
      <!-- xsd:any extension point for channel-specific metadata -->
      <ChannelSpecific>
        <BankReference>REF123</BankReference>
      </ChannelSpecific>
    </CreditTransfer>
  </Body>
</ISFDocument>
```

In RSAD class diagrams, model the `xsd:any` content as a class with attributes, then reference
it from the ISF extension point in the sequence diagram.

---

## ESQL Mapping Patterns

When ESQL is selected, the ACE developer will implement the mapper subflow. The RSAD design
should document which fields map where.

### Standard ESQL mapper structure
```esql
-- Output ISF location (always this path for inbound mapper)
DECLARE ISF_NS NAMESPACE 'http://www.ibm.com/xmlns/prod/ftm/isf/v3';
DECLARE rISF REFERENCE TO OutputLocalEnvironment.PMP.ISF.XMLNSC.{ISF_NS}ISFDocument;

-- Set currency as XML attribute
SET rISF.{ISF_NS}Body.{ISF_NS}CreditTransfer.{ISF_NS}InstructedAmount
    .(XMLNSC.Attribute)Currency = InputRoot.XMLNSC.MT103.Field32A.Currency;

-- Set xsi:type for polymorphic party role
DECLARE XSI_NS NAMESPACE 'http://www.w3.org/2001/XMLSchema-instance';
SET rISF.{ISF_NS}Body.{ISF_NS}CreditTransfer.{ISF_NS}DebtorParty
    .(XMLNSC.Attribute){XSI_NS}:type = 'isf:DebtorRole';

-- Delete empty optional element to prevent ISF validation errors
IF NOT EXISTS(rISF.{ISF_NS}Body.{ISF_NS}CreditTransfer.{ISF_NS}RemittanceInformation.*[]) THEN
    DELETE FIELD rISF.{ISF_NS}Body.{ISF_NS}CreditTransfer.{ISF_NS}RemittanceInformation;
END IF;
```

---

## Mapper Subflow Naming Convention

Document these names in RSAD (in the Channel class model and sequence diagrams):

| Direction | Convention | Example |
|---|---|---|
| Inbound (to ISF) | `MapIn<Format>` | `MapInSwiftMT103`, `MapInPacs008` |
| Outbound (from ISF) | `MapOut<Format>` | `MapOutSwiftMT103`, `MapOutPacs008` |
| Two-way | `Map<Format>` | `MapSwiftMT103` |

The mapper name in the Channel model must exactly match the ACE subflow name deployed in the
integration server. Any mismatch causes the PT Flow to fail with a mapper-not-found error.

---

## Mapping Design Artifact

The RSAD design for mapping should produce:

1. **Mapping Strategy document** (in Confluence / attached to JIRA):
   - Source format and schema reference
   - Target format (ISF version)
   - Technology choice (ESQL / Java / XSLT / WTX)
   - Field-level mapping table

2. **Field mapping table** (minimum required in RSAD design):

| Source Field | Source Path | Target ISF Element | Transformation |
|---|---|---|---|
| Value Date | MT103/Field32A/Date | Header/ValueDate | Format: YYMMDD → YYYY-MM-DD |
| Currency | MT103/Field32A/Currency | InstructedAmount/@Currency | Direct copy |
| Amount | MT103/Field32A/Amount | InstructedAmount/text() | Decimal normalization |
| Sender BIC | MT103/Field51A/BIC | DebtorAgent/FinancialInstitution/BIC | Direct copy |

3. **Sequence diagram annotation**: Mark the mapper invocation in the functional sequence
   diagram with the mapper subflow name and technology.

---

## WTX/ITX Mapping Design

When WTX (IBM Transformation Extender / IBM App Connect Professional) is used:

- The RSAD design should reference the WTX map name and version
- Document input/output schema files (`.dpa` for WTX, or XSD)
- The ACE flow invokes WTX via a Mapping node or Java call
- Include WTX map files in the same repository as ACE projects
- Test maps standalone in WTX Design Studio before ACE integration

WTX is typically used for:
- SWIFT FIN (MT) message parsing (tag-value format)
- ACH NACHA (fixed-position format)
- EDIFACT or X12 EDI
- ISO 8583 (card payment binary format)


path: references/ftm-design-workflow.md
content: # FTM Design Workflow in RSAD

This reference covers the step-by-step process for designing a new FTM interface using RSAD,
from receiving a JIRA ticket through to handing off design artifacts for ACE implementation.

---

## Step 1: Understand the Requirement

Before opening RSAD, answer these questions from the JIRA ticket and Confluence:

1. **What payment type?** (SWIFT MT103, ISO 20022 pacs.008, ACH, CHAPS, etc.)
2. **Which FTM pattern?** (See `patterns-artifacts.md` — select from 9.1–9.15)
3. **Inbound or outbound?** Or both (bilateral)?
4. **What external system?** (New SP? Or modify existing SP?)
5. **What transport?** (MQ, HTTP, FILE)
6. **What mapper technology?** (ESQL / Java / XSLT / WTX — see `mapping-design.md`)
7. **New FSM or extend existing?** (Use generic FSMs if possible)
8. **Error handling requirements?** (What alert states are needed?)

---

## Step 2: Identify or Create the Service Participant

A **Service Participant (SP)** represents either:
- An external financial institution or system (bank, clearinghouse, gateway)
- An internal FTM service (e.g., a separate payment rail)

### New SP checklist:
- [ ] Name: `<INSTITUTION_CODE>_<RAIL>` (e.g., `SWIFT_MT103`, `FPS_OUTBOUND`)
- [ ] Type: BANK / CLEARINGHOUSE / INTERNAL
- [ ] Role: maps to ISO 20022 party role (e.g., `DEBTOR_AGENT`, `CREDITOR_AGENT`)
- [ ] Status: ACTIVE (set INACTIVE until go-live)
- [ ] Channels: one per direction per format

### SP configuration in RSAD class diagram:
```
Class: ServiceParticipant
  «stereotype: FTM_SP»
  + sp_name: String = "SWIFT_OUTBOUND"
  + sp_type: String = "BANK"
  + role: String = "CREDITOR_AGENT"
  + active: Boolean = true

Class: Channel
  «stereotype: FTM_Channel»
  + channel_name: String = "SWIFT_MT103_OUT"
  + direction: String = "OUTBOUND"
  + format: String = "SWIFT_MT103"
  + mapper_subflow: String = "MapOutSwiftMT103"
  + output_queue: String = "FTM.SWIFT.OUT"
  + transport: String = "MQ"
```

---

## Step 3: Draw the Use Case Diagram

Purpose: establish WHO does WHAT at the highest functional level.

Template for a new interface:
```
Actors: [External System], [FTM Operator], [Receiving System]
Use Cases (inside FTM boundary):
  - Receive [Payment Type] Message
  - Validate and Map to ISF
  - Route Transaction
  - Deliver to [Receiving System]
  - Handle Processing Error        «include»
  - Notify Operator of Alert       «include»
```

Rules:
- Every external actor has at least one primary use case
- Include error handling as a shared use case via `«include»`
- Do not model implementation details here — keep it functional

---

## Step 4: Draw the Functional Sequence Diagram

This is the primary design artifact reviewed by architects and business analysts.

**Lifelines to include:**
1. External System (sending)
2. PT Flow (Physical Transmission — entry point ACE flow)
3. Inbound Mapper (ACE subflow)
4. DB2 (FTM database)
5. MQ Event Queue
6. EP Flow (Event Processing — orchestration ACE flow)
7. Action Subflow (ACE subflow executing FSM action)
8. External System (receiving, if outbound)

**Mandatory message sequence (Pattern 9.1 Outbound as example):**
```
1. ExternalSystem → PTFlow: Inbound raw message
2. PTFlow → Mapper: invoke mapper subflow
3. Mapper → PTFlow: return ISF document
4. PTFlow → DB2: INSERT Transmission (state=RECEIVED)
5. PTFlow → DB2: INSERT Transaction (state=INITIAL)
6. PTFlow → MQEventQueue: PUT E_MpInMappingComplete
7. MQEventQueue → EPFlow: GET event
8. EPFlow → DB2: SELECT FSM transitions for state=INITIAL, event=E_MpInMappingComplete
9. EPFlow → ActionSubflow: Execute ValidateAndRoute action
10. ActionSubflow → DB2: UPDATE Transaction state=VALIDATED
11. ActionSubflow → MQOutbound: PUT outbound message
12. ActionSubflow → MQEventQueue: PUT E_TxnOutCreated
```

**Error path (always include):**
```
3a. Mapper fails → PTFlow raises E_MpInMappingAborted
4a. EPFlow transitions Transaction to PMP_Alert state
5a. OAC shows alert to operator
```

---

## Step 5: Design the FSM(s)

See `fsm-design.md` for the full FSM reference. Summary of what to decide here:

- **Object type**: Transaction FSM? Transmission FSM? Both?
- **SUBTYPE**: Unique identifier for this interface's FSM (registered in `VALUE` table)
- **OBJECT_SELECTION_TEMPLATE**: SQL WHERE clause selecting objects for this FSM
- **States**: Map each processing stage to a named state
- **Events**: Use standard events where possible (see standard events table in `fsm-design.md`)
- **Actions**: Name of ACE subflow to execute (follows naming convention: `Act<Name>`)
- **Stereotypes**: Apply `PMP_Alert`, `PMP_Terminal` correctly

---

## Step 6: Select Mapping Technology

The mapping decision is made during design and documented in RSAD before ACE implementation.

| Technology | Use When |
|---|---|
| **ESQL** | Simple to moderate transforms; ISF field-by-field mapping; standard choice |
| **Java** | Complex logic, external library calls, recursive parsing |
| **XSLT** | XML-to-XML structural transforms; stylesheet-based |
| **WTX/ITX** | Very large/complex transforms; legacy integration; batch file processing |

See `mapping-design.md` for full guidance.

---

## Step 7: Export SQL Configuration

After modeling SP, Channel, and FSM in RSAD:

1. **Right-click model** → IBM FTM → Export Configuration
2. Review each generated SQL file:

```sql
-- sp_config.sql
INSERT INTO SERVICE_PARTICIPANT_BASE
  (SP_NAME, SP_TYPE, ROLE, STATUS, ...)
VALUES
  ('SWIFT_OUTBOUND', 'BANK', 'CREDITOR_AGENT', 'INACTIVE', ...);

-- channel_config.sql
INSERT INTO CHANNEL_BASE
  (CHANNEL_NAME, SP_NAME, DIRECTION, FORMAT, MAPPER, OUTPUT_QUEUE, ...)
VALUES
  ('SWIFT_MT103_OUT', 'SWIFT_OUTBOUND', 'OUT', 'SWIFT_MT103', 'MapOutSwiftMT103', 'FTM.SWIFT.OUT', ...);

-- fsm_config.sql
INSERT INTO FSM (FSM_NAME, OBJECT_TYPE, SUBTYPE, OBJECT_SELECTION_TEMPLATE)
VALUES ('TxnFSM_SWIFT_OUT', 'TRANSACTION', 'SWIFT_OUTBOUND_TXN', 'SUBTYPE = ''SWIFT_OUTBOUND_TXN''');

INSERT INTO FSM_STATE_REL (FSM_NAME, STATE_NAME, STATE_TYPE)
VALUES ('TxnFSM_SWIFT_OUT', 'INITIAL', 'NORMAL');
-- ... more states

INSERT INTO FSM_TRANSITION (FSM_NAME, FROM_STATE, EVENT_TYPE, ACTION, TO_STATE, TRANSITION_PRIORITY)
VALUES ('TxnFSM_SWIFT_OUT', 'INITIAL', 'E_MpInMappingComplete', 'ActValidateAndRoute', 'VALIDATED', 1);
-- ... more transitions
```

3. Register new SUBTYPE in VALUE table:
```sql
INSERT INTO VALUE (NAME, VALUE, DESCRIPTION)
VALUES ('ROLE_FOR_TXN_TYPE', 'SWIFT_OUTBOUND_TXN:CREDITOR_AGENT', 'SWIFT outbound transaction type');
```

---

## Step 8: Hand Off to ACE Development

Package and hand off these artifacts for ACE implementation:

| Artifact | Consumed By |
|---|---|
| Functional sequence diagram | ACE developer (flow structure reference) |
| FSM state machine diagram | ACE developer (action subflow list, event names) |
| SQL config scripts | DB2 DBA (import to FTM database) |
| Mapper technology decision | ACE developer (ESQL/Java/WTX implementation) |
| SP/Channel config | ACE developer (queue names, mapper subflow names) |

The ACE developer should not need to make any architectural decisions — RSAD design artifacts
contain all the information needed to implement without ambiguity.

---

## Modifying an Existing Interface

When a JIRA ticket modifies an existing interface (not creating new):

1. Open RSAD and locate the existing SP/FSM model
2. Identify what changed: new state? new event? channel attribute update?
3. Make minimal changes — don't redesign if only one transition changes
4. Re-export only the affected SQL (FSM transitions, channel record, etc.)
5. Apply the delta SQL to DB2 (UPDATE or INSERT the changed rows)
6. Update the sequence diagram if the message flow changed
7. Commit all changed `.emx`/`.uml` files + SQL delta to version control

---

## Design Review Checklist

Before handing off RSAD artifacts for implementation:

- [ ] Use case diagram reviewed with business analyst
- [ ] Functional sequence diagram reviewed with architect
- [ ] FSM covers all paths: happy path, error path, timeout path
- [ ] Every FSM path ends in a terminal state
- [ ] Every error path has a `PMP_Alert` state with Constraints
- [ ] SP and channel names follow naming conventions
- [ ] SQL scripts generated and reviewed (no orphaned FK references)
- [ ] Mapping technology decision documented
- [ ] Artifacts committed to version control


path: evals/evals.json
content: {
  "skill_name": "ibm-rsad-copilot",
  "evals": [
    {
      "id": 0,
      "prompt": "I'm starting a new FTM interface for outbound SWIFT MT103 payments. The sending bank submits payments via MQ, FTM processes them, and delivers to the SWIFT network. I need to design this in RSAD. What artifacts do I need to produce and what should the FSM look like?",
      "expected_output": "Complete design guidance including: the 7 required RSAD artifacts, a detailed FSM with states/transitions/events (including PMP_Alert states with Constraints), SP/Channel configuration details, and the sequence of RSAD steps to follow. Should reference Pattern 9.1, include standard events like E_MpInMappingComplete, and mention SQL export.",
      "files": [],
      "assertions": [
        {
          "id": "mentions-7-artifacts",
          "description": "Lists the standard RSAD design artifacts (use case, sequence, FSM, SP/channel config, deployment, SQL export)"
        },
        {
          "id": "fsm-has-pmp-alert",
          "description": "FSM design includes PMP_Alert states with Constraints tagged values (Cancel/Resubmit)"
        },
        {
          "id": "references-pattern-91",
          "description": "References FTM Pattern 9.1 (Outbound Message/File) as the applicable pattern"
        },
        {
          "id": "uses-standard-events",
          "description": "Uses standard FTM events: E_MpInMappingComplete and/or E_MpInMappingAborted"
        },
        {
          "id": "mentions-sql-export",
          "description": "Mentions exporting SQL configuration scripts from the RSAD model"
        }
      ]
    },
    {
      "id": 1,
      "prompt": "I have a JIRA ticket: 'Add timeout handling to the CHAPS outbound transaction FSM. If the transaction is in WAITING_FOR_ACK state for more than 2 hours, raise an operator alert.' How do I implement this in RSAD?",
      "expected_output": "Step-by-step RSAD instructions including: add Heartbeat transition with Object Filter on timeout, add TIMEOUT_ALERT state with PMP_Alert stereotype and Constraints, export updated FSM SQL, commit to version control.",
      "files": [],
      "assertions": [
        {
          "id": "heartbeat-event",
          "description": "References E_Heartbeat event for timeout detection"
        },
        {
          "id": "object-filter-timeout",
          "description": "Mentions Object Filter / guard condition on timeout field (e.g., timeout < NOW() or CURRENT TIMESTAMP)"
        },
        {
          "id": "pmp-alert-stereotype",
          "description": "Instructs applying PMP_Alert stereotype to the new timeout alert state"
        },
        {
          "id": "constraints-tagged-value",
          "description": "Mentions adding Constraints tagged value (Cancel, Continue) to the alert state"
        },
        {
          "id": "sql-export-step",
          "description": "Includes step to re-export/regenerate SQL config from updated RSAD model"
        }
      ]
    },
    {
      "id": 2,
      "prompt": "We're implementing an ISO 20022 pacs.008 inbound payment flow. I need to choose a mapping technology and document the field mapping from pacs.008 to ISF. The source message has Cdtr, Dbtr, CdtTrfTxInf/IntrBkSttlmAmt elements. What should I do in RSAD and what mapping technology should I use?",
      "expected_output": "Mapping technology recommendation (ESQL), field-level mapping table, ESQL patterns for ISF, mapper naming convention (MapInPacs008), and how to document in RSAD Channel config and sequence diagram.",
      "files": [],
      "assertions": [
        {
          "id": "recommends-esql",
          "description": "Recommends ESQL as the mapping technology for ISO 20022 XML-to-ISF transformation"
        },
        {
          "id": "isf-namespace",
          "description": "References the ISF namespace (http://www.ibm.com/xmlns/prod/ftm/isf/v3)"
        },
        {
          "id": "mapper-naming-convention",
          "description": "Mentions mapper naming convention (e.g., MapInPacs008)"
        },
        {
          "id": "currency-as-attribute",
          "description": "Notes that currency/amount must be set as an XML attribute in ESQL (.(XMLNSC.Attribute)Currency pattern or similar)"
        },
        {
          "id": "channel-config",
          "description": "Mentions documenting the mapper subflow name in the RSAD Channel configuration"
        }
      ]
    }
  ]
}


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)