swift_mt_message/fields/field11.rs
1//! # Field 11: MT Reference
2//!
3//! ## Purpose
4//! Identifies the original message being referenced in acknowledgment, cancellation, or status inquiry messages.
5//! This field establishes critical traceability links between original transactions and their related responses,
6//! enabling proper transaction lifecycle management and exception handling in the SWIFT network.
7//!
8//! ## Options Overview
9//! - **Option R**: Used in acknowledgment and response contexts
10//! - **Option S**: Used in cancellation requests and status inquiry messages
11//!
12//! ## Format Specification
13//! Both options follow identical format: `3!n6!n[4!n][6!n]`
14//! - **Message Type**: 3 numeric digits (103, 202, etc.)
15//! - **Date**: 6 numeric digits (YYMMDD format)
16//! - **Session Number**: Optional 4 numeric digits
17//! - **Input Sequence Number**: Optional 6 numeric digits
18//!
19//! ## Usage by Message Type
20//! - **MT110**: Advice of Cheque(s) - references original payment instruction
21//! - **MT111**: Request for Stop Payment - references cheque to be stopped
22//! - **MT112**: Status of Stop Payment Request - references original stop request
23//! - **MT192**: Request for Cancellation (Customer) - references message to cancel
24//! - **MT196**: Client Side Query - references message being queried
25//! - **MT292**: Request for Cancellation (Treasury) - references treasury message to cancel
26//! - **MT296**: Answer to Client Side Query - references original query
27//!
28//! ## Option Selection Guidelines
29//! ### When to Use Option R (Response Context)
30//! - **Acknowledgments**: Confirming receipt of original message
31//! - **Status Responses**: Providing status updates on original transactions
32//! - **Confirmation Messages**: Confirming execution of original instructions
33//! - **Response Messages**: Any response to an original message
34//!
35//! ### When to Use Option S (Status/Cancellation Context)
36//! - **Cancellation Requests**: Requesting cancellation of original message
37//! - **Status Inquiries**: Inquiring about status of original message
38//! - **Stop Payment Requests**: Stopping cheque or payment instructions
39//! - **Transaction Control**: Any control operation on original message
40//!
41//! ## Network Validation Rules
42//! - **Message Type**: Must be valid 3-digit SWIFT message type
43//! - **Date Validation**: Must be valid calendar date in YYMMDD format
44//! - **Sequence Validation**: Session and sequence numbers must be numeric when present
45//! - **Reference Integrity**: Referenced message should exist and be accessible
46//! - **Authority Validation**: Sender must have authority to reference/cancel message
47//!
48//! ## Message Traceability Benefits
49//! ### Transaction Lifecycle Tracking
50//! - **Payment Chain**: Link all related messages in payment processing
51//! - **Exception Handling**: Identify problematic transactions for investigation
52//! - **Audit Trails**: Maintain complete transaction history for compliance
53//! - **Customer Service**: Provide accurate status updates to customers
54//!
55//! ### Operational Efficiency
56//! - **Automated Processing**: Enable STP for acknowledgments and cancellations
57//! - **Risk Management**: Proper identification prevents erroneous operations
58//! - **Dispute Resolution**: Clear audit trail for transaction disputes
59//! - **System Integration**: Support end-to-end transaction processing
60//!
61//! ## Cancellation Windows and Timing
62//! - **Customer Payments (MT192)**: Typically cancellable before beneficiary credit
63//! - **Treasury Messages (MT292)**: Cancellation windows vary by market practice
64//! - **Stop Payment (MT111)**: Must reference valid cheque payment instruction
65//! - **Real-time Processing**: Immediate processing reduces cancellation windows
66//!
67//! ## Best Practices
68//! - **Complete References**: Include session and sequence numbers when available
69//! - **Timely Processing**: Process cancellation requests promptly within business windows
70//! - **Validation**: Verify referenced message exists and is in appropriate state
71//! - **Documentation**: Maintain clear records of all reference relationships
72//!
73//! ## Error Prevention Guidelines
74//! - **Verify Message Type**: Ensure referenced message type is correct
75//! - **Validate Date**: Confirm date matches original message exactly
76//! - **Check Authority**: Verify sender has rights to reference/cancel message
77//! - **Avoid Duplicates**: Prevent multiple references to same original message
78//! - **Sequence Accuracy**: Use precise sequence numbers to avoid wrong message targeting
79//!
80//! ## Related Fields Integration
81//! - **Field 20**: Sender's Reference (original message identifier)
82//! - **Field 21**: Related Reference (cover payment relationships)
83//! - **Block 1**: Basic Header (contains actual session and sequence numbers)
84//! - **Block 3**: User Header (additional reference information)
85//!
86//! ## Compliance and Regulatory Aspects
87//! - **Audit Requirements**: Maintain complete reference chains for audit purposes
88//! - **Regulatory Reporting**: Support regulatory transaction reporting requirements
89//! - **Data Retention**: Preserve reference relationships for required retention periods
90//! - **Investigation Support**: Enable transaction investigation and dispute resolution
91//!
92//! ## See Also
93//! - Swift FIN User Handbook: Message Reference Standards
94//! - Cancellation Guidelines: Timing and Authority Requirements
95//! - Exception Handling Guide: Proper Reference Usage
96//! - Network Rules: Message Identification Standards
97
98use chrono::NaiveDate;
99use serde::{Deserialize, Serialize};
100use swift_mt_message_macros::SwiftField;
101
102/// **Field 11R: MT Reference (Option R)**
103///
104/// Response context variant of [Field 11 module](index.html). Used in acknowledgment
105/// and response messages to reference the original message.
106///
107/// **Components:**
108/// - Message type (3!n)
109/// - Date (6!n, YYMMDD format)
110/// - Session number (optional, \[4!n\])
111/// - Input sequence number (optional, \[6!n\])
112///
113/// For complete documentation, see the [Field 11 module](index.html).
114#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, SwiftField)]
115pub struct Field11R {
116 /// Message type of the original message being referenced
117 ///
118 /// Format: 3!n - Exactly 3 numeric digits
119 /// Examples: "103", "202", "205", "940"
120 #[component("3!n")]
121 pub message_type: String,
122
123 /// Date of the original message
124 ///
125 /// Format: 6!n (YYMMDD) - Must be valid calendar date
126 /// Used to locate the original message in daily processing
127 #[component("6!n")]
128 pub date: NaiveDate,
129
130 /// Session number of the original message
131 ///
132 /// Format: \[4!n\] - Optional 4-digit session identifier
133 /// Helps identify message within specific processing session
134 #[component("[4!n]")]
135 pub session_number: Option<String>,
136
137 /// Input Sequence Number of the original message
138 ///
139 /// Format: \[6!n\] - Optional 6-digit sequence identifier
140 /// Provides precise message location within session logs
141 #[component("[6!n]")]
142 pub input_sequence_number: Option<String>,
143}
144
145/// **Field 11S: MT Reference (Option S)**
146///
147/// Status/Cancellation context variant of [Field 11 module](index.html). Used in cancellation
148/// requests and status inquiry messages for transaction control.
149///
150/// **Components:**
151/// - Message type (3!n)
152/// - Date (6!n, YYMMDD format)
153/// - Session number (optional, \[4!n\])
154/// - Input sequence number (optional, \[6!n\])
155///
156/// For complete documentation, see the [Field 11 module](index.html).
157#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, SwiftField)]
158pub struct Field11S {
159 /// Message type of the original message being referenced
160 ///
161 /// Format: 3!n - Must be valid SWIFT message type
162 /// For MT292: Valid types include 200, 202, 205, 210, 256, 299
163 #[component("3!n")]
164 pub message_type: String,
165
166 /// Date of the original message
167 ///
168 /// Format: 6!n (YYMMDD) - Must match original message date exactly
169 /// Used for precise message identification in cancellation requests
170 #[component("6!n")]
171 pub date: NaiveDate,
172
173 /// Session number of the original message
174 ///
175 /// Format: \[4!n\] - Optional but recommended for accurate targeting
176 /// Essential in high-volume processing environments
177 #[component("[4!n]")]
178 pub session_number: Option<String>,
179
180 /// Input Sequence Number of the original message
181 ///
182 /// Format: \[6!n\] - Provides highest precision for message identification
183 /// Critical for avoiding cancellation of wrong messages
184 #[component("[6!n]")]
185 pub input_sequence_number: Option<String>,
186}
187
188/// **Field 11 Enum: MT Reference Options**
189///
190/// Enum wrapper for [Field 11 module](index.html) variants providing message referencing
191/// capability for acknowledgment, cancellation, and status inquiry scenarios.
192///
193/// For complete documentation, see the [Field 11 module](index.html).
194#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, SwiftField)]
195pub enum Field11 {
196 /// Option R: Used in acknowledgment and response contexts
197 /// Common in confirmation messages and status responses
198 R(Field11R),
199
200 /// Option S: Used in cancellation and status inquiry contexts
201 /// Essential for transaction control and exception handling
202 S(Field11S),
203}