Project-A - Export - Brokerage Cargo Reports (Manual and Automatic) - Part C (** IT Request)

**** This feature has been split per IT request into 3 parts - A, B(I) and (II) and C with different scope in each part to better manage implementation approach, development and testing. Part A - Sl.No. 1 (a) to (h) and 2 Part B - I - Sl.# 3 & 4 Part B - II - Sl. # 5,6 & 7. Part C - Sl. # 1 - ( i) , (j) ,( k.) ----------------------------------- A. Problem Statement / Objective As a consolidator of export shipments, it is Carrier Co’ responsibility to communicate all goods intended for removal, by vessel or aircraft, from a place in Australia to a place outside Australia to Customs with a manifest. B. Feature Benefit Hypothesis This feature to implement the submission of export manifests assures Carrier Co' compliance with Customs Border Force requirements for processing export shipments as manifests can only be done electronically via TPS. C. Business Process Feature Scope : (Sl. No. 1- i , j , k). The system must allow the user to make changes on the BCR. The system must allow the user to withdraw the BCR. The system must allow the user to withdraw a sent BCR, reset the status and resubmit a BCR. D. Business Value This is to allow the automated submission of cargo reporting based on pre-set logic to reduce the manual work required as well as potential omissions in reporting which might occur if resorting purely on manual. Manual reporting will still be required especially for incorrect submissions and/or previous rejections. E. Scope In Scope BCR Correction, Valuation and Completion Export Manifest Submission Messaging and Status Out of Scope While EDNs are quoted on ESMs, the submission of EDNs is not covered on this Feature. References: MSG-ESM - Export Sub Manifest MSG-ESMR - MSG-ESM Response CLEAR MESSAGE FROM CUSTOMS FOR AN EXPORT DOCUMENT Reference: K00095987 CAN: AE793F636 Departure Date: 09-Sep-24 18:32:00 Port of Departure: AUSYD Country/Region of Destination: SE Flight Number: CX138 CGN Status: CLEAR Status Description: THE GOODS COVERED BY THE DOCUMENT ARE AUTHORISED FOR EXPORT AND MAY BE DEALT WITH. Status of Lines: Line: 0001 CAN: EXLV Status: CLEAR Line: 0002 CAN: EXLV Status: CLEAR Line: 0003 CAN: EXLV Status: CLEAR Line: 0004 CAN: EXLV Status: CLEAR Line: 0005 CAN: EXLV Status: CLEAR Line: 0006 CAN: EXLV Status: CLEAR Line: 0007 CAN: EXLV Status: CLEAR Line: 0008 CAN: EXLV Status: CLEAR Line: 0009 CAN: EXLV Status: CLEAR Line: 0010 CAN: EXLV Status: CLEAR Line: 0011 CAN: EXLV Status: CLEAR Line: 0012 CAN: EXLV Status: CLEAR Line: 0013 CAN: EXLV Status: CLEAR Line: 0014 CAN: EXLV Status: CLEAR Line: 0015 CAN: EXLV Status: CLEAR Line: 0016 CAN: EXLV Status: CLEAR Line: 0017 CAN: EXLV Status: CLEAR UNH+000004+CUSRES:D:99B:UN BGM+961:::MSG-ESMR+17HG 8C48 E3G4:001+11 FTX+AHN+++CLEAR:THE GOODS COVERED BY THE DOCUMENT ARE AUTHORISED FOR EXPORT AND MAY BE DEALT WITH. NAD+MR+83003926181::95 RFF+ABO:K00095987/PRD1::001 RFF+ACW:MSG-ESM RFF+AFM:9 RFF+AIZ:AE793F636 DOC+1 RFF+TL:EXLV CST+0001 FTX+AHN+++CLEAR DOC+1 RFF+TL:EXLV CST+0002 FTX+AHN+++CLEAR DOC+1 RFF+TL:EXLV CST+0003 FTX+AHN+++CLEAR DOC+1 RFF+TL:EXLV CST+0004 FTX+AHN+++CLEAR DOC+1 RFF+TL:EXLV CST+0005 FTX+AHN+++CLEAR DOC+1 RFF+TL:EXLV CST+0006 FTX+AHN+++CLEAR DOC+1 RFF+TL:EXLV CST+0007 FTX+AHN+++CLEAR DOC+1 RFF+TL:EXLV CST+0008 FTX+AHN+++CLEAR DOC+1 RFF+TL:EXLV CST+0009 FTX+AHN+++CLEAR DOC+1 RFF+TL:EXLV CST+0010 FTX+AHN+++CLEAR DOC+1 RFF+TL:EXLV CST+0011 FTX+AHN+++CLEAR DOC+1 RFF+TL:EXLV CST+0012 FTX+AHN+++CLEAR DOC+1 RFF+TL:EXLV CST+0013 FTX+AHN+++CLEAR DOC+1 RFF+TL:EXLV CST+0014 FTX+AHN+++CLEAR DOC+1 RFF+TL:EXLV CST+0015 FTX+AHN+++CLEAR DOC+1 RFF+TL:EXLV CST+0016 FTX+AHN+++CLEAR DOC+1 RFF+TL:EXLV CST+0017 FTX+AHN+++CLEAR CNT+5:0017 UNT+78+000004

Input documents:

title: SBSS Platform Knowledge Document
content: ## Carrier Co Australia Customs Brokerage System

---

## 1. Platform Overview

### What is SBSS?
SBSS (Brokerage Operations Support System) is Carrier Co Australia's customs brokerage platform used to manage import and export declarations for shipments entering or leaving Australia. It serves as the primary interface between Carrier Co customs brokers and the Customs Border Force (CBF) for regulatory compliance and customs clearance.

### Who Uses SBSS?
- **Customs Brokers (BRK)** – Process and submit declarations to customs authorities
- **Administrators (ADM)** – Configure system parameters and manage operational settings
- **Compilers (COM)** – Prepare and validate declaration data before submission
- **Operations Supervisors** – Oversee workflow and exception handling
- **Front Office Staff** – Handle day-to-day shipment processing and customer liaison

### Business Purpose
SBSS supports the end-to-end customs brokerage workflow for international shipments, including:
- Declaration preparation and validation
- Submission to customs authorities via integrated government systems
- Response handling (approvals, rejections, exceptions)
- Document management and record retention
- Charge calculation and billing
- Regulatory compliance with CBF requirements

---

## 2. System Architecture

### Core Systems in the SBSS Ecosystem

#### SBSS (Brokerage Operations Support System)
The central platform where all declaration work is performed. SBSS maintains shipment records, declarations, commodities, parties, and documents. It orchestrates communication between internal Carrier Co systems and external government platforms.

#### TPS (Trade Processing System)
The Customs Border Force's primary customs processing system. SBSS submits declarations to TPS and receives responses (permits, rejections, holds) via TradeNet messaging.

#### TradeNet
Singapore's national trade facilitation platform. For Singapore operations, SBSS communicates with TradeNet for customs approvals using EDIFACT-based messaging protocols.

#### BDIS (Brokerage Document Imaging System)
Document management system that stores scanned copies of invoices, packing lists, certificates of origin, and other supporting documents. BDIS integrates with SBSS to attach documents to declarations for customs review.

#### TCS (HAWB Management System)
Manages House Air Waybill (HAWB) records and shipment tracking references. TCS provides shipment master data to SBSS including consignee details, weights, values, and routing information.

#### MSG-ESM (Enterprise Shipment Management)
Carrier Co's enterprise-level shipment tracking system. MSG-ESM provides real-time visibility into shipment status across the Carrier Co network and feeds operational data to SBSS.

#### MSG-CSA (Cargo Release System - Trucking)
Manages cargo release for trucking operations and inland movement. MSG-CSA coordinates with SBSS to ensure shipments are physically released only after customs clearance.

#### OLAF (Operations Logistics and Forwarding)
Freight forwarding system that manages booking, routing, and carrier coordination. OLAF sends shipment forecast data to SBSS before physical arrival.

#### BCR (Broker Client Reporting)
Reporting and analytics platform that generates operational and compliance reports for brokers and customers. BCR extracts data from SBSS for business intelligence.

#### BSIS (Brokerage Statistical Information System)
Archives historical declaration data for regulatory reporting, audits, and compliance verification. BSIS ensures long-term retention of customs records as required by law.

---

## 3. Integration Patterns

### Message Exchange with Customs Authorities

#### EDIFACT Messaging
SBSS uses UN/EDIFACT (Electronic Data Interchange for Administration, Commerce and Transport) standard messages to communicate with TradeNet (Singapore) and TPS (Australia). Common message types include:

- **Declaration Messages**: Submit formal customs declarations
- **Permit Messages**: Receive customs approvals and permit numbers
- **Error Messages (ERRORM)**: Receive validation failures and rejection reasons
- **Status Messages (STATUS-R)**: Query and receive status updates on submitted declarations
- **Update Messages**: Submit amendments to previously lodged declarations

#### Message Patterns

**Synchronous Communication**:
- Real-time validation responses during declaration submission
- Immediate error feedback for malformed messages

**Asynchronous Communication**:
- Declaration submission → customs processing → permit issuance (can take minutes to hours)
- Status polling to track declaration progress through customs workflow
- Event-driven updates when customs officers complete manual review

#### Message Naming Conventions
- **INPDEC**: Import Payment Declaration (for formal clearances with duty/GST payable)
- **IPTDEC**: Import Payment Declaration (specific duty treatment types)
- **TNPDEC**: Transhipment Declaration (Batam consolidation scenario)
- **INPUPD**: Import Payment Update (amend existing declarations)
- **IPTUPD**: Import Payment Update (specific treatment amendments)
- **OUTDEC**: Outbound/Export Declaration
- **COODEC**: Country of Origin Declaration
- **INPPMT**: Import Permit (approval response)
- **IPTPMT**: Import Permit (specific treatment approval)
- **TNPPMT**: Transhipment Permit
- **OUTPMT**: Export Permit
- **COODCI**: Country of Origin Declaration Information response

### APIs and File Transfers
- **Shipment Download**: TCS pushes shipment manifests to SBSS via batch file transfer
- **Document Upload**: BDIS receives document images via API calls triggered by SBSS
- **Charge File Generation**: SBSS exports charge files to billing systems via scheduled jobs
- **Reference Data Sync**: Tariff codes, exchange rates, and regulatory tables updated via periodic feeds

---

## 4. Data Model Overview

### Key Entities and Relationships

#### Shipment
The central object representing a physical cargo movement from origin to destination.
- **Identifiers**: Shipment ID, MAWB (Master Air Waybill), HAWB (House Air Waybill), 1Z Tracking Number
- **Routing**: Origin country/port, destination country/port, transit country (for transhipments)
- **Parties**: Shipper, consignee, importer, broker
- **Weights/Values**: Gross weight, net weight, declared value, freight charges
- **Status**: Shipment status codes (e.g., 03 = in-process, 04 DA = cleared)

#### Declaration
The formal customs submission for one or more shipments.
- **Declaration Number**: Customs Reference Number (CRN) assigned by SBSS, Customs Control Number (CCN) assigned by CBF
- **Clearance Type (CT)**: FML (Formal), DEM (De minimis), LND (Low-value No-Duty), FTZ (Free Trade Zone)
- **Declaration Type**: Import/Export, Treatment codes (APS/GTR/SHO/DES/REX/GST/DUT/DNG/BKT)
- **Totals**: Declaration total value, statistical value, freight amount, insurance, duties
- **Brokerage Status**: Tracks workflow stages (RAT, EBC, CUS statuses)

#### Commodity Line
Individual line items within a declaration representing distinct products.
- **Classification**: HS Code (Harmonized System tariff code), commodity description
- **Values**: Commodity value, duty amount, supplementary quantities
- **Origin/Treatment**: Country of origin, preference codes, treatment applications
- **Linkages**: Maps back to shipment ID and invoice number via Form Type references (SHP, INV, TRK)

#### Invoice
Commercial invoice associated with shipment.
- **Invoice Number**: Unique identifier from shipper
- **Currency**: Original currency and converted value (to AUD/SGD)
- **Line Items**: Commodity details, quantities, unit prices
- **Charges**: Freight, insurance, discount allocations

#### Consignment
Grouping of related shipments for consolidated processing.
- **CONSREF#**: Consolidation Reference Number generated based on matching criteria
- **Virtual Shipment**: Temporary shipment record (prefixed with #) representing consolidated group
- **Lead Shipment**: Primary shipment within consolidation used for customs submission
- **Child Shipments**: Related shipments rolled up into virtual declaration

#### Party
Entities involved in the shipment transaction.
- **Types**: Shipper, Consignee, Importer of Record (IOR), Broker, Carrier
- **Identifiers**: TIN (Australian Business Number), OEM Client ID (Client Code ID), Tax ID
- **Attributes**: Name, address, contact details, postal code

---

## 5. User Roles and Permissions

### Front Office Roles

**Broker (BRK)**
- Primary role for declaration processing
- Can create, edit, and submit declarations to customs
- Handles document attachment and commodity classification
- Resolves exceptions and holds
- Consolidation of shipments assigned to BRK can proceed

**Administrator (ADM)**
- Configures system parameters including consolidation criteria
- Manages reference data (tariff codes, ports, countries)
- Sets up user roles and permissions
- Monitors system health and integration status
- Consolidation of shipments assigned to ADM can proceed

**Compiler (COM)**
- Prepares declarations for review before broker submission
- Validates data completeness and accuracy
- Attaches supporting documents via BDIS
- Consolidation of shipments assigned to COM can proceed

### Back Office Roles
- **Operations Supervisor**: Assigns shipments to front office staff, monitors workflow bottlenecks
- **Compliance Officer**: Audits declarations for regulatory adherence
- **Customer Service**: Responds to client inquiries about shipment status

### Assignment Logic (AST)
- Shipments must be assigned (AST) to a front office role (BRK/ADM/COM) before they can be consolidated
- Consolidation criteria can include AST status as a parameter to ensure only properly assigned shipments are grouped
- Unassigned shipments (back office) are excluded from consolidation until assignment occurs

---

## 6. Consolidation Reference System

### CONSREF# (Consolidation Reference Number)
A dynamically generated identifier that groups shipments with matching attributes for consolidated declaration submission.

#### Purpose
- Combine multiple low-value or related shipments into a single declaration
- Reduce processing overhead and submission costs
- Ensure accurate duty/tax calculation on aggregated values
- Prevent tax evasion on de minimis thresholds

#### Generation Logic
CONSREF# is constructed by parsing and concatenating values from configured matching parameters:

| Parameter | Max Chars | Parsing Rule | Example |
|-----------|-----------|--------------|---------|
| Importer Account # | 6 | Last 6 chars (exclude leading zeros) | 123456 |
| Movement Number | 8 | Full value | 12345678 |
| MAWB | 8 | Last 8 digits | 81542000 |
| Import Date | 8 | DDMMYYYY | 18032024 |
| Transit Country | 2 | Full country code | SG |
| Clearance Type | 3 | Full code | DEM |
| Shipment Indicator | Variable | Full value | TTR |
| Forecast Status | 6 | Literal value | FORCMP |

**Maximum Length**: 35 characters (right-trimmed if exceeded)

#### Matching Criteria Sets
Admins configure multiple criteria sets, each with a primary parameter:

- **Set A (Trusted Traders)**: Shipment Indicator (TTR) + Importer Account + Import Date
- **Set B (Batam Transhipments)**: Transit Country (SG/MY) + Destination Country + Import Date
- **Set C (De minimis)**: Clearance Type (DEM) + Import Date + Consignee Telephone + Movement Number
- **Set D (Forecast Complete)**: Forecast Status (FOR=CMP) + Importer Account + MAWB

#### Priority Order
Systems check criteria sets in configured sequence:
- **Australia**: Set A → Set C (Trusted Traders → De minimis)
- **Singapore**: Set B → Set C (Batam → De minimis)

### Virtual Shipments
When consolidation occurs:
1. System creates a **Virtual Shipment** with ID starting with # (e.g., #000000035)
2. Virtual shipment aggregates declaration data from all child shipments
3. **Lead Shipment** (highest value or package count) represents the group in customs submission
4. Child shipments retain individual records but reference virtual/lead via comments and events

---

## 7. Environment and Infrastructure

### Deployment Architecture
- **Production Environment**: Live system processing real customs declarations
- **Testing Environment**: Mirrors production for user acceptance testing and regression testing
- **Development Environment**: Sandbox for feature development and integration testing

### Connectivity
- **CBF TPS Connection**: Secure gateway for Australian customs messaging (encrypted, VPN-tunneled)
- **TradeNet Connection**: Singapore customs network access via certified messaging protocol
- **SBSS Internal Network**: Connects to TCS, MSG-ESM, OLAF, BDIS, MSG-CSA within Carrier Co infrastructure

### Data Residency
- Australian operations: Data stored in Australia to comply with CBF data sovereignty requirements
- Singapore operations: Data stored in Singapore for TradeNet compliance

---

## 8. Glossary of Domain Terms

### Shipment and Routing
- **MAWB**: Master Air Waybill – carrier's shipment identifier
- **HAWB**: House Air Waybill – freight forwarder's sub-shipment identifier
- **1Z Number**: Carrier Co tracking number format
- **PTN**: Package Tracking Number
- **OCC**: Origin Country Code
- **OPC**: Origin Port Code
- **DCC**: Destination Country Code
- **DPC**: Destination Port Code
- **TCC**: Transit Country Code

### Declaration Types and Clearance
- **FML**: Formal Entry – full customs declaration with duty/tax calculation
- **DEM**: De minimis – low-value exemption clearance
- **LND**: Low-value No-Duty – clearance for goods below duty threshold
- **FTZ**: Free Trade Zone – special customs area treatment
- **INF**: Informal Entry (deprecated, replaced by DEM)

### Brokerage Status Codes
- **RAT**: Rating Status (duty calculation stage)
- **EBC**: E-Broker Complete (internal validation complete)
- **CUS**: Customs Status (submission and response tracking)
- **FOR**: Forecast Status (document scanning/preparation stage)
- **AST**: Assignment Status (which user role owns the shipment)
- **MAN**: Manual Review Status (customs hold for examination)

### CUS Status Values
- **SNT**: Sent to Customs
- **SCR**: Successfully Received (acknowledgment from customs)
- **SCA**: Scanning Required (customs document request)
- **APP**: Approved
- **ERR**: Error (validation failure)
- **REJ**: Rejected (customs refusal)
- **INS**: Inspection Required
- **CLR**: Cleared for Release
- **CMP**: Complete

### RAT Status Values
- **CMP**: Complete (rating calculation finished)
- **RFC**: Ready for Customs (validation passed, ready to submit)
- **HLD1**: Hold Level 1 (pending additional information)

### Exception and Hold Codes
- **RTS**: Return to Sender
- **RTO**: Return to Origin
- **BYP**: Bypass (skip validation)
- **HLD1**: Hold Level 1 (broker action required)
- **1U**: Specific exception reason code (customs query)
- **NST**: Not Sent (message content validation failed)
- **NRQ**: No Request (declaration not yet submitted)

### Message Types
- **INPDEC**: Import Payment Declaration
- **IPTDEC**: Import Payment (Treatment-specific) Declaration
- **TNPDEC**: Transhipment Declaration
- **INPUPD**: Import Payment Update
- **IPTUPD**: Import Payment (Treatment) Update
- **OUTDEC**: Outbound/Export Declaration
- **COODEC**: Country of Origin Declaration
- **INPPMT**: Import Permit (approval)
- **IPTPMT**: Import Payment Permit
- **TNPPMT**: Transhipment Permit
- **OUTPMT**: Export Permit
- **ERRORM**: Error Message (rejection with reasons)
- **STATUS-R**: Status Request/Response

### Treatment and Preference Codes
- **APS**: ASEAN Preferential Scheme
- **GTR**: General Tariff Rate
- **SHO**: Special Handling Order
- **DES**: Destruction
- **REX**: Re-export
- **GST**: Goods and Services Tax
- **DUT**: Duty Treatment
- **DNG**: Dangerous Goods
- **BKT**: Blanket Treatment

### Parties and Identifiers
- **IOR**: Importer of Record (entity legally responsible for duties)
- **COD**: Consignee on Demand
- **TIN**: Australian Business Number
- **OEM Client ID**: Client Code ID
- **Shipper**: Party sending goods
- **Consignee**: Party receiving goods
- **Broker**: Customs agent filing declarations

### Consolidation Terms
- **CONSREF#**: Consolidation Reference Number
- **VRT/VID**: Virtual Shipment ID (prefixed with #)
- **Lead Shipment**: Primary shipment in consolidated group
- **Child Shipment**: Individual shipment rolled into consolidation
- **TTR**: Trusted Trader (shipment indicator for preferential processing)
- **Batam**: Singapore-Indonesia transhipment consolidation scenario

### Document Types
- **INV**: Commercial Invoice
- **SHP**: Shipment Identifier reference
- **TRK**: Tracking Number reference
- **CA**: Customs Acknowledgment
- **SC**: Special Conditions
- **AFD**: Additional Fee Detail
- **ERD**: Error Detail

### Financial and Charges
- **COD**: Cash on Delivery
- **FRT**: Freight Charges
- **INS**: Insurance
- **DIS**: Discount
- **UNS**: Upload Not Sent (charge file suppression flag)
- **Sigma**: Summation/total across multiple shipments

### Reference Numbers
- **CRN**: Customs Reference Number (SBSS-assigned)
- **CCN**: Customs Control Number (CBF-assigned)
- **PMT#**: Permit Number
- **PMTSD**: Permit Start Date
- **PMTED**: Permit End Date
- **CAADT**: Customs Approval Actual Date/Time
- **PMADT**: Permit Actual Date/Time
- **DESDT**: Declaration Submission Date/Time

### Shipment Status Codes
- **03**: In-Process/Submitted
- **04 DA**: Cleared/Delivered Available

---

## 9. Regulatory Context

### Customs Border Force (CBF) Requirements
- All import/export declarations must be lodged electronically via TPS
- Declarations must include accurate HS codes for tariff classification
- Supporting documents (invoices, certificates) must be retained for 5 years
- Duty and GST calculations must follow CBF guidelines
- Permit numbers must be obtained before cargo release

### Singapore Customs (TradeNet) Requirements
- Transhipment declarations required for cargo moving through Singapore en route to final destination
- De minimis thresholds apply for low-value goods
- Preferential tariff treatment requires certificates of origin
- TradeNet messaging must conform to UN/EDIFACT standards

### Compliance Obligations
- Brokers must hold valid customs broker licenses
- Declarations must be signed electronically by authorized brokers
- Tariff classification errors can result in penalties and audits
- False declarations are criminal offenses
- Record retention: 5-7 years depending on jurisdiction

---

title: Customs Brokerage Process Flow
content: ## Import and Export Clearance for Carrier Co Australia

---

## 1. Import Declaration Process (End-to-End)

### Phase 1: Shipment Arrival and Manifest Download

**Trigger**: Cargo arrives at destination airport/port or manifest is transmitted by carrier

**Activities**:
1. **Manifest Receipt**: TCS receives cargo manifest from airline/carrier with shipment details (MAWB, HAWB, consignee, origin, declared value, weight)
2. **Shipment Download to SBSS**: Manifest data flows from TCS to SBSS, creating shipment records
3. **Consolidation Matching** (if configured):
   - SBSS checks shipment attributes against configured consolidation criteria (importer account, import date, transit country, clearance type, etc.)
   - If matching criteria are met, SBSS generates CONSREF# and groups shipments
   - Admin reviews consolidation report showing CONSREF# and matching shipment counts
4. **Assignment**: Shipment assigned (AST) to broker (BRK), compiler (COM), or admin (ADM) role in front office

**Key Data Captured**:
- Shipment ID, MAWB, HAWB, tracking number
- Parties (shipper, consignee, importer)
- Declared value, weight, package count
- Routing (origin, destination, transit points)
- Movement number, flight/vessel details

**System Interactions**: TCS → SBSS → (Optional) Consolidation Engine

---

### Phase 2: Document Receipt and Validation

**Trigger**: Shipment assigned to broker for processing

**Activities**:
1. **Document Collection**:
   - Broker receives commercial invoice, packing list, certificate of origin, permits (if applicable) from shipper/consignee
   - Documents scanned and uploaded to BDIS
2. **Document Attachment**:
   - Broker attaches BDIS images to shipment declaration
   - For consolidated shipments, documents from all child shipments are merged and grouped by shipment ID in virtual declaration
3. **Forecast Status Update**:
   - Forecast status (FOR) updated to CMP (Complete) once all documents received and scanned
   - If consolidation criteria include FOR=CMP, shipments only receive CONSREF# after forecast completion

**Key Validations**:
- Invoice value matches declared shipment value
- HS codes are present and valid
- Required certificates/permits are attached
- Consignee/importer details are accurate

**System Interactions**: Broker → BDIS → SBSS

---

### Phase 3: Declaration Preparation

**Trigger**: FOR=CMP and broker begins declaration entry

**Activities**:
1. **Clearance Type Determination**:
   - **FML (Formal)**: Shipment value exceeds de minimis threshold or specific commodity requires formal entry
   - **DEM (De minimis)**: Low-value consignments below duty threshold
   - **LND (Low-value No-Duty)**: Goods below duty threshold but requiring GST
   - **FTZ**: Free trade zone clearance for bonded warehouses
2. **Declaration Data Entry**:
   - Broker enters/validates summary data (declaration type, clearance type, gross weight, declared value)
   - Customer details (shipper, consignee, importer with TIN/tax ID)
   - Movement details (arrival date, import date, movement number, port codes)
   - Charges (freight, insurance, other charges)
3. **Commodity Classification**:
   - Broker assigns HS code to each commodity line
   - Enters commodity description, quantity, unit value
   - Specifies country of origin
   - Applies treatment codes (APS/GTR/SHO/DES/REX) if preferential tariff treatment claimed
   - Attaches licenses, permits, or quota references if required
4. **Invoice Processing**:
   - For single-currency invoices: Use original declared value
   - For multi-currency invoices: SBSS converts all values to local currency (AUD/SGD) using declaration exchange rate
   - For consolidated shipments with mixed currencies: Use declaration total value (already in AUD/SGD) as baseline
5. **Consolidation (if applicable)**:
   - Broker selects matching shipments via CONSREF# from consolidation report
   - SBSS creates **Virtual Shipment** (ID starting with #) combining:
     - All commodity lines from child shipments
     - Sigma (sum) of declared values, gross weights, freight, insurance, duties
     - Common clearance type (FML forced for consolidated declarations)
     - Form type references (SHP, INV, TRK) mapping commodities back to original shipment IDs
   - **Lead Shipment** selected (highest value or package count) as primary reference for customs submission
   - Virtual shipment's declaration number (CRN) assigned

**Key Calculations**:
- **Declaration Total Value**: Sum of all invoice values (converted to local currency if needed)
- **Statistical Value**: Includes freight and insurance added to invoice value
- **Duty Amount**: Calculated per commodity line based on HS code tariff rate
- **GST/Tax**: Applied to sum of invoice value + freight + insurance + duty

**System Interactions**: SBSS (Declaration Module) → Rating Engine → Tariff Database

---

### Phase 4: Rating and Validation

**Trigger**: Broker completes data entry and initiates rating

**Activities**:
1. **Rating Calculation**:
   - SBSS rating engine retrieves tariff rates for each HS code
   - Calculates duty per commodity line (value × tariff rate)
   - Applies treatment codes (preferential rates if applicable)
   - Calculates GST on dutiable value
   - Computes total declaration charges
2. **Internal Validation**:
   - **RAT (Rating) Status** checks:
     - All commodity HS codes valid
     - Quantities and values within acceptable ranges
     - Treatment codes match HS code eligibility
     - Licenses/permits present for restricted goods
   - **EBC (E-Broker Complete) Status** checks:
     - All required fields populated
     - Party details complete (TIN, addresses)
     - Documents attached for all invoice line items
     - No conflicting data between shipment and declaration
3. **Manual Review (if needed)**:
   - High-value shipments flagged for supervisor approval
   - Unusual commodity classifications escalated to compliance officer
   - Missing document exceptions logged

**Status Progression**:
- RAT = CMP → EBC = CMP → CUS = RFC (Ready for Customs)

**System Interactions**: SBSS → Rating Engine → Validation Rules Engine

---

### Phase 5: Submission to Customs

**Trigger**: CUS = RFC and broker approves submission

**Activities**:
1. **Message Generation**:
   - SBSS constructs EDIFACT message based on declaration type and treatment:
     - **INPDEC**: Standard formal import declaration (APS/GTR/SHO/DES/REX)
     - **IPTDEC**: Import declaration with specific duty treatment (GST/DUT/DNG/BKT)
     - **TNPDEC**: Transhipment declaration (Batam consolidation scenario with inbound/outbound MAWB/HAWB)
   - For consolidated shipments:
     - Message includes all commodity lines (up to 50 per message per TradeNet limit)
     - Each commodity tagged with Form Type references (SHP/INV/TRK) to original shipment
     - Lead shipment HAWB used as declaration reference (virtual # ID not sent to customs)
2. **Message Transmission**:
   - SBSS sends message to TPS (Australia) or TradeNet (Singapore)
   - **CUS Status** updated to **SNT (Sent)**
   - Shipment status updated to **03** (In-Process)
   - Exception reason code **1U** logged (message sent, awaiting response)
   - **MAN Status** updated to **NST (Not Sent)** if validation fails, or **NRQ (No Request)** if awaiting customs action
3. **Acknowledgment**:
   - Customs system sends synchronous acknowledgment (message received and queued)
   - **CUS Status** updated to **SCR (Successfully Received)**
   - Broker sees confirmation in SBSS that declaration is in customs processing queue

**System Interactions**: SBSS → TradeNet/TPS Gateway → Customs Backend

---

### Phase 6: Customs Processing and Response

**Customs Processing (External)**:
1. Customs system validates message format and content
2. Runs risk assessment algorithms
3. Routes to officer review if flagged, otherwise auto-processes
4. Generates permit or rejection

**SBSS Receives Response**:

#### Scenario A: Approval (Permit Issued)

**Inbound Message**: INPPMT, IPTPMT, or TNPPMT

**Activities**:
1. SBSS receives permit message with:
   - **CCN (Customs Control Number)**: Official customs identifier
   - **Permit Number (PMT#)**: Authorization to release cargo
   - **PMTSD/PMTED**: Permit validity period
   - **CAADT/PMADT**: Customs approval date/time
2. **CUS Status** updated to **APP (Approved)**
3. **Shipment Status** updated to **04 DA (Cleared/Delivered Available)**
4. **For Consolidated Shipments**:
   - Virtual shipment receives response first
   - SBSS automatically syncs permit details to **Lead Shipment** declaration
   - Lead shipment's permit details copied to all **Child Shipments** via:
     - Declaration > Customs > Reference Number fields (CCN, PMT#, PMTSD, PMTED, CAADT, PMADT)
     - Shipment comments (Customer Supplied References synced)
     - Brokerage events logged for each child ("Consolidated under Shipment ID XXXXX", "Permit received: PMT#")
5. **Charge File Generation**:
   - For consolidated shipments, single charge file generated from **Lead Shipment** only
   - Charge file includes:
     - Government charges (duties, GST) from declaration
     - Accessorial charges (brokerage fees, document fees) from shipment
   - Child shipments flagged **UNS (Upload Not Sent)** to suppress duplicate charge files
6. **Document Update**:
   - Approved declaration form (PDF) generated and attached to BDIS
   - For consolidated shipments, declaration form available on virtual, lead, and all child shipments
7. **Release Notification**:
   - SBSS notifies MSG-CSA that shipment is cleared for release
   - Warehouse receives pickup authorization

**System Interactions**: TPS/TradeNet → SBSS → Lead/Child Shipments → MSG-CSA → Billing System

---

#### Scenario B: Rejection (Declaration Refused)

**Inbound Message**: ERRORM or STATUS-R with rejection codes

**Activities**:
1. SBSS receives rejection message with:
   - Error codes and descriptions (e.g., "HS code invalid", "Missing license", "Value discrepancy")
   - Line-level or declaration-level errors
2. **CUS Status** updated to **ERR (Error)** or **REJ (Rejected)**
3. **Shipment Status** remains **03** (not cleared)
4. **MAN Status** may update to specific hold code indicating reason
5. Broker reviews error details in SBSS
6. **For Consolidated Shipments**:
   - If entire declaration rejected, all child shipments receive rejection status sync
   - If specific commodity lines rejected, broker identifies faulty child shipments via Form Type SHP references
7. **Exception Handling**:
   - Broker corrects errors (amends HS code, uploads missing document, adjusts value)
   - Broker submits **INPUPD/IPTUPD** (update message) with corrections
   - Or broker withdraws declaration and resubmits fresh INPDEC

**System Interactions**: TPS/TradeNet → SBSS → Broker Worklist

---

#### Scenario C: Hold for Inspection

**Inbound Message**: Customs inspection request or SCA (Scanning Required) status

**Activities**:
1. SBSS receives hold notification
2. **CUS Status** updated to **INS (Inspection Required)** or **SCA (Scanning Required)**
3. **MAN Status** updated to **HLD1** or specific hold code
4. Broker coordinates with customs officer:
   - Provides additional documents
   - Arranges physical inspection at cargo facility
   - Responds to queries via SBSS messaging or email
5. Once inspection cleared:
   - Customs issues permit (follows Scenario A path)
   - Or requests amendment (follows Scenario B path)

**System Interactions**: SBSS ↔ Customs Officer (manual intervention) → TPS/TradeNet

---

### Phase 7: Cargo Release and Finalization

**Trigger**: CUS = APP and shipment status = 04 DA

**Activities**:
1. **Cargo Release**:
   - MSG-CSA receives clearance notification from SBSS
   - Warehouse releases cargo to consignee or delivery carrier
   - Physical handover confirmed in MSG-ESM
2. **Billing**:
   - Charge file sent to billing system
   - Customer invoiced for duties, GST, brokerage fees, accessorial charges
   - For consolidated shipments, single invoice issued to lead shipment's importer
3. **Record Archival**:
   - Declaration, commodity, document, and message data archived in BSIS
   - Retention period: 5 years minimum for compliance
4. **Reporting**:
   - BCR generates reports for:
     - Daily clearance volumes
     - Duty/GST collected
     - Exception rates (rejections, holds)
     - Consolidation efficiency metrics

**System Interactions**: SBSS → MSG-CSA → MSG-ESM → Billing System → BSIS/BCR

---

## 2. Export Declaration Process (End-to-End)

### Phase 1: Booking and Shipment Creation

**Trigger**: Customer books export shipment via OLAF or Carrier Co sales channel

**Activities**:
1. **Booking Entry**:
   - Customer provides shipper, consignee, commodity details, destination, requested pickup date
   - OLAF creates shipment booking record
2. **Manifest Generation**:
   - OLAF transmits shipment manifest to SBSS
   - SBSS creates export shipment record
3. **Assignment**:
   - Shipment assigned to broker for export declaration preparation

**Key Data Captured**:
- Shipper (exporter), consignee (foreign buyer)
- Commodity descriptions, HS codes, values
- Export country, port of exit, destination country
- Export date, outbound movement number

**System Interactions**: OLAF → SBSS

---

### Phase 2: Export Declaration Preparation

**Trigger**: Broker receives assigned export shipment

**Activities**:
1. **Document Collection**:
   - Commercial invoice, packing list, certificate of origin (if required)
   - Export licenses/permits for controlled goods
2. **Declaration Entry**:
   - Export declaration type selected (OUTDEC or COODEC)
   - Commodity classification (HS code, description, quantity, value)
   - Party details (exporter with TIN, foreign consignee)
   - Movement details (export date, port of exit, vessel/flight details)
3. **Validation**:
   - Restricted/prohibited goods checks
   - Export license verification for dual-use or strategic goods
   - Country-of-origin certification for FTA eligibility

**System Interactions**: SBSS → Tariff/License Database

---

### Phase 3: Submission to Customs

**Trigger**: Broker completes and approves export declaration

**Activities**:
1. **Message Generation**:
   - **OUTDEC**: Standard export declaration
   - **COODEC**: Certificate of origin declaration (for FTA preferential treatment in destination country)
2. **Transmission**:
   - SBSS sends message to TPS/TradeNet
   - **CUS Status** = **SNT**
   - **Shipment Status** = **03**
   - **Exception Reason** = **1U**
3. **Acknowledgment**:
   - Customs acknowledges receipt
   - **CUS Status** = **SCR**

**System Interactions**: SBSS → TPS/TradeNet

---

### Phase 4: Customs Response and Clearance

#### Scenario A: Approval

**Inbound Message**: OUTPMT or COODCI

**Activities**:
1. SBSS receives export permit
2. **CUS Status** = **CLR (Cleared)**
3. **Shipment Status** = **04 DA**
4. Cargo released for loading onto vessel/aircraft
5. Permit attached to shipment for carrier handover

**System Interactions**: TPS/TradeNet → SBSS → MSG-CSA

---

#### Scenario B: Hold/Rejection

**Inbound Message**: ERRORM or hold notification

**Activities**:
1. **CUS Status** = **ERR** or **HLD (Hold)**
2. Broker coordinates with customs officer to resolve issue
3. Submits correction via **OUTUPD** (export update message)
4. Re-approval follows Scenario A path

---

### Phase 5: Departure and Finalization

**Trigger**: Cargo loaded and vessel/aircraft departs

**Activities**:
1. Carrier confirms departure to SBSS
2. Final shipment status updated in MSG-ESM
3. Export declaration archived in BSIS
4. Customer invoiced for brokerage fees

**System Interactions**: Carrier → MSG-ESM → SBSS → BSIS

---

## 3. Message Lifecycle (Import/Export)

### Creation
- Declaration data entered in SBSS UI
- SBSS constructs EDIFACT message per customs schema (INPDEC/IPTDEC/TNPDEC/OUTDEC/COODEC)

### Validation
- **Pre-Submission**: SBSS validates message structure, mandatory fields, data types
- **Post-Submission**: Customs performs content validation (HS codes, party IDs, value ranges)

### Submission
- SBSS transmits message via secure gateway to TPS/TradeNet
- CUS = SNT, Shipment Status = 03, Exception = 1U

### Response Handling
- **Acknowledgment**: SCR (message received, queued for processing)
- **Approval**: APP → Permit issued (INPPMT/IPTPMT/TNPPMT/OUTPMT/COODCI)
- **Rejection**: ERR/REJ → Error message returned (ERRORM)
- **Hold**: INS/SCA/HLD1 → Manual review required

### Status Update
- **Synchronous**: Immediate feedback (acknowledgment, validation errors)
- **Asynchronous**: Delayed response (permit issuance after officer review, can take minutes to hours)

### Retry/Amendment
- If rejected, broker submits update message (INPUPD/IPTUPD/OUTUPD)
- Or withdraws and resubmits fresh declaration

---

## 4. Clearance Types

### FML (Formal Entry)
- **Trigger**: Shipment value exceeds de minimis threshold, or commodity requires formal declaration (e.g., restricted goods)
- **Process**: Full declaration with commodity classification, duty calculation, GST
- **Outcome**: Permit issued after customs approval, duties/taxes payable

### DEM (De minimis)
- **Trigger**: Low-value consignments (typically below AUD 1,000 or SGD 400)
- **Process**: Simplified declaration, often auto-cleared
- **Outcome**: No duty, minimal GST or exempt, faster clearance

### LND (Low-value No-Duty)
- **Trigger**: Goods below duty threshold but subject to GST
- **Process**: Declaration focuses on GST calculation, no tariff classification needed
- **Outcome**: GST payable, no customs duty

### FTZ (Free Trade Zone)
- **Trigger**: Cargo entering bonded warehouse or FTZ for storage/re-export
- **Process**: Suspended duty/tax until cargo leaves FTZ for domestic consumption
- **Outcome**: No immediate payment, duty deferred or waived on re-export

### Alternate Broker / Transhipment
- **Trigger**: Cargo transiting through country en route to final destination (e.g., Batam scenario: air into Singapore, sea out to Indonesia)
- **Process**: Transhipment declaration (TNPDEC) with inbound and outbound MAWB/HAWB
- **Outcome**: Permit issued for cargo to continue journey, no import duty (cargo not entering commerce)

---

## 5. Exception Handling

### Rejection Scenarios
- **HS Code Invalid**: Tariff code not found or incorrect format → Broker corrects and resubmits
- **Missing License**: Restricted goods require permit → Broker uploads permit document and updates declaration
- **Value Discrepancy**: Invoice value doesn't match declared value → Broker amends value or provides explanation
- **Party Details Incorrect**: TIN invalid, address incomplete → Broker updates party data

### Hold Scenarios
- **Document Request (SCA)**: Customs officer requests additional supporting documents → Broker uploads to BDIS and notifies customs
- **Physical Inspection (INS)**: Cargo examination required → Broker coordinates inspection appointment with warehouse and customs
- **Valuation Query (HLD1)**: Declared value under question → Broker provides additional invoices or valuation evidence

### Refund/Withdrawal
- **Overpayment**: Duty calculated incorrectly → Broker submits refund request with corrected calculation
- **Withdrawal (BYP)**: Declaration no longer needed (shipment cancelled, returned to sender) → Broker withdraws declaration, cargo re-exported or destroyed

---

## 6. Status Lifecycle

### Shipment Status Progression
- **Downloaded** → Shipment created in SBSS from manifest
- **Assigned (AST)** → Allocated to broker/compiler/admin
- **03** → Declaration submitted to customs, awaiting response
- **04 DA** → Cleared by customs, available for delivery
- **RTS/RTO** → Return to sender/origin (clearance failed or shipment refused)

### Declaration Brokerage Status Progression
- **RAT**: Rating calculation in progress
  - **RAT = CMP**: Rating complete, duty/tax calculated
- **EBC**: Internal validation in progress
  - **EBC = CMP**: Validation complete, ready for submission
- **CUS**: Customs submission and response tracking
  - **CUS = RFC**: Ready for Customs (internal approval to submit)
  - **CUS = SNT**: Sent to Customs
  - **CUS = SCR**: Successfully Received (acknowledged by customs)
  - **CUS = APP**: Approved (permit issued)
  - **CUS = ERR**: Error (validation failed)
  - **CUS = REJ**: Rejected (declaration refused)
  - **CUS = INS**: Inspection Required
  - **CUS = CLR**: Cleared (export approved)
  - **CUS = CMP**: Complete (all processing finished)

### Forecast Status (FOR)
- **Initiated** → Document scan process started
- **In Progress** → Some documents scanned, others pending
- **CMP (Complete)** → All documents scanned and attached
- **Note**: FOR = CMP may be consolidation criterion trigger

### Manual Review Status (MAN)
- **NST (Not Sent)**: Message content validation failed before submission
- **NRQ (No Request)**: Awaiting broker action to submit
- **HLD1**: Hold for manual review
- **Specific Exception Codes**: 1U (customs query), etc.

---

## 7. Regulatory Context

### CBF Import Requirements
- All cargo arriving in Australia must be declared electronically via TPS before release
- Importers must provide accurate HS codes for tariff classification
- Duty and GST calculated based on customs value (transaction value + freight + insurance)
- Permits required for restricted goods (food, pharmaceuticals, weapons, etc.)
- Supporting documents must be retained for 5 years for audit

### CBF Export Requirements
- Export declarations required for controlled goods (strategic exports, dual-use items)
- Certificate of origin declarations for FTA preferential treatment
- Exporters must provide accurate commodity descriptions and HS codes
- Departure confirmation required before cargo leaves Australian jurisdiction

### Singapore TradeNet Requirements
- All imports/exports/transhipments must be declared via TradeNet
- EDIFACT messaging mandatory for electronic submissions
- Transhipment permits required for cargo moving through Singapore (Batam scenario)
- De minimis threshold: SGD 400 for GST exemption
- Preferential tariff schemes (ASEAN, FTA) require certificates of origin

### Compliance Obligations
- **Broker Licensing**: Customs brokers must hold valid licenses issued by CBF or Singapore Customs
- **Electronic Signatures**: Declarations must be electronically signed by authorized brokers
- **Tariff Classification Accuracy**: Errors in HS codes can result in penalties, back-duty assessments, or criminal charges for deliberate misclassification
- **False Declarations**: Submitting false information (undervaluation, misdescription) is a criminal offense
- **Record Retention**: 5-7 years depending on jurisdiction and commodity type
- **Audit Cooperation**: Brokers must provide records upon request during customs audits

---

## 8. Consolidation-Specific Process Flow

### Identification Phase
1. Shipment downloads from manifest
2. SBSS checks shipment attributes against configured consolidation criteria sets (in priority order)
3. If match found on primary parameter + secondary parameters, CONSREF# generated and assigned
4. Shipment flagged for consolidation (viewable in consolidation matching report)

### Selection Phase
1. Broker reviews consolidation matching report (sorted by CONSREF# with highest shipment count first)
2. Broker selects shipments under same CONSREF# for consolidation
3. SBSS creates Virtual Shipment (# ID) combining:
   - All declarations and commodity lines from selected shipments
   - Sigma values (declared value, gross weight, freight, insurance, duties)
   - Common clearance type (forced to FML for consolidated submissions)
   - Form Type references mapping commodities to original shipment IDs

### Lead Shipment Assignment
1. SBSS selects lead shipment (highest value, or highest package count if values equal, or alphabetically if tied)
2. Lead shipment HAWB becomes declaration reference (virtual # ID not sent to customs)

### Submission Phase
1. Virtual declaration submitted to customs (INPDEC/IPTDEC/TNPDEC)
2. Message includes all commodity lines with Form Type tags (SHP/INV/TRK)
3. CUS = SNT on virtual, lead, and child shipments

### Response Sync Phase
1. Customs response received on virtual shipment
2. SBSS syncs permit details to lead shipment
3. Lead shipment syncs to all child shipments:
   - Declaration references (CCN, PMT#, dates)
   - Customer supplied references
   - Brokerage events
   - CUS and shipment status
   - Exception codes

### Charge File Phase
1. Single charge file generated from lead shipment
2. Child shipments flagged UNS to suppress duplicate billing

### Document Availability Phase
1. Approved declaration form available on virtual, lead, and all child shipments
2. BDIS documents merged and tagged by originating shipment ID

---

This process flow serves as the operational blueprint for all customs brokerage activities in SBSS. Brokers, compilers, and administrators follow these workflows to ensure compliant, efficient, and accurate customs clearance for Carrier Co customers.

title: Project-A - Export - Brokerage Cargo Reports (Manual and Automatic) - Part C (** IT Request) — Feature Brief
content: **Document Version:** 3.0  
**Prepared For:** Carrier Co Australia Customs Brokerage Operations  
**Business Domain:** Export Cargo Reporting and Compliance  
**Target System:** SBSS (Brokerage Operations Support System)

---

## 1. Business Need

As a consolidator of export shipments, Carrier Co Australia is legally required to communicate all goods intended for removal from Australia to the Customs Border Force (CBF) via electronic cargo manifests. The current system supports initial manifest submission (MSG-ESM Original messages), but lacks the capability to amend or withdraw manifests after submission.

When errors are discovered post-submission, or when cargo plans change (shipments cancelled, routing modified, consolidation adjusted), brokers have no automated mechanism to correct or retract previously submitted manifests. This creates compliance risk, operational delays, and manual workarounds that are error-prone and inefficient.

**Regulatory Context:**  
CBF's TPS (Trade Processing System) mandates electronic lifecycle management of export manifests. Each change or withdrawal must be submitted with an incremental version number to maintain an audit trail. Manual corrections via phone or email are not compliant with TPS requirements.

---

## 2. Business Objectives

**Primary Objectives:**
- Enable compliant amendment of previously submitted export sub-manifests when data corrections are required
- Enable withdrawal of export sub-manifests when cargo is cancelled or removed from a consolidation
- Automate status synchronization across Master Waybill, Shipment, and Flow entities to reflect customs responses
- Reduce manual intervention and error rates in export cargo reporting
- Maintain accurate audit trails of all manifest changes and customs responses

**Regulatory Compliance:**
- Meet CBF's TPS (Trade Processing System) requirements for MSG-ESM lifecycle management
- Comply with EDIFACT messaging standards for MSG-ESM Amendment (Function Code 5) and Withdrawal (Function Code 50)
- Maintain accurate audit trails of all manifest changes and customs responses
- Support TPS versioning rules: each amendment/withdrawal increments the Sender Reference Version number cumulatively across all message types (Original, Amendment, Withdrawal)

**Operational Efficiency:**
- Reduce broker workload by automating status updates from customs responses
- Prevent duplicate charge file generation for withdrawn shipments
- Provide clear visibility into amendment/withdrawal status at Master and Shipment levels
- Support re-amendment workflows when initial corrections are rejected by customs

**Customer Experience:**
- Faster resolution of export delays caused by manifest errors
- Proactive withdrawal capability prevents unnecessary customs holds on cancelled shipments
- Improved transparency: customers receive timely updates on manifest status changes

---

## 3. Scope

### In Scope

**Amendment Processing (MSG-ESM with Function Code 5):**
- Triggering MSG-ESM Amendment messages when Master Waybill BCR status is set to AMD (Amendment)
- Mapping corrected Master and Shipment data to outbound MSG-ESM message segments
- Generating and incrementing Sender Reference Version numbers for message versioning (cumulative across Original, Amendment, and Withdrawal)
- Processing MSG-ESMR (MSG-ESM Response) messages for amendments
- Updating BCR and MAN statuses based on customs approval/rejection of amendments
- Synchronizing amendment outcomes to Flow-level status references (BCRCLR, BCRERR)
- Supporting re-amendment workflows (amendment rejected → correct data → re-amend)

**Withdrawal Processing (MSG-ESM with Function Code 50):**
- Triggering MSG-ESM Withdrawal messages when Master Waybill BCR status is set to WID (Withdrawal)
- Excluding line-level data from withdrawal messages (header-only submission)
- Processing MSG-ESMR responses for withdrawals
- Updating BCR and MAN statuses to reflect withdrawal acceptance or rejection
- Suppressing charge file generation for withdrawn manifests (via UNS flag)
- Handling withdrawn manifests in downstream systems (MSG-CSA, billing)

**Response Processing (MSG-ESMR for Amendments and Withdrawals):**
- Parsing MSG-ESMR messages for header-level and line-level status updates
- Processing error/advisory segments (ERP-ERC-FTX) for validation failures
- Mapping customs-assigned statuses (CLEAR, ERROR, REJECTED, WITHDRAWN, REVOKED) to SBSS statuses
- Capturing error details at Master and Shipment levels for broker remediation
- Updating Flow-level references to reflect consolidated manifest outcomes
- Handling mixed line-level outcomes (some lines cleared, others errored)

**Data Validation and Error Handling:**
- Pre-submission validation of mandatory data elements for amendments and withdrawals
- Warning mechanisms for data quality issues (non-blocking, set MAN=FAI)
- Syntax error processing via CONTRL messages (with leading zero handling in Interchange Control Reference Number)
- Status rollback and resubmission capability
- Validation pass/fail logic (RDY→PAS or RDY→FAI)
- Clearance type-specific validation rules (FML requires CCN with CUS=CLR/AAC, TRS requires TRS number, DEM/LND/ABK require CAN or EDEC)

**Status Management:**
- New BCR status values: AAC (Amendment Accepted), ARJ (Amendment Rejected), AST (Amendment Sent), WRJ (Withdrawal Rejected), WST (Withdrawal Sent), WTD (Withdrawn), SYN (Syntax Error), UND (Undefined), FAI (Validation Failed)
- Corresponding MAN status values for shipment-level tracking
- Flow-level reference updates (BCRCLR, BCRERR) to reflect consolidated outcomes
- Master-to-shipment status synchronization (header-level rejection sets all shipments to REJ)

**Reference Number Management:**
- Sender Reference (URM) format: "MW" prefix + 33 characters (unique across Master Waybills and Declarations)
- Sender Reference Version (SRV) increment logic: cumulative across all message types (Original, Amendment, Withdrawal)
- Interchange Control Reference Number (IRN) sequencing: starts from 500 for Master Waybills (to differentiate from Shipment IRN which starts from 1)
- URM reflection from Master to Shipment after Original MSG-ESM sent
- Message Type Identifier (MTI) storage for CONTRL matching
- Removal of obsolete URN reference (parent type MW)

**User Interface Updates:**
- AU Rating List column change: "MAWB & SEQ" → "MAWB & SEQ & URM"
- Validation warnings displayed in popup (non-blocking, not stored in Shipment Comment FAI or Master Waybill Brokerage Events)
- Master-level validation failure popup (not stored in Master Waybill Brokerage Events)

**Message Analyzer Refactoring:**
- Refactor Message Analyzer to process BCR status changes based on MSG-ESMR responses
- Ensure MSG-ESMR messages update Master Waybill and Shipment statuses correctly
- Handle header-level and line-level status updates from customs

### Out of Scope

- Export Declaration Number (EDN) submission and processing (handled separately in export declaration workflows)
- Original MSG-ESM submission logic (already implemented in prior features)
- Import cargo reporting or declaration amendments
- Charge calculation or billing system integration (beyond suppression of duplicate charge files via UNS flag)
- Manual override of customs-assigned statuses
- Manual reporting via phone/email (system enforces electronic submission only)
- Amendments to manifests that were never successfully submitted (must submit Original MSG-ESM first)

---

## 4. Stakeholders and Actors

**Primary Users:**
- **Customs Brokers (BRK):** Initiate amendments and withdrawals by changing Master Waybill BCR status; review customs responses and resolve errors
- **Administrators (ADM):** Configure reference data for new status values; monitor message processing health; investigate CONTRL syntax errors
- **Compilers (COM):** Validate data completeness before brokers trigger amendments; correct validation failures

**Supporting Systems:**
- **TPS (Trade Processing System):** CBF's customs processing platform that receives MSG-ESM messages and returns MSG-ESMR responses
- **TCS (HAWB Management System):** Provides Master Waybill and shipment master data
- **BDIS (Brokerage Document Imaging System):** Stores supporting documents referenced in manifests
- **MSG-ESM (Enterprise Shipment Management):** Receives status updates for shipment visibility
- **MSG-CSA (Cargo Release System):** Blocks cargo release for withdrawn manifests
- **Billing System:** Generates invoices for cleared shipments; suppresses invoices for withdrawn shipments (UNS flag)

**Regulatory Authority:**
- **Customs Border Force (CBF):** Defines EDIFACT message standards, validation rules, and compliance requirements for MSG-ESM lifecycle

---

## 5. Dependencies

**Technical Prerequisites:**
- MSG-ESM Original message submission capability (previously implemented in Feature Part A)
- MSG-ESMR response processing for Original messages (previously implemented in Feature Part B-I and II)
- Master Waybill and Shipment data models extended with new reference fields (URM, SRV, IRN, MTI, DSQ, TRS, CCAN, EDEC)
- EDIFACT message construction and parsing engine for MSG-ESM and MSG-ESMR message types
- TPS gateway connectivity for secure message transmission

**Data Prerequisites:**
- Master Waybill must have existing URM (Unique Reference Number) from original MSG-ESM submission
- Shipments must have Declaration Reference Number DSQ assigned for line-level tracking
- Master Waybill must have valid Transport Type (A=Air, S=Sea) and Cargo Report Type (C=Consolidation, S=Single)
- For FML clearance type: Declaration Reference Number CCN must exist and CUS status must be CLR or AAC
- For TRS clearance type: Shipment Reference Number TRS must exist
- For ABK/DEM/LND clearance types: Either Shipment Reference Number CAN or Declaration Reference Number EDEC must exist

**Process Prerequisites:**
- Brokers must have completed original MSG-ESM submission (BCR status = SNT → CLR/ERR)
- Amendment scenarios require MAN status = PAS (Passed validation) on shipments to be included
- Withdrawal scenarios require BCR status = WID to be set explicitly by broker
- Shipment-level validation must be triggered by setting MAN status = RDY (Ready for validation)

**Reference Data:**
- New BCR and MAN status values configured in Admin > References > Brokerage Status Value
- New Declaration Reference Number URM configured in Admin > References > Declaration Ref Type (with parent type MW)
- Obsolete Reference Number URN (parent type MW) removed from Admin > References > Reference Number Type
- Sender Reference Version (SRV) numbering logic established for message versioning
- Error code mappings defined for MSG-ESMR error/advisory segments (ERP-ERC-FTX)
- Interchange Reference Number (IRN) sequencing starts from 500 for Master Waybills (to differentiate from Shipment IRN)

---

## 6. Success Criteria

**Functional Success:**
- Brokers can trigger MSG-ESM Amendment messages by setting Master Waybill BCR status to AMD
- Brokers can trigger MSG-ESM Withdrawal messages by setting Master Waybill BCR status to WID
- SBSS correctly increments Sender Reference Version (SRV) cumulatively for each amendment/withdrawal of the same manifest (across Original, Amendment, and Withdrawal message types)
- MSG-ESMR responses update BCR and MAN statuses according to customs approval/rejection
- Error details from MSG-ESMR are captured at appropriate levels (Master for header errors, Shipment for line errors via ESMRED)
- Flow-level references (BCRCLR, BCRERR) reflect consolidated manifest outcomes
- Withdrawn manifests do not generate duplicate charge files (UNS flag set)
- Shipment-level validation triggers correctly when MAN status is set to RDY
- Master-level validation triggers correctly when BCR status is set to AMD or WID
- URM is reflected from Master to Shipment after Original MSG-ESM sent
- AU Rating List displays "MAWB & SEQ & URM" column with correct formatting

**Compliance Success:**
- All outbound MSG-ESM Amendment/Withdrawal messages conform to TPS EDIFACT specifications
- Sender Reference Version increments correctly per TPS versioning rules (cumulative across Original/Amendment/Withdrawal, never resets)
- Line information is excluded from Function Code 50 (Withdrawal) messages
- CONTRL syntax error messages correctly map to Master Waybills via IRN matching (handling leading zero in UCI 0020 element)
- Sender Reference (URM) format uses "MW" prefix (not "AU" like declarations) to prevent duplication

**Operational Success:**
- Amendment processing time reduced from manual email-based corrections to automated message submission
- Error resolution time reduced through clear visibility of customs rejection reasons (ESMRED, ESMRSD references)
- Audit trail completeness: all amendments and withdrawals logged in Brokerage Events with status descriptions
- Zero instances of duplicate charge file generation for withdrawn manifests
- Validation warnings are non-blocking (shipment saves successfully, MAN=FAI indicates failure)
- Validation errors displayed in popup (not stored in comments/events)
- Message Analyzer correctly refactored to process MSG-ESMR responses

---

## 7. Assumptions and Risks

**Assumptions:**
- CBF TPS availability and response times remain within acceptable SLA thresholds
- Brokers receive adequate training on new BCR status codes and amendment/withdrawal workflows
- Existing Master Waybill and Shipment data quality is sufficient for accurate message construction
- EDIFACT message parser can handle all MSG-ESMR response variations (header-only errors, line-level errors, mixed statuses)
- Transport Type defaults to "A" (Air) if not populated when Master Waybill Origin Country is set to AU
- IRN sequencing starting from 500 for Master Waybills is sufficient to avoid collisions with Shipment IRN (which starts from 1)

**Risks:**

| Risk | Impact | Mitigation |
|------|--------|------------|
| MSG-ESMR response delays from TPS cause status synchronization lag | Medium | Implement asynchronous status polling; provide broker dashboard for pending responses |
| Data quality issues in shipments cause validation failures on amendment | High | Pre-validation warnings before BCR status change; detailed error reporting to guide corrections; non-blocking validation allows save |
| Sender Reference Version numbering collisions between concurrent users | Medium | Database-level locking on SRV increment; unique constraint enforcement |
| Customs rejects amendment but broker unaware of specific line-level failures | High | Line-level error mapping to shipment ESMRED references; visual indicators on Rating List |
| Withdrawal triggers downstream cargo release issues | Medium | Coordinate with MSG-CSA integration; ensure withdrawn manifests flag cargo as non-released |
| URM duplication between Master Waybills and Declarations | High | "MW" prefix for Master URM, "AU" prefix for Declaration URN; unique constraint validation |
| CONTRL IRN matching fails due to leading zero | Medium | Strip leading zero from CONTRL UCI 0020 element before matching to Master IRN |
| Validation failure details stored in comments clutter UI | Low | Display validation errors in popup only; remove storage in Shipment Comment FAI or Master Waybill Brokerage Events |
| Message Analyzer fails to process MSG-ESMR responses | High | Refactor Message Analyzer to correctly update BCR statuses; comprehensive testing |

**Constraints:**
- TPS message size limits (e.g., maximum lines per MSG-ESM message)
- EDIFACT syntax strictness requires exact segment sequencing and conditional element rules
- Sender Reference Version must never decrement or reset (cumulative across Original, Amendment, and Withdrawal for the same manifest)
- Withdrawal messages cannot include partial line data (all-or-nothing header-level operation)
- Clearance type-specific validation rules (FML requires CCN and CUS=CLR/AAC, TRS requires TRS number, ABK/DEM/LND require CAN or EDEC)
- CCAN (Contingency Customs Authority Number) must be exactly 14 characters when EDEC=EXCC

---

## 8. High-Level Process Flow

**Amendment Scenario:**
1. Broker identifies error in previously submitted MSG-ESM (e.g., incorrect commodity count, wrong HAWB reference)
2. Broker updates Master Waybill or Shipment data in SBSS
3. Broker sets Shipment MAN status to RDY (Ready for validation) to trigger shipment-level validation
4. SBSS validates shipment data (clearance type-specific checks: FML requires CCN with CUS=CLR/AAC, TRS requires TRS number, ABK/DEM/LND require CAN or EDEC, EXCC requires CCAN with 14 characters, shipper requires TIN/OID or Name)
5. If validation passes: SBSS sets MAN=PAS; if validation fails: SBSS sets MAN=FAI and displays warning popup (non-blocking, shipment saves successfully)
6. Broker corrects validation failures and retries RDY→PAS
7. Broker sets Master Waybill BCR status to AMD
8. SBSS validates Master-level data (CRN exists, URM exists, Origin Country=AU)
9. SBSS validates that at least one shipment has MAN=PAS (if none, set BCR=FAI and display popup)
10. If validation passes: SBSS increments SRV (cumulative across Original/Amendment/Withdrawal), constructs MSG-ESM with Function Code 5, submits to TPS, sets BCR=AST, sets shipment MAN=AST for included shipments
11. TPS processes amendment, returns MSG-ESMR
12. Message Analyzer parses MSG-ESMR: updates BCR (AAC/ARJ/ERR/RVK/CLR), syncs to MAN statuses, logs errors if rejected (Master-level errors in Brokerage Events, line-level errors in ESMRED)
13. SBSS updates Flow-level BCR status (BCRCLR if all lines cleared, BCRERR if any line errored)
14. Broker reviews outcome; if rejected, corrects data and resubmits (AMD→AST→AAC/ARJ/CLR/ERR cycle)

**Withdrawal Scenario:**
1. Broker determines manifest must be withdrawn (e.g., cargo cancelled, shipment removed from consolidation)
2. Broker sets Master Waybill BCR status to WID
3. SBSS validates withdrawal eligibility (Master must have URM from original submission, CRN exists, Origin Country=AU)
4. SBSS increments SRV (cumulative), constructs MSG-ESM with Function Code 50 (header only, no lines), submits to TPS, sets BCR=WST, sets all associated shipments' MAN=WST
5. TPS processes withdrawal, returns MSG-ESMR
6. Message Analyzer parses MSG-ESMR: updates BCR (WTD/WRJ), syncs to MAN statuses
7. If withdrawal accepted (WTD): SBSS sets UNS (Upload Not Sent) flag on all associated shipments to suppress charge file generation; notifies MSG-CSA to block cargo release
8. If withdrawal rejected (WRJ): Broker reviews rejection reason, corrects issue or contacts customs, re-initiates withdrawal (WID→WST→WTD/WRJ cycle)

**Syntax Error Scenario (CONTRL):**
1. SBSS submits MSG-ESM (Amendment or Withdrawal)
2. TPS returns CONTRL message with syntax errors
3. SBSS matches CONTRL to Master Waybill via IRN (stripping leading zero from CONTRL UCI 0020 element if present: e.g., 0123456 → 123456)
4. SBSS matches CONTRL to message type via MTI (CUSCAR for MSG-ESM)
5. SBSS sets BCR=SYN, stores syntax error details in Master Waybill Brokerage Events
6. Broker reviews error details, corrects syntax issue (e.g., segment sequencing, invalid element format)
7. Broker resubmits by setting BCR=AMD or WID again

---

## 9. Business Value

**Compliance Assurance:**
- Full lifecycle management of export manifests ensures regulatory adherence
- Reduced risk of penalties from CBF for uncorrected manifest errors
- Audit-ready record of all amendments and withdrawals with timestamps and status history
- TPS versioning compliance (SRV increments correctly, cumulative across all message types, never resets)

**Operational Efficiency:**
- Estimated 80% reduction in manual correction time (from hours to minutes per amendment)
- Automated status synchronization eliminates manual follow-up with customs
- Consolidated error reporting reduces broker troubleshooting effort (ESMRED, ESMRSD references)
- Non-blocking validation warnings allow brokers to save work-in-progress

**Customer Experience:**
- Faster resolution of export delays caused by manifest errors
- Proactive withdrawal capability prevents unnecessary customs holds on cancelled shipments
- Improved transparency: customers receive timely updates on manifest status changes
- Flow-level BCR status (BCRCLR, BCRERR) provides at-a-glance consolidated manifest status

**Cost Avoidance:**
- Prevents duplicate billing for withdrawn consolidated manifests (UNS flag)
- Reduces labor costs associated with manual error resolution
- Minimizes risk of fines from non-compliance with cargo reporting requirements
- Reduces TPS re-submission costs (correct errors before submission via validation)

---

## 10. Next Steps

1. **Technical Specification Development:** Detailed segment mapping, validation rules, and status transition logic
2. **Reference Data Configuration:** Create new BCR/MAN status values in Admin tables; configure URM Declaration Ref Type (parent type MW); remove obsolete URN reference (parent type MW)
3. **Development:** Implement message construction, submission triggers, MSG-ESMR parsing, status update logic, validation pass/fail logic (RDY→PAS/FAI), URM reflection, IRN sequencing (starts from 500), Message Analyzer refactoring
4. **Testing:** End-to-end scenarios covering amendments (approved/rejected/re-amended), withdrawals (accepted/rejected), syntax errors (CONTRL with leading zero), mixed line-level outcomes, clearance type-specific validations, URM reflection, AU Rating List display, Message Analyzer BCR status updates
5. **Training:** Broker training on new status codes, validation warnings (non-blocking, popup display), error resolution workflows, RDY→PAS validation triggers, URM reflection
6. **Deployment:** Staged rollout with monitoring of TPS response handling
7. **Post-Implementation Review:** Measure success against criteria (processing time, error rates, compliance audit outcomes)

---

title: Project-A - Export - Brokerage Cargo Reports (Manual and Automatic) - Part C (** IT Request) — Technical Specification
content: # Export Sub-Manifest Amendment and Withdrawal  
# Technical Specification

**Document Version:** 3.0  
**System:** SBSS (Brokerage Operations Support System)  
**Message Types:** MSG-ESM (Export Sub-Manifest), MSG-ESMR (MSG-ESM Response), CONTRL (Syntax Acknowledgment)  
**Regulatory Authority:** Customs Border Force (CBF) TPS  
**Standards:** UN/EDIFACT D.99B

---

## 1. Message Format and Segment Reference

This section provides a unified reference for all EDIFACT segments used across MSG-ESM Amendment, MSG-ESM Withdrawal, and MSG-ESMR response messages. Segments are organized by functional group, with detailed element specifications, data formats, conditional rules, and applicability across message types.

### 1.1 Segment Overview Table

| Segment | Segment Group | Amendment (FC=5) | Withdrawal (FC=50) | MSG-ESMR (Inbound) | Purpose |
|---------|---------------|------------------|--------------------|----------------|---------|
| UNH | Header | M | M | M | Message Header |
| BGM | Header | M | M | M | Beginning of Message |
| RFF | Header (SG2) | M | M | M | Reference Numbers |
| DTM | Header (SG2) | C | C | C | Date/Time |
| NAD | Header (SG3) | M | M | M | Party Identification |
| TDT | Header (SG5) | M | M | M | Transport Details |
| LOC | Header (SG5) | M | M | M | Location Information |
| CNT | Header (SG5) | M | M | C | Control Totals (Header) |
| CNI | Line (SG7) | M | **Excluded** | C | Consignment Line Number |
| RFF | Line (SG8) | M | **Excluded** | C | Line References |
| GID | Line (SG8) | C | **Excluded** | C | Goods Item Details |
| CNT | Line (SG7) | C | **Excluded** | C | Control Totals (Line) |
| ERP | Error (SG4) | N/A | N/A | C | Error Point Details |
| ERC | Error (SG4) | N/A | N/A | C | Error Code |
| FTX | Header/Line/Error | C | C | M | Free Text (Status/Errors) |
| CST | Line (MSG-ESMR) | N/A | N/A | C | Customs Status per Line |
| UNT | Trailer | M | M | M | Message Trailer |

**Legend:**
- **M** = Mandatory
- **C** = Conditional (based on data availability or message context)
- **N/A** = Not Applicable
- **FC** = Function Code (1225 - MESSAGE FUNCTION CODE in BGM segment)

---

### 1.2 Header Segments (Common to All Message Types)

#### UNH - Message Header

| Element | Name | Format | Amendment | Withdrawal | MSG-ESMR | Notes |
|---------|------|--------|-----------|------------|------|-------|
| 0062 | Message Reference Number | n..14 | M | M | M | Fixed value: `1` for outbound MSG-ESM; generated by customs for MSG-ESMR |
| S009 | Message Identifier | - | M | M | M | Composite element |
| 0065 | Message Type | a6 | M | M | M | `CUSCAR` for MSG-ESM outbound; `CUSRES` for MSG-ESMR inbound |
| 0052 | Version Number | an..3 | M | M | M | `D` |
| 0054 | Release Number | an..3 | M | M | M | `99B` |
| 0051 | Agency Code | an..2 | M | M | M | `UN` |

**Example:**
```
UNH+1+CUSCAR:D:99B:UN'
```

---

#### BGM - Beginning of Message

| Element | Name | Format | Amendment | Withdrawal | MSG-ESMR | Rules |
|---------|------|--------|-----------|------------|------|-------|
| C002 | Document/Message Name | - | M | M | M | Composite |
| 1001 | Document Name Code | an..3 | M | M | M | `85` for MSG-ESM outbound; `961` for MSG-ESMR inbound |
| 1131 | Code List Identifier | an..17 | C | C | C | `::MSG-ESMR` for MSG-ESMR; omit for MSG-ESM |
| 1004 | Sender Reference | an..35 | M | M | M | **Outbound:** Master Waybill>Miscellaneous>Reference Numbers>**URM** (format: `MW` + 33 chars, e.g., `MW3658...`). **Inbound:** Maps to URM for Master identification |
| 1225 | Message Function Code | an..3 | M | M | M | **Amendment:** `5` (Replace). **Withdrawal:** `50` (Withdrawal). **MSG-ESMR:** `11` (Response) |
| 1056 | Sender Reference Version | an..14 | M | M | M | **Outbound:** Incremented from Master Waybill>Miscellaneous>Reference Numbers>**SRV**. **Inbound:** Maps to SRV to identify message version |

**BGM Conditional Rules:**
- **1004 (Sender Reference):**
  - **Outbound MSG-ESM:** Generated as `MW` + last 33 characters of system-generated unique reference. Must not duplicate any existing URM (Master Waybills) or URN (Declarations). The "MW" prefix differentiates Master Waybill references from Declaration references (which use "AU" prefix).
  - **Inbound MSG-ESMR:** Extract from RFF+ABO segment (1154 - Sender Reference) to match Master Waybill.
- **1056 (Sender Reference Version):**
  - **Amendment:** SRV = SRV(previous) + 1. Stored in Master Waybill>Miscellaneous>Reference Numbers>SRV.
  - **Withdrawal:** SRV = SRV(previous) + 1 (cumulative across all message types for this Master).
  - **MSG-ESMR:** Extract from RFF+ABO (4000 - Sender Reference Version) to identify which MSG-ESM version the response corresponds to.
  - **Critical Note:** SRV is cumulative across Original (Function Code 9), Amendment (Function Code 5), and Withdrawal (Function Code 50) messages. Each message type increments the same SRV counter. SRV never resets or decrements. For example, if Original MSG-ESM has SRV=001, first Amendment will have SRV=002, and subsequent Withdrawal will have SRV=003.

**Example (Amendment):**
```
BGM+85+MW365812345678901234567890123456:5+002'
```
Where `002` is the Sender Reference Version (second version of this manifest, could be first amendment if original was version 001).

**Example (Withdrawal):**
```
BGM+85+MW365812345678901234567890123456:50+003'
```

**Example (MSG-ESMR):**
```
BGM+961:::MSG-ESMR+17HG8C48E3G4:001+11'
```

---

#### RFF - Reference (Segment Group 2: Header-Level References)

Multiple RFF segments may appear in SG2. Each serves a distinct reference purpose.

| Qualifier (1153) | Element 1154 Name | Format | Amendment | Withdrawal | MSG-ESMR | SBSS Mapping (Outbound) | Notes |
|------------------|-------------------|--------|-----------|------------|------|-------------------------|-------|
| **ABO** | Sender Reference | an..35 | N/A | N/A | M | N/A | **MSG-ESMR only:** Maps to Master>Miscellaneous>Reference Numbers>**URM** to identify Master Waybill |
| **ACW** | Customs Document Type | an..3 | N/A | N/A | M | N/A | **MSG-ESMR only:** Fixed value `MSG-ESM` |
| **AFM** | Message Function Code (Inbound) | an..3 | N/A | N/A | M | N/A | **MSG-ESMR only:** `5` (Amendment response), `50` (Withdrawal response), `9` (Original response). Used to route MSG-ESMR logic |
| **AIZ** | Customs Authority Number (CAN) | an..35 | N/A | N/A | C | N/A | **MSG-ESMR only:** Customs-assigned CAN if available |

**MSG-ESMR-Specific RFF Processing:**

**RFF+ABO Segment:**
- **Purpose:** Identifies which Master Waybill the MSG-ESMR corresponds to.
- **Matching Logic:**
  1. Extract `1154 - Sender Reference` from RFF+ABO.
  2. Match against Master Waybill>Miscellaneous>Reference Numbers>**URM**.
  3. Extract `4000 - Sender Reference Version` from RFF+ABO.
  4. Match against Master Waybill>Miscellaneous>Reference Numbers>**SRV** to identify specific message version.

**Example:**
```
RFF+ABO:MW365812345678901234567890123456::002'
```
Interpretation: This MSG-ESMR corresponds to Master with URM=`MW365812345678901234567890123456`, message version 002.

**RFF+AFM Segment:**
- **Purpose:** Indicates the function code of the MSG-ESM message being responded to.
- **Routing Logic:**
  - `5` → Apply Amendment MSG-ESMR processing (update BCR to AAC/ARJ/ERR/CLR/RVK, sync MAN statuses).
  - `50` → Apply Withdrawal MSG-ESMR processing (update BCR to WTD/WRJ, sync MAN statuses).
  - `9` → Original MSG-ESM response (handled in separate feature).

**Example:**
```
RFF+AFM:5'
```
Interpretation: This is a response to an Amendment MSG-ESM.

---

#### DTM - Date/Time (Segment Group 2)

| Element | Name | Format | Amendment | Withdrawal | MSG-ESMR | SBSS Mapping | Rules |
|---------|------|--------|-----------|------------|------|--------------|-------|
| C507 | Date/Time/Period | - | C | C | C | Composite | Conditional based on date availability |
| 2005 | Date/Time/Period Qualifier | an..3 | C | C | C | - | `182` = Estimated Departure Date |
| 2380 | Date/Time/Period Value | an..35 | C | C | C | Master Waybill>Master Waybill>Departure Details>**Departure Date** | Format: `CCYYMMDD` (e.g., `20240918`) |
| 2379 | Date/Time/Period Format Qualifier | an..3 | C | C | C | - | `102` (CCYYMMDD format) |

**Conditional Rule:**
- Include DTM segment only if Master Waybill>Master Waybill>Departure Details>**Departure Date** is populated.

**Example:**
```
DTM+182:20240918:102'
```

---

#### NAD - Name and Address (Segment Group 3: Party Identification)

NAD segments identify parties involved in the cargo movement. Multiple NAD segments may appear with different qualifiers.

##### NAD+MR (Message Recipient - Customs Authority)

| Element | Name | Format | Amendment | Withdrawal | MSG-ESMR | SBSS Mapping | Rules |
|---------|------|--------|-----------|------------|------|--------------|-------|
| 3035 | Party Qualifier | an..3 | M | M | M | - | Fixed: `MR` |
| C082 | Party Identification Details | - | M | M | M | Composite | - |
| 3039 | Party ID | an..35 | M | M | M | - | Fixed: `83003926181` (CBF TPS identifier) |
| 3055 | Code List Responsible Agency | an..3 | M | M | M | - | Fixed: `95` (UN/EDIFACT agency code for customs) |

**Example:**
```
NAD+MR+83003926181::95'
```

##### NAD+GO (Goods Owner - Shipper/Exporter)

| Element | Name | Format | Amendment | Withdrawal | MSG-ESMR | SBSS Mapping | Rules |
|---------|------|--------|-----------|------------|------|--------------|-------|
| 3035 | Party Qualifier | an..3 | M | M | M | - | Fixed: `GO` |
| C082 | Party Identification Details | - | C | C | N/A | Composite | Include if TIN or OID available |
| 3039 | Goods Owner Party ID | an..35 | C | C | N/A | Declaration>Customer>**Shipper**>Reference Numbers>**TIN** (if available); else **OID** | Conditional: include element 3055 only if 3039 is populated |
| 3055 | Code List Responsible Agency | an..3 | C | C | N/A | - | Fixed: `95` (only if 3039 included) |
| C058 | Name and Address | - | C | C | N/A | Composite | Include if Shipper Name available |
| 3036 | Owner Name | an..35 | C | C | N/A | Declaration>Customer>**Shipper**>**Shipper Name** | **Critical: Exclude 3055 if 3036 is used** |

**NAD+GO Conditional Logic:**
1. **If TIN or OID is available:**
   ```
   NAD+GO+AAA3437936M::95'
   ```
   (3039 = TIN/OID, 3055 = `95`)

2. **If TIN/OID is not available but Shipper Name is:**
   ```
   NAD+GO+++BUSH BARRIER'
   ```
   (3036 = Shipper Name, **3055 excluded**)

3. **If neither TIN/OID nor Shipper Name is available:**
   - **Validation Failure:** Raise warning "TIN/OEM Client ID or Shipper Name is required for MSG-ESM message."

**NAD+GO Structure Critical Rule:**
- Element 3055 (Code List Responsible Agency = `95`) is **only** included when element 3039 (Goods Owner Party ID) is populated.
- When element 3036 (Owner Name) is used, element 3055 **must be excluded**.
- This ensures EDIFACT syntax compliance: 3055 qualifies 3039, not 3036.

---

#### TDT - Transport Details (Segment Group 5)

| Element | Name | Format | Amendment | Withdrawal | MSG-ESMR | SBSS Mapping | Rules |
|---------|------|--------|-----------|------------|------|--------------|-------|
| 8051 | Transport Stage Qualifier | an..3 | M | M | M | - | Fixed: `1` (Pre-carriage) |
| 8028 | Conveyance Reference Number | an..17 | M | M | M | Master Waybill>Master Waybill>**Flight/Vessel Number** | - |
| C220 | Mode of Transport | - | M | M | M | Composite | - |
| 8067 | Transport Mode Name Code | an..3 | M | M | M | - | Fixed: `31` (Inland water transport) |
| 8179 | Mode of Transport | an..3 | M | M | M | Master Waybill>Master Waybill>**Transport Type** | **Conversion rule:** `A` → `6` (Air), `S` → `11` (Sea) |

**Transport Type Conversion Logic:**
- If Master Waybill>Master Waybill>**Transport Type** = `A`, insert `6` in element 8179.
- If Master Waybill>Master Waybill>**Transport Type** = `S`, insert `11` in element 8179.
- If Transport Type is missing, apply default `A` (Air) → `6`.

**Transport Type Default Assignment:**
- **Trigger:** When Master Waybill>Master Waybill>Export/Import Information>**Origin Country** is set to `AU` (on load or save).
- **Logic:** If Master Waybill>Master Waybill>**Transport Type** is empty, assign default value `A` (Air) from system side.
- **Storage:** Master Waybill>Master Waybill>**Transport Type** = `A`.

**Example (Air):**
```
TDT+1+CX138+31:6'
```

**Example (Sea):**
```
TDT+1+VESSEL123+31:11'
```

---

#### LOC - Location (Segment Group 5)

| Element | Name | Format | Amendment | Withdrawal | MSG-ESMR | SBSS Mapping | Rules |
|---------|------|--------|-----------|------------|------|--------------|-------|
| 3227 | Location Qualifier | an..3 | M | M | M | - | `60` = Port of Discharge (Departure Port) |
| C517 | Location Identification | - | M | M | M | Composite | - |
| 3225 | Location Name Code | an..35 | M | M | M | Master Waybill>Export/Import Information>**Port of Departure** | UN/LOCODE format (e.g., `AUSYD` for Sydney) |
| 3055 | Code List Responsible Agency | an..3 | M | M | M | - | Fixed: `139` (UN/LOCODE authority) |

**Example:**
```
LOC+60+AUSYD::139'
```

---

#### CNT - Control Total (Segment Group 5: Header-Level Totals)

CNT segments at the header level provide summary counts of packages and containers across the entire manifest. Multiple CNT segments with different qualifiers may appear.

| Element | Name | Format | Amendment | Withdrawal | MSG-ESMR | SBSS Mapping | Rules |
|---------|------|--------|-----------|------------|------|--------------|-------|
| C270 | Control | - | M | M | C | Composite | - |
| 6069 | Control Total Type Qualifier | an..3 | M | M | C | - | `11` = Total Packages, `36` = Total Containers |
| 6066 | Control Total Quantity | n..18 | M | M | C | - | Summarized from line-level CNT totals (see Line CNT section) |

**CNT Calculation Logic (Outbound MSG-ESM Amendment):**

1. **CNT+11 (Total Packages):**
   - Iterate through all shipments included in the MSG-ESM message (MAN status = PAS).
   - For each shipment, extract `6066 - Number of Packages` from line-level CNT+11 (Segment Group 7).
   - Sum all line-level package counts.
   - Insert total into header-level CNT+11.

2. **CNT+36 (Total Containers):**
   - Iterate through all shipments included in the MSG-ESM message.
   - For each shipment, extract `6066 - Number of Containers` from line-level CNT+36 (Segment Group 7).
   - Sum all line-level container counts.
   - Insert total into header-level CNT+36.

**Example:**
```
CNT+11:17'     (17 total packages across all lines)
CNT+36:2'      (2 total containers across all lines)
```

**MSG-ESMR Inbound:**
- CNT segments in MSG-ESMR are optional and informational. Do not process for status updates.

---

### 1.3 Line Segments (Segment Group 7 and 8: Consignment Details)

**CRITICAL:** Line segments are **EXCLUDED** from Withdrawal messages (Function Code 50). Only Amendment (Function Code 5) and MSG-ESMR include line-level data.

#### CNI - Consignment Line Number (Segment Group 7)

| Element | Name | Format | Amendment | Withdrawal | MSG-ESMR | SBSS Mapping | Rules |
|---------|------|--------|-----------|------------|------|--------------|-------|
| 1490 | Line Number | n..6 | M | **Excluded** | C | Declaration>Customs>Reference Numbers>**DSQ** (Declaration Sequence) | Sequential line number (e.g., `000001`, `000002`). **Updated Mapping:** DSQ replaces previous SEQ mapping. |

**CNI Processing Logic (Outbound Amendment):**

1. Map the following data to define the association between Master and Shipments:
   - Master Waybill>**Number** (with BCR Status = AMD)
   - Shipment>Master Waybill>**Number**
2. Fetch Declaration>Customs>Reference Numbers>**DSQ** from all shipments associated with the Master where MAN status = PAS.
3. Insert DSQ as the value of CNI element 1490 (Line Number).
4. Sequence must be zero-padded to 6 digits (e.g., `1` → `000001`).

**Example:**
```
CNI+000001'
CNI+000002'
...
CNI+000017'
```

**MSG-ESMR Inbound (Line-Level Status):**

In MSG-ESMR, CST (Customs Status) segment maps Line Number to shipment:
```
CST+000001'
FTX+AHN+++CLEAR'
```
- **Matching Logic:** Extract `1496 - Line Number` from CST segment. Map to shipment where Declaration>Customs>Reference Numbers>**DSQ** matches (e.g., `000001` → DSQ = `1`).
- **Status Update:** Apply line-level status from FTX+AHN to matched shipment's MAN status.

**Mapping Change Note:**
- **Previous Mapping:** Declaration>Customs>Reference Numbers>**SEQ** (Sequence Number).
- **Updated Mapping:** Declaration>Customs>Reference Numbers>**DSQ** (Declaration Sequence).
- **Rationale:** DSQ is the correct field for line-level tracking per TPS requirements.

---

#### RFF - Reference (Segment Group 8: Line-Level References)

Line-level RFF segments provide shipment-specific references. Multiple RFF segments appear per line, each with a distinct qualifier.

| Qualifier (1153) | Element 1154 Name | Format | Amendment | Withdrawal | MSG-ESMR | SBSS Mapping (Outbound) | Conditional Rules |
|------------------|-------------------|--------|-----------|------------|------|-------------------------|-------------------|
| **TL** | Export Declaration Exemption Code | an..35 | C | **Excluded** | C | Declaration>Customs>Reference Numbers>**EDEC** | **Mandatory** if CT ≠ TRS and EDEC is populated. Common values: `EXLV` (Low Value Export), `EXPE` (Personal Effects), `EXCC` (Contingency). |
| **TN** | Customs Authority Number | an..35 | C | **Excluded** | C | **If CT=FML:** Declaration>Customs>Reference Numbers>**CCN**. **If CT=TRS:** Shipment>Summary>Reference Numbers>**TRS**. **Else:** Shipment>Summary>Reference Numbers>**CAN**. | **Mandatory** for CT=FML (CCN must exist). **Mandatory** for CT=TRS (TRS number required). **Conditional** for other CT: either CAN or EDEC must be present. **Critical: Exclude RFF+TN segment (not include with empty value) if CAN not populated for DEM/LND.** |
| **HWB** | House Waybill Number | an..35 | M | **Excluded** | C | Shipment>Master Waybill>**House Waybill** | Always mandatory for line-level identification. |
| **AHV** | Contingency Customs Authority Number | an..35 | C | **Excluded** | C | Shipment>Summary>Reference Numbers>**CCAN** | **Mandatory** only if EDEC = `EXCC` (Contingency). Must be 14 characters if included. |

**RFF Segment Conditional Logic:**

1. **RFF+TL (Export Declaration Exemption Code):**
   - **Include if:** Declaration>Customs>Reference Numbers>**EDEC** is populated AND Clearance Type (CT) ≠ TRS.
   - **Validation:** If CT ∈ {ABK, DEM, LND, FML} and neither EDEC nor CAN is populated, raise warning: "Either Customer Authority Number or Export Declaration Exemption Code is required for MSG-ESM message."

2. **RFF+TN (Customs Authority Number):**
   - **If CT = FML:**
     - Map to Declaration>Customs>Reference Numbers>**CCN**.
     - **Validation:** CCN must exist (already enforced in trigger conditions for FML: CUS status must be CLR or AAC, which implies CCN exists).
   - **If CT = TRS:**
     - Map to Shipment>Summary>Reference Numbers>**TRS**.
     - **Validation:** If TRS is missing, raise warning: "TRS number is required for Transhipment."
   - **Else (CT ∈ {ABK, DEM, LND}):**
     - Map to Shipment>Summary>Reference Numbers>**CAN**.
     - **Validation:** If both CAN and EDEC are missing, raise warning: "Either Customer Authority Number or Export Declaration Exemption Code is required for MSG-ESM message."
     - **Critical Rule:** If CAN is not populated, **exclude RFF+TN segment entirely** (do not include segment with empty value). Incorrect structure example: `RFF+TN'` (no value). Correct structure when CAN not populated: Omit RFF+TN segment.

3. **RFF+HWB (House Waybill Number):**
   - Always mandatory. No conditional logic.

4. **RFF+AHV (Contingency Customs Authority Number):**
   - **Include if:** EDEC = `EXCC`.
   - **Validation:** If EDEC = `EXCC` and CCAN is missing, raise warning: "Contingency Customs Authority Number is required when Export Declaration Exemption Code is EXCC."
   - **Validation:** If EDEC = `EXCC` and CCAN length ≠ 14, raise warning: "Contingency Customs Authority Number must be 14 characters."

**RFF Segment Structural Rule (GID+1 Insertion):**

When multiple RFF segments repeat for the same line, insert `GID+1'` between distinct RFF groups:

**Example:**
```
RFF+TL:EXLV'
GID+1'
RFF+HWB:1ZAA00356793546561'
```

**Rationale:** TPS specification requires GID separator for clarity when multiple reference types appear for a single line.

**Critical Note on RFF Structure for DEM/LND:**
- When CT = DEM or LND, and CAN is not populated, **exclude RFF+TN segment entirely** (do not include with empty value).
- Example of incorrect structure: `RFF+TN'` (no value).
- Example of correct structure (CAN populated): `RFF+TN:CAN123456'`.
- Example of correct structure (CAN not populated): Exclude RFF+TN segment entirely.

---

#### GID - Goods Item Details (Segment Group 8)

| Element | Name | Format | Amendment | Withdrawal | MSG-ESMR | SBSS Mapping | Conditional Rules |
|---------|------|--------|-----------|------------|------|--------------|-------------------|
| 1496 | Goods Item Number | n..5 | C | **Excluded** | C | - | Fixed value: `1` (single goods item per line). **Include only if:** EDEC = `EXPE` (Personal Effects) OR EDEC = `EXLV` (Low Value Export). |

**GID Conditional Logic:**

- **Trigger Condition:** Segment Group 14 (GID-FTX) should only be included when Declaration>Customs>Reference Numbers>**EDEC** = `EXPE` OR `EXLV`.
- **If EDEC ∉ {EXPE, EXLV}:** Exclude GID segment entirely.

**Example (EDEC = EXLV):**
```
GID+1'
```

**Example (EDEC = EXCC):**
```
(No GID segment)
```

**GID+1 Insertion Logic (Between RFF Segments):**
- When RFF segments repeat within Segment Group 8 (e.g., RFF+TL followed by RFF+HWB), insert `GID+1'` between them.
- This applies regardless of EDEC value (i.e., GID+1 is inserted for structural clarity even if Segment Group 14 GID is not required).
- Example:
  ```
  RFF+TL:EXLV'
  GID+1'
  RFF+HWB:1ZAA00356793546561'
  ```

---

#### CNT - Control Total (Segment Group 7: Line-Level Totals)

Line-level CNT segments provide per-shipment package and container counts. These are aggregated into header-level CNT totals.

| Element | Name | Format | Amendment | Withdrawal | MSG-ESMR | SBSS Mapping | Rules |
|---------|------|--------|-----------|------------|------|--------------|-------|
| C270 | Control | - | C | **Excluded** | C | Composite | - |
| 6069 | Control Total Type Qualifier | an..3 | C | **Excluded** | C | - | `11` = Number of Packages, `36` = Number of Containers |
| 6066 | Control Total Quantity | n..18 | C | **Excluded** | C | Shipment-level package/container count | Extracted from shipment data |

**Line-Level CNT Population (Outbound Amendment):**

1. **CNT+11 (Packages per Line):**
   - Extract package count from shipment record.
   - Insert into CNT+11 for that line.

2. **CNT+36 (Containers per Line):**
   - Extract container count from shipment record.
   - Insert into CNT+36 for that line (if containers are used).

**Example:**
```
CNI+000001'
CNT+11:1'       (1 package for this line)
CNT+36:0'       (0 containers for this line)
```

**Aggregation to Header CNT:**
- Sum all line-level CNT+11 values → Header CNT+11.
- Sum all line-level CNT+36 values → Header CNT+36.

---

### 1.4 Error/Advisory Segments (MSG-ESMR Only: Segment Group 4)

Error segments appear in MSG-ESMR responses when validation fails or customs requires additional information. Segment Group 4 (ERP-ERC-FTX) is repeated for each error.

#### ERP - Error Point Details

| Element | Name | Format | Amendment | Withdrawal | MSG-ESMR | Processing Logic |
|---------|------|--------|-----------|------------|------|------------------|
| C701 | Error Point Details | - | N/A | N/A | C | Composite |
| 1049 | Error Segment Tag | an..3 | N/A | N/A | C | Identifies which segment the error pertains to (not currently processed in SBSS) |
| 1052 | Error Segment Number | n..6 | N/A | N/A | C | Not processed |
| 1054 | Error Location | an..6 | N/A | N/A | C | **Key field:** `0000` = Header-level error, `0001`-`9999` = Line number where error occurred |

**ERP Processing Logic:**

1. **Extract 1054 - Error Location:**
   - **If 1054 = `0000`:** Error is at **Master Waybill level** (header error).
     - Update Master Waybill>Brokerage Status>BCR based on Header FTX+AHN status.
     - Sync MAN status to all associated shipments (e.g., if Header Status = REJECTED, set all MAN = REJ).
     - Store error description from FTX+AAO in Master Waybill>Miscellaneous>Brokerage Events.
   - **If 1054 ≠ `0000`:** Error is at **Shipment level** (line error).
     - Map Error Location to Declaration>Customs>Reference Numbers>**DSQ** (e.g., `0178` → DSQ = `178`).
     - Store error identifier (from ERC segment) in Shipment>Summary>Customer Supplied References>**ESMRED**>Number.
     - Store error description (from FTX+AAO) in **ESMRED**>Comment.

**Example (Header-Level Error):**
```
ERP+::0000'
ERC+XM1016::95'
FTX+AAO+++EXPORT DOCUMENT STATUS IS ERROR BECAUSE A SUB-MANIFEST REPORT WITH A CARGO REPORT TYPE OF C (CONSOLIDATION) HAS NO LINES'
```
**Interpretation:**
- Error Location = `0000` → Master-level error.
- Error Code XM1016 → Consolidation report missing lines.
- Store error text in Master Waybill>Miscellaneous>Brokerage Events.

**Example (Line-Level Error):**
```
ERP+::0169'
ERC+XM1024::95'
FTX+AAO+++LINENUM=000000000000169 IS TRYING TO QUOTE EDN=AFENRN3NW THAT HAS ALREADY BEEN TALLY EXPIRED'
```
**Interpretation:**
- Error Location = `0169` → Line 169 (shipment with DSQ = `169`).
- Error Code XM1024 → EDN already expired.
- Store error in shipment's ESMRED reference.

---

#### ERC - Application Error Details

| Element | Name | Format | Amendment | Withdrawal | MSG-ESMR | Processing Logic |
|---------|------|--------|-----------|------------|------|------------------|
| C901 | Application Error Detail | - | N/A | N/A | C | Composite |
| 9321 | Error Identifier | an..35 | N/A | N/A | C | Customs error code (e.g., `XM1016`, `XM1024`) |
| 3055 | Code List Responsible Agency | an..3 | N/A | N/A | C | Fixed: `95` (customs authority) |

**ERC Processing:**
- **If Header-Level Error:** Store 9321 in Master Waybill>Miscellaneous>Brokerage Events (along with FTX description).
- **If Line-Level Error:** Store 9321 in Shipment>Summary>Customer Supplied References>**ESMRED**>Number.

---

#### FTX - Free Text (Status and Error Descriptions)

FTX segments appear in three contexts:
1. **Header Section (FTX+AHN):** Overall manifest status.
2. **Line Section (FTX+AHN):** Per-shipment status.
3. **Error Section (FTX+AAO):** Detailed error descriptions (paired with ERP/ERC).

##### FTX+AHN (Header Section - Master Status)

| Element | Name | Format | Amendment | Withdrawal | MSG-ESMR | Processing Logic |
|---------|------|--------|-----------|------------|------|------------------|
| 4451 | Text Subject Qualifier | an..3 | N/A | N/A | M | Fixed: `AHN` (Additional Information) |
| C108 | Text Literal | - | N/A | N/A | M | Composite |
| 4440 | Status Type | an..512 | N/A | N/A | M | **Amendment:** `CLEAR`, `ERROR`, `REJECTED`, `REVOKED`. **Withdrawal:** `REJECTED`, `WITHDRAWN`. |
| 4440 | Status Description | an..512 | N/A | N/A | C | Full-text explanation (e.g., "THE GOODS COVERED BY THE DOCUMENT ARE AUTHORISED FOR EXPORT...") |

**FTX+AHN Header Processing (Amendment MSG-ESMR):**

1. **Extract 4440 - Status Type** (first occurrence in C108).
2. **Update Master Waybill>Brokerage Status>BCR:**
   - `CLEAR` → BCR = **CLR**
   - `ERROR` (including `ERROR - VALIDATION`, `ERROR - SUSPENDED`, `ERROR - EMBARGOED`, `ERROR - EXPIRED`, etc.) → BCR = **ERR**
   - `REJECTED` → BCR = **REJ**
   - `REVOKED` → BCR = **RVK**
3. **Store Status Type : Status Description** in Master Waybill>Miscellaneous>Brokerage Events.
   - **Critical:** Store the **entire** Status Type including suffix (e.g., `ERROR - VALIDATION`, not just `ERROR`).
4. **Sync MAN Status to Associated Shipments:**
   - If Header Status = `REJECTED`, update all shipments' MAN status to **REJ**.

**Example (Amendment Approved):**
```
FTX+AHN+++CLEAR:THE GOODS COVERED BY THE DOCUMENT ARE AUTHORISED FOR EXPORT AND MAY BE DEALT WITH.'
```
**Processing:**
- BCR = **CLR**
- Store "CLEAR: THE GOODS COVERED..." in Brokerage Events.

**Example (Amendment with Error):**
```
FTX+AHN+++ERROR - VALIDATION:THE GOODS COVERED BY THE DOCUMENT CANNOT BE DEALT WITH. CUSTOMS DOES NOT EXPECT FURTHER QUOTATION OF THE RELATED CAN. THE LODGED OR AMENDED INFORMATION HAS NOT PASSED THE REQUIRED EDITS.'
```
**Processing:**
- BCR = **ERR**
- Store "ERROR - VALIDATION: THE GOODS COVERED..." in Brokerage Events (include full suffix).

---

**FTX+AHN Header Processing (Withdrawal MSG-ESMR):**

1. **Extract 4440 - Status Type**.
2. **Update Master Waybill>Brokerage Status>BCR:**
   - `REJECTED` → BCR = **WRJ** (Withdrawal Rejected)
   - `WITHDRAWN` → BCR = **WTD** (Withdrawn)
3. **Store Status Type : Status Description** in Master Waybill>Miscellaneous>Brokerage Events.
4. **Sync MAN Status to Associated Shipments:**
   - If `REJECTED`, update all shipments' MAN = **WRJ**.
   - If `WITHDRAWN`, update all shipments' MAN = **WTD**.

**Example (Withdrawal Accepted):**
```
FTX+AHN+++WITHDRAWN:THE EXPORT DECLARATION OR CARGO REPORT HAS BEEN WITHDRAWN BY THE REPORTING PARTY AND MAY NOT BE DEALT WITH.'
```
**Processing:**
- BCR = **WTD**
- MAN (all shipments) = **WTD**

---

##### FTX+AHN (Line Section - Shipment Status)

Line-level FTX+AHN appears after CST segment, providing status for individual shipments.

**FTX+AHN Line Processing (Amendment MSG-ESMR):**

1. **Extract CST element 1496 - Line Number** to identify shipment (map to DSQ).
2. **Extract 4440 - Line Status Type** from FTX+AHN.
3. **Update Shipment MAN Status:**
   - `CLEAR` → MAN = **CLR**
   - `ERROR` (including `ERROR - EXPIRED`, `ERROR - VALIDATION`, etc.) → MAN = **ERR**
4. **Store Line Status Type : Line Status Description** in Shipment>Summary>Customer Supplied References>**ESMRSD**>Number and Comment.
   - **Critical:** Store the **entire** Status Type including suffix (e.g., `ERROR - EXPIRED`, not just `ERROR`).
5. **Update Flow-Level BCR Status:**
   - Map Shipment>Flow>Reference Numbers>**MWB** to Master Waybill>**Number**.
   - If Line Status = `CLEAR`, add Reference Number **BCRCLR** to Flow.
   - If Line Status = `ERROR`, add Reference Number **BCRERR** to Flow.

**Example (Line Cleared):**
```
CST+0001'
FTX+AHN+++CLEAR'
```
**Processing:**
- Match DSQ = `1` → Shipment identified.
- MAN = **CLR**
- Add BCRCLR to Flow.
- Store "CLEAR" in ESMRSD>Number.

**Example (Line Error):**
```
CST+0169'
FTX+AHN+++ERROR - EXPIRED:LINENUM=000000000000169 IS TRYING TO QUOTE EDN=AFENRN3NW THAT HAS ALREADY BEEN TALLY EXPIRED'
```
**Processing:**
- Match DSQ = `169` → Shipment identified.
- MAN = **ERR**
- Add BCRERR to Flow.
- Store "ERROR - EXPIRED: LINENUM=000000000000169..." in ESMRSD>Number and Comment (include full suffix).

---

##### FTX+AAO (Error Description - Paired with ERP/ERC)

FTX+AAO provides detailed error descriptions when ERP/ERC segments are present.

**FTX+AAO Processing:**

1. **Determine Error Level** (from ERP element 1054):
   - **0000:** Master-level → Store in Master Waybill>Miscellaneous>Brokerage Events.
   - **Other:** Shipment-level → Store in ESMRED>Comment of matched shipment.
2. **Extract 4440 - Error Description** from FTX+AAO.
3. **Storage:**
   - **Master-level:** Append to Brokerage Events as "Error Code: Description".
   - **Shipment-level:** Store in ESMRED>Comment.

**Example (Master-Level):**
```
ERP+::0000'
ERC+XM1016::95'
FTX+AAO+++EXPORT DOCUMENT STATUS IS ERROR BECAUSE A SUB-MANIFEST REPORT WITH A CARGO REPORT TYPE OF C (CONSOLIDATION) HAS NO LINES'
```
**Storage:**
- Master Waybill>Miscellaneous>Brokerage Events: "XM1016: EXPORT DOCUMENT STATUS IS ERROR..."

**Example (Shipment-Level):**
```
ERP+::0169'
ERC+XM1024::95'
FTX+AAO+++LINENUM=000000000000169 IS TRYING TO QUOTE EDN=AFENRN3NW THAT HAS ALREADY BEEN TALLY EXPIRED'
```
**Storage:**
- Shipment (DSQ=169)>Summary>Customer Supplied References>ESMRED>Number: `XM1024`
- ESMRED>Comment: "LINENUM=000000000000169 IS TRYING TO QUOTE EDN=AFENRN3NW..."

---

#### CST - Customs Status (MSG-ESMR Line Section)

CST segment in MSG-ESMR identifies the line number for subsequent line-level status (FTX+AHN).

| Element | Name | Format | Amendment | Withdrawal | MSG-ESMR | Processing Logic |
|---------|------|--------|-----------|------------|------|------------------|
| 1496 | Line Number | n..6 | N/A | N/A | C | Maps to shipment via Declaration>Customs>Reference Numbers>**DSQ**. Zero-padded (e.g., `0001` → DSQ = `1`). |

**CST Processing:**

1. **Extract 1496 - Line Number.**
2. **Convert to integer** (strip leading zeros: `0001` → `1`).
3. **Match to shipment:** Find shipment where DSQ = extracted integer.
4. **Apply subsequent FTX+AHN status** to matched shipment.

---

### 1.5 Message Trailer Segments

#### UNT - Message Trailer

| Element | Name | Format | Amendment | Withdrawal | MSG-ESMR | Rules |
|---------|------|--------|-----------|------------|------|-------|
| 0074 | Number of Segments | n..6 | M | M | M | Total count of segments in message (including UNH and UNT) |
| 0062 | Message Reference Number | n..14 | M | M | M | Must match UNH element 0062 (value `1` for outbound MSG-ESM) |

**Example:**
```
UNT+78+1'
```
(78 segments total in message)

---

## 2. Data Mapping Rules

This section defines all field mappings between SBSS entities and EDIFACT message elements. Mappings are organized by **data domain** (Master Waybill data, Shipment data, Declaration data, etc.), NOT by message type or scenario.

### 2.1 Master Waybill Data Mappings

| EDIFACT Segment | Element | SBSS Source Field | Direction | Data Type | Transformation Rules | Applicability |
|-----------------|---------|-------------------|-----------|-----------|----------------------|---------------|
| BGM | 1004 - Sender Reference | Master Waybill>Miscellaneous>Reference Numbers>**URM** | Outbound | an..35 | Generate as `MW` + 33 chars unique reference. Must not duplicate any Declaration URN or Master URM. | Amendment, Withdrawal |
| BGM | 1056 - Sender Reference Version | Master Waybill>Miscellaneous>Reference Numbers>**SRV** | Outbound | an..14 | Increment from previous SRV by 1. **Cumulative** across Original (FC=9), Amendment (FC=5), and Withdrawal (FC=50) messages. | Amendment, Withdrawal |
| RFF+ABO | 1154 - Sender Reference | Master Waybill>Miscellaneous>Reference Numbers>**URM** | Inbound | an..35 | Match MSG-ESMR to Master by URM. | MSG-ESMR |
| RFF+ABO | 4000 - Sender Reference Version | Master Waybill>Miscellaneous>Reference Numbers>**SRV** | Inbound | an..14 | Match MSG-ESMR to specific MSG-ESM version by SRV. | MSG-ESMR |
| DTM+182 | 2380 - Date/Time/Period Value | Master Waybill>Master Waybill>Departure Details>**Departure Date** | Outbound | an..35 (CCYYMMDD) | Format as `CCYYMMDD` (e.g., `20240918`). Conditional: omit DTM if null. | Amendment, Withdrawal |
| TDT | 8028 - Conveyance Reference Number | Master Waybill>Master Waybill>**Flight/Vessel Number** | Outbound | an..17 | No transformation. | Amendment, Withdrawal |
| TDT | 8179 - Mode of Transport | Master Waybill>Master Waybill>**Transport Type** | Outbound | an..3 | **Convert:** `A` → `6` (Air), `S` → `11` (Sea). Default: if null, assume `A` → `6`. | Amendment, Withdrawal |
| LOC+60 | 3225 - Location Name Code | Master Waybill>Export/Import Information>**Port of Departure** | Outbound | an..35 | UN/LOCODE format (e.g., `AUSYD`). | Amendment, Withdrawal |
| FTX+AHN (Header) | 4440 - Status Type | Master Waybill>Brokerage Status>**BCR** | Inbound | an..512 | **Map:** `CLEAR` → BCR=CLR, `ERROR` (including all ERROR variants) → BCR=ERR, `REJECTED` → BCR=REJ (Amendment) / BCR=WRJ (Withdrawal), `WITHDRAWN` → BCR=WTD, `REVOKED` → BCR=RVK. Store entire status type including suffix (e.g., `ERROR - VALIDATION`). | MSG-ESMR |
| FTX+AHN (Header) | 4440 - Status Description | Master Waybill>Miscellaneous>**Brokerage Events** | Inbound | an..512 | Store as "Status Type: Status Description". Include full suffix (e.g., `ERROR - VALIDATION`). | MSG-ESMR |
| ERP-ERC-FTX (Header) | 9321 - Error Identifier, 4440 - Error Description | Master Waybill>Miscellaneous>**Brokerage Events** | Inbound | an..35, an..512 | Store as "Error Code: Error Description". Only if ERP location = `0000`. | MSG-ESMR |

---

### 2.2 Shipment Data Mappings

| EDIFACT Segment | Element | SBSS Source Field | Direction | Data Type | Transformation Rules | Applicability |
|-----------------|---------|-------------------|-----------|-----------|----------------------|---------------|
| CNI | 1490 - Line Number | Declaration>Customs>Reference Numbers>**DSQ** | Outbound | n..6 | Zero-pad to 6 digits (e.g., `1` → `000001`). Sequence assigned from DSQ. **Updated mapping** (previously SEQ). | Amendment |
| RFF+HWB | 1154 - House Waybill Number | Shipment>Master Waybill>**House Waybill** | Outbound | an..35 | No transformation. | Amendment |
| RFF+TN (CT=FML) | 1154 - Customs Authority Number | Declaration>Customs>Reference Numbers>**CCN** | Outbound | an..35 | No transformation. Mandatory for FML clearance type. | Amendment |
| RFF+TN (CT=TRS) | 1154 - Customs Authority Number | Shipment>Summary>Reference Numbers>**TRS** | Outbound | an..35 | No transformation. Mandatory for TRS clearance type. | Amendment |
| RFF+TN (CT≠FML, TRS) | 1154 - Customs Authority Number | Shipment>Summary>Reference Numbers>**CAN** | Outbound | an..35 | Conditional: include if CAN exists OR EDEC exists. **Critical: Exclude RFF+TN segment (not include with empty value) if CAN not populated for DEM/LND.** | Amendment |
| RFF+TL | 1154 - Export Declaration Exemption Code | Declaration>Customs>Reference Numbers>**EDEC** | Outbound | an..35 | Conditional: include if CT ≠ TRS and EDEC exists. Common values: EXLV, EXPE, EXCC. | Amendment |
| RFF+AHV | 1154 - Contingency Customs Authority Number | Shipment>Summary>Reference Numbers>**CCAN** | Outbound | an..35 | Conditional: mandatory if EDEC=EXCC. Must be 14 characters. | Amendment |
| NAD+GO | 3039 - Goods Owner Party ID | Declaration>Customer>**Shipper**>Reference Numbers>**TIN** (or **OID** if TIN null) | Outbound | an..35 | Use TIN if available; else OID. If both null, use 3036 (Shipper Name). | Amendment, Withdrawal |
| NAD+GO | 3036 - Owner Name | Declaration>Customer>**Shipper**>**Shipper Name** | Outbound | an..35 | Conditional: use if TIN/OID not available. **Exclude 3055 if 3036 used.** | Amendment, Withdrawal |
| CNT+11 (Line) | 6066 - Number of Packages | Shipment package count | Outbound | n..18 | Extract from shipment record. | Amendment |
| CNT+36 (Line) | 6066 - Number of Containers | Shipment container count | Outbound | n..18 | Extract from shipment record. | Amendment |
| CST | 1496 - Line Number | Declaration>Customs>Reference Numbers>**DSQ** | Inbound | n..6 | Match line number to shipment. Strip leading zeros (e.g., `0001` → DSQ=1). | MSG-ESMR |
| FTX+AHN (Line) | 4440 - Line Status Type | Shipment MAN Status | Inbound | an..512 | **Map:** `CLEAR` → MAN=CLR, `ERROR` (including all ERROR variants) → MAN=ERR. Store entire status type including suffix (e.g., `ERROR - EXPIRED`). | MSG-ESMR |
| FTX+AHN (Line) | 4440 - Line Status Description | Shipment>Summary>Customer Supplied References>**ESMRSD**>Number and Comment | Inbound | an..512 | Store Status Type in Number, Description in Comment. Include full suffix (e.g., `ERROR - EXPIRED`). | MSG-ESMR |
| ERP-ERC-FTX (Line) | 9321 - Error Identifier | Shipment>Summary>Customer Supplied References>**ESMRED**>Number | Inbound | an..35 | Store error code. Only if ERP location ≠ `0000`. | MSG-ESMR |
| ERP-ERC-FTX (Line) | 4440 - Error Description | Shipment>Summary>Customer Supplied References>**ESMRED**>Comment | Inbound | an..512 | Store error description. Only if ERP location ≠ `0000`. | MSG-ESMR |

---

### 2.3 Flow-Level Mappings

| EDIFACT Segment | Element | SBSS Source Field | Direction | Data Type | Transformation Rules | Applicability |
|-----------------|---------|-------------------|-----------|-----------|----------------------|---------------|
| N/A (Derived) | N/A | Shipment>Flow>Reference Numbers>**MWB** | Inbound | - | **Derivation:** Match Shipment>Flow>Reference Numbers>MWB to Master Waybill>Number. If all shipments in flow have MAN=CLR, add **BCRCLR** to flow. If any have MAN=ERR, add **BCRERR** to flow. | MSG-ESMR |

**Flow-Level BCR Status Update Logic:**

1. **Trigger:** MSG-ESMR processed with line-level statuses.
2. **Iterate:** For each shipment in the MSG-ESMR:
   - Extract Shipment>Flow>Reference Numbers>**MWB**.
   - Match MWB to Master Waybill>**Number**.
3. **Aggregate:**
   - If all shipments under the same MWB have MAN=CLR, add Reference Number **BCRCLR** to the flow.
   - If any shipment under the MWB has MAN=ERR, add Reference Number **BCRERR** to the flow.
4. **Purpose:** Provides flow-level visibility into whether a consolidated manifest was fully cleared or had errors.

---

### 2.4 Charge File Suppression Mappings

| SBSS Field | Value | Processing Rule | Applicability |
|------------|-------|-----------------|---------------|
| Shipment>Summary>Reference Numbers>**UNS** (Upload Not Sent) | Yes | **Suppression Rule:** If Master Waybill BCR status = WTD (Withdrawn), set UNS=Yes on all associated shipments. This prevents duplicate charge file generation for withdrawn manifests. | Withdrawal Accepted |

**Charge File Suppression Logic:**

1. **Trigger:** MSG-ESMR received with Header Status = `WITHDRAWN` (BCR = WTD).
2. **Action:**
   - Map Master Waybill>**Number** to all Shipment>Master Waybill>**Number**.
   - For each matched shipment, set Shipment>Summary>Reference Numbers>**UNS** = `Yes`.
3. **Downstream Impact:** Billing system checks UNS flag. If `Yes`, skip charge file generation for that shipment.
4. **Purpose:** Prevents invoicing customers for cargo that was withdrawn and never exported.

---

### 2.5 Reference Number Reflection (Master to Shipment)

| SBSS Source Field | SBSS Destination Field | Trigger | Processing Rule |
|-------------------|------------------------|---------|-----------------|
| Master Waybill>Miscellaneous>Reference Numbers>**URM** | Declaration>Customs>Reference Numbers>**URM** | MSG-ESM Original message sent | **Reflection Rule:** Once MSG-ESM Original message is successfully sent (BCR=SNT → SCR), reflect Master URM to all shipments included in the message. Store in Declaration>Customs>Reference Numbers>URM. |

**URM Reflection Logic:**

1. **Trigger:** MSG-ESM Original message sent (BCR transitioned from RFC to SNT).
2. **Action:**
   - Extract Master Waybill>Miscellaneous>Reference Numbers>**URM**.
   - Map Master Waybill>**Number** to all Shipment>Master Waybill>**Number** included in the message.
   - For each matched shipment, insert URM into Declaration>Customs>Reference Numbers>**URM**.
3. **Purpose:** Provides shipment-level visibility into which Master manifest the shipment belongs to. Useful for cross-referencing in reports (e.g., AU Rating List displays "MAWB & SEQ & URM").

**AU Rating List Display Update:**

- **Current Column:** "MAWB & SEQ"
- **Updated Column:** "MAWB & SEQ & URM"
- **Format Example:**
  ```
  4067668094 / 002 / MW3658
  ```
  (MAWB = `4067668094`, SEQ = `002` (DSQ value), URM = `MW3658...`)

**Note:** The Rating List displays DSQ value in the "SEQ" position for backward compatibility with existing UI labels.

---

### 2.6 IRN and MTI Mappings (for CONTRL Matching)

| EDIFACT Segment | Element | SBSS Source Field | Direction | Data Type | Transformation Rules | Applicability |
|-----------------|---------|-------------------|-----------|-----------|----------------------|---------------|
| UNB (Interchange Header) | 0020 - Interchange Control Reference Number | Master Waybill>Miscellaneous>Reference Numbers>**IRN** | Outbound | an..14 | Assigned from system-generated sequence starting from **500** for Master Waybills (to differentiate from Shipment IRN which starts from 1). | Amendment, Withdrawal |
| UCI (CONTRL) | 0020 - Interchange Control Reference Number (Inbound) | Master Waybill>Miscellaneous>Reference Numbers>**IRN** | Inbound | an..14 | Match CONTRL to Master by IRN. **Strip leading zero** if present (e.g., `0123456` → `123456`). | CONTRL |
| UNH | 0065 - Message Type Identifier | Master Waybill>Miscellaneous>Reference Numbers>**MTI** | Outbound | a6 | Fixed value: `CUSCAR` (for MSG-ESM messages). | Amendment, Withdrawal |
| UCM (CONTRL) | 0065 - Message Type Identifier | Master Waybill>Miscellaneous>Reference Numbers>**MTI** | Inbound | a6 | Match CONTRL to message type. | CONTRL |

**IRN Sequencing Logic:**

- **Master Waybill IRN:** Starts from **500** (e.g., 500, 501, 502, ...).
- **Shipment IRN:** Starts from **1** (e.g., 1, 2, 3, ...).
- **Purpose:** Differentiate Master Waybill interchanges from Shipment interchanges when processing CONTRL messages.
- **Assignment Trigger:** When MSG-ESM message (Original, Amendment, or Withdrawal) is constructed, assign next available IRN from Master sequence.
- **Storage:** Master Waybill>Miscellaneous>Reference Numbers>**IRN**.

**MTI Assignment:**

- **Value:** `CUSCAR` (UN/EDIFACT message type for customs cargo report).
- **Assignment Trigger:** When MSG-ESM message is constructed.
- **Storage:** Master Waybill>Miscellaneous>Reference Numbers>**MTI**.

**CONTRL Matching with Leading Zero Handling:**

- **Issue:** TPS may return CONTRL with UCI 0020 element containing leading zero (e.g., `0123456` instead of `123456`).
- **Solution:** Before matching CONTRL to Master Waybill, strip leading zero from UCI 0020 element.
- **Example:**
  - CONTRL 0020 = `0123456`
  - Strip leading zero → `123456`
  - Match to Master Waybill>Miscellaneous>Reference Numbers>**IRN** = `123456`.

---

### 2.7 Reference Number Configuration (Admin Table Updates)

**New Reference Numbers to Add:**

| Admin Table | Reference Number Type | Parent Type | Code | Description | Print Code | EDI Code |
|-------------|-----------------------|-------------|------|-------------|------------|----------|
| Declaration Ref Type | URM | MW | URM | MAWB Unique Reference Number | - | - |

**Reference Numbers to Remove:**

| Admin Table | Reference Number Type | Parent Type | Code | Description | Reason for Removal |
|-------------|-----------------------|-------------|------|-------------|---------------------|
| Reference Number Type | URN | MW | URN | Sender Reference | Replaced by URM with "MW" parent type for clarity. URN was ambiguous (used for both Master and Declaration). |

**Rationale:**
- **URM (MAWB Unique Reference Number):** Clearly distinguishes Master Waybill sender references (with "MW" prefix) from Declaration sender references (which use "AU" prefix).
- **Parent Type = MW:** Indicates this reference belongs to Master Waybill entity.
- **Removal of URN (MW):** Obsolete reference type. URM replaces it.

---

### 2.8 Transport Type Default Assignment

| SBSS Field | Trigger | Default Value | Conditional Logic |
|------------|---------|---------------|-------------------|
| Master Waybill>Master Waybill>**Transport Type** | Master Waybill>Export/Import Information>**Origin Country** = `AU` (on load or save) | `A` (Air) | **If Transport Type is empty:** Assign default `A`. **If Transport Type has value:** No change. |

**Purpose:** Ensures all Australian export manifests have a valid Transport Type, defaulting to Air if not specified.

---

## 3. Business Rules and Validation

This section consolidates all validation rules, conditional logic, and processing constraints that apply across MSG-ESM Amendment, Withdrawal, and MSG-ESMR processing.

### 3.1 Amendment Trigger Conditions (Outbound)

**Master Waybill-Level Validation (BCR Status Change to AMD):**

When a broker sets Master Waybill>Brokerage Status>**BCR** = **AMD** and saves the record, the following conditions are validated:

| Validation Check | SBSS Field | Condition | Failure Action |
|------------------|------------|-----------|----------------|
| Origin Country | Master Waybill>Export/Import Information>**Origin Country** | Must equal `AU` | Raise error: "Amendment only applicable for Australian origin manifests." |
| CRN Exists | Master Waybill>Miscellaneous>Reference Numbers>**CRN** | Must have value | Raise error: "Customs Reference Number (CRN) required for amendment." |
| URM Exists | Master Waybill>Miscellaneous>Reference Numbers>**URM** | Must have value (assigned during original MSG-ESM submission) | Raise error: "Sender Reference (URM) missing. Original MSG-ESM must be submitted first." |

**If all Master-level validations pass:**
- Trigger shipment-level validation check: iterate through all shipments associated with this Master (Shipment>Master Waybill>Number matches Master Waybill>Number).
- Check if at least one shipment has MAN status = **PAS** (Passed validation).
- **If no shipments have MAN=PAS:**
  - Set Master Waybill>Brokerage Status>**BCR** = **FAI** (Validation Failed).
  - Display popup: "No shipments eligible for amendment. Ensure MAN status = PAS and required fields populated."
  - **Do NOT store error details in Master Waybill Brokerage Events or Reference Numbers.**
- **If at least one shipment has MAN=PAS:**
  - Increment Master Waybill>Miscellaneous>Reference Numbers>**SRV** by 1.
  - Construct MSG-ESM Amendment message (see message construction logic in §6).
  - Set Master BCR = **AST** (Amendment Sent).
  - Set shipment MAN = **AST** for all included shipments (MAN=PAS).
  - Submit message to TPS.

**If Master-level validation fails:**
- Set Master Waybill>Brokerage Status>**BCR** = **FAI** (Validation Failed).
- Display popup showing validation error details.
- **Do NOT store error details in Master Waybill Brokerage Events or Reference Numbers.**

---

**Shipment-Level Validation (MAN Status = PAS):**

For each shipment where Shipment>Master Waybill>**Number** matches the Master being amended:

| Validation Check | SBSS Field | Condition | Failure Action |
|------------------|------------|-----------|----------------|
| MAN Status | Shipment MAN Status | Must equal **PAS** (Passed) | Exclude shipment from MSG-ESM Amendment message. Only shipments with MAN=PAS are included. |
| Declaration Sequence | Declaration>Customs>Reference Numbers>**DSQ** | Must have value | Raise warning: "Declaration Sequence (DSQ) missing. Shipment cannot be included in amendment." Set MAN=FAI. |

**If shipment-level validation passes for at least one shipment:**
- Construct MSG-ESM Amendment message (Function Code 5) with validated shipments.
- Set Master BCR = **AST** (Amendment Sent).
- Set shipment MAN = **AST** for included shipments.
- Submit message to TPS.

**If validation fails for all shipments (no shipments with MAN=PAS):**
- Set Master BCR = **FAI** (Validation Failed).
- Display popup: "No shipments eligible for amendment. Ensure MAN status = PAS and required fields populated."
- **Do NOT store error details in Master Waybill Brokerage Events or Reference Numbers.**

---

### 3.2 Withdrawal Trigger Conditions (Outbound)

**Master Waybill-Level Validation (BCR Status Change to WID):**

When a broker sets Master Waybill>Brokerage Status>**BCR** = **WID** and saves the record:

| Validation Check | SBSS Field | Condition | Failure Action |
|------------------|------------|-----------|----------------|
| Origin Country | Master Waybill>Export/Import Information>**Origin Country** | Must equal `AU` | Raise error: "Withdrawal only applicable for Australian origin manifests." |
| CRN Exists | Master Waybill>Miscellaneous>Reference Numbers>**CRN** | Must have value | Raise error: "Customs Reference Number (CRN) required for withdrawal." |
| URM Exists | Master Waybill>Miscellaneous>Reference Numbers>**URM** | Must have value | Raise error: "Sender Reference (URM) missing. Original MSG-ESM must be submitted first." |

**If all validations pass:**
- Increment Master Waybill>Miscellaneous>Reference Numbers>**SRV** by 1.
- Construct MSG-ESM Withdrawal message (Function Code 50, header only, no lines).
- Set Master BCR = **WST** (Withdrawal Sent).
- Set all associated shipments' MAN = **WST**.
- Submit message to TPS.

**If validation fails:**
- Set Master BCR = **FAI**.
- Display popup: "Withdrawal validation failed. [specific error]."
- **Do NOT store error details in Master Waybill Brokerage Events or Reference Numbers.**

---

### 3.3 Shipment-Level Validation Rules (RDY → PAS/FAI)

**Validation Trigger:** When MAN status is changed to **RDY** (Ready for validation) on a shipment and the shipment is saved.

**Validation Pass:** If all checks below pass, set MAN = **PAS** (Passed). Shipment is eligible for inclusion in MSG-ESM Amendment.

**Validation Fail:** If any check fails, set MAN = **FAI** (Validation Failed). Display popup with validation warning. **Shipment saves successfully** (validation is non-blocking).

**Important:** Validation errors/warnings are displayed in a popup. **Do NOT store validation error details in Shipment Comment FAI** (previous behavior removed).

---

#### 3.3.1 Export Authorization Code (EAC) Validation

**Clearance Type Context:** This validation applies only to CT ∈ {FML, ABK, DEM, LND}. Skip EAC validation if CT = TRS.

| Field | Validation Rule | Failure Action |
|-------|-----------------|----------------|
| Declaration>Customs>Reference Numbers>**EAC** | First two characters must equal `AU` (if EAC exists). **Exception:** If CT=TRS, EAC validation skipped. | Raise warning: "Export Authorization Code must start with AU for Australian export." Set MAN=FAI. Display popup. |

**Conditional Logic:**
- **If CT ∈ {FML, ABK, DEM, LND}:** Validate EAC.
- **If CT = TRS:** Skip EAC validation entirely.

**Alternative Validation (if EAC is missing):**
- If EAC is not populated, check if **Export Country** = `AU` (from Master Waybill>Export/Import Information>**Export Country**).
- If Export Country = `AU`, validation passes (even if EAC is missing).
- If Export Country ≠ `AU` and EAC is missing, raise warning: "Export Country must be AU or Export Authorization Code must start with AU."

---

#### 3.3.2 Customs Authority Number / Exemption Code Validation

**Clearance Type-Specific Rules:**

| Clearance Type (CT) | Required Field(s) | Validation Rule | Failure Action |
|---------------------|-------------------|-----------------|----------------|
| **FML** | Declaration>Customs>Reference Numbers>**CCN** AND CUS Status = CLR or AAC | CCN must exist and CUS status must be CLR or AAC. | **Note:** This validation is enforced at **message trigger point** (when BCR=AMD is set), not at RDY validation. If CT=FML but CCN or CUS is missing, shipment is excluded from message (MAN remains RDY, not set to FAI). |
| **TRS** | Shipment>Summary>Reference Numbers>**TRS** | TRS must exist and have value. | Raise warning: "TRS number is required for Transhipment." Set MAN=FAI. Display popup. |
| **ABK, DEM, LND** | Shipment>Summary>Reference Numbers>**CAN** OR Declaration>Customs>Reference Numbers>**EDEC** | At least one of CAN or EDEC must have value. | Raise warning: "Either Customer Authority Number or Export Declaration Exemption Code is required for MSG-ESM message." Set MAN=FAI. Display popup. |

**FML Special Handling:**
- FML shipments require CCN and CUS=CLR/AAC to be included in MSG-ESM message.
- However, this is **not** a RDY validation rule. Instead, at message trigger (BCR=AMD), SBSS filters shipments:
  - If CT=FML AND (CCN missing OR CUS ∉ {CLR, AAC}), exclude shipment from message.
  - If all FML shipments fail this filter, no shipments are included, and Master-level validation fails (BCR=FAI).

**TRS Validation Logic:**
- When MAN=RDY is triggered for TRS shipment, check if Shipment>Summary>Reference Numbers>**TRS** exists.
- If TRS is missing, validation fails (MAN=FAI, popup displayed).
- If TRS exists, validation passes on this check.

**ABK/DEM/LND Validation Logic:**
- When MAN=RDY is triggered for ABK/DEM/LND shipment, check if either CAN or EDEC exists.
- If both are missing, validation fails (MAN=FAI, popup displayed).
- If at least one exists, validation passes on this check.

---

#### 3.3.3 Contingency Customs Authority Number (CCAN) Validation

| Field | Validation Rule | Failure Action |
|-------|-----------------|----------------|
| Shipment>Summary>Reference Numbers>**CCAN** | **Mandatory** if EDEC = `EXCC`. Must be exactly 14 characters. | **If EDEC=EXCC and CCAN missing:** Raise warning: "Contingency Customs Authority Number is required when Export Declaration Exemption Code is EXCC." Set MAN=FAI. Display popup. **If EDEC=EXCC and CCAN length ≠ 14:** Raise warning: "Contingency Customs Authority Number must be 14 characters." Set MAN=FAI. Display popup. |

**Conditional Logic:**
- **If EDEC ≠ EXCC:** Skip CCAN validation (CCAN is not required).
- **If EDEC = EXCC:** Validate CCAN existence and length.

---

#### 3.3.4 Shipper Identification Validation

| Field | Validation Rule | Failure Action |
|-------|-----------------|----------------|
| Declaration>Customer>**Shipper**>Reference Numbers>**TIN** OR **OID** OR **Shipper Name** | At least one of TIN, OID, or Shipper Name must have value. | Raise warning: "TIN/OEM Client ID or Shipper Name is required for MSG-ESM message." Set MAN=FAI. Display popup. |

**Mapping Priority:**
1. **If TIN exists:** Use TIN in NAD+GO (3039).
2. **Else if OID exists:** Use OID in NAD+GO (3039).
3. **Else if Shipper Name exists:** Use Shipper Name in NAD+GO (3036).
4. **Else:** Validation fails.

---

#### 3.3.5 Warning vs. Error Handling (Non-Blocking Validation)

**Design Principle:** Validation failures raise **warnings** (non-blocking) rather than hard errors. Shipments can be saved even if validation fails, but MAN status is set to **FAI** to indicate failure.

**Popup Display:**
- When MAN=FAI is set, display popup with validation failure details (e.g., "TRS number is required for Transhipment.").
- **Do NOT append validation errors to Shipment Comment FAI** (previous behavior removed).
- Validation error content in popup should include **data name only** (e.g., "Export Declaration Exemption Code"), not specific SBSS mapping path (e.g., avoid "Declaration>Customs>Reference Numbers>EDEC").

**Broker Workflow:**
1. Broker sets MAN=RDY.
2. Validation runs.
3. If validation fails, MAN=FAI, popup displays warning.
4. Broker corrects data.
5. Broker sets MAN=RDY again.
6. If validation passes, MAN=PAS (Passed).
7. Shipment is eligible for inclusion in MSG-ESM Amendment.

---

### 3.4 Post-Submission Status Changes

#### 3.4.1 MSG-ESM Amendment Sent (Function Code 5)

**Trigger:** MSG-ESM Amendment message successfully transmitted to TPS.

**Master Waybill Updates:**
- BCR = **AST** (Amendment Sent)
- Increment SRV in Master Waybill>Miscellaneous>Reference Numbers>SRV (already done pre-submission).

**Shipment Updates (for all shipments included in the message):**
- MAN = **AST** (Amendment Sent)

**Flow Updates:**
- No immediate flow update. Flow BCR status updated upon MSG-ESMR receipt.

---

#### 3.4.2 MSG-ESM Withdrawal Sent (Function Code 50)

**Trigger:** MSG-ESM Withdrawal message successfully transmitted to TPS.

**Master Waybill Updates:**
- BCR = **WST** (Withdrawal Sent)
- Increment SRV.

**Shipment Updates (for all shipments associated with the Master):**
- MAN = **WST** (Withdrawal Sent)

**Flow Updates:**
- No immediate flow update.

---

### 3.5 MSG-ESMR Response Processing Rules

#### 3.5.1 Amendment Response (RFF+AFM = 5)

**Header-Level Status Processing:**

| MSG-ESMR Status (FTX+AHN) | Master BCR Update | Shipment MAN Update (all associated) | Brokerage Events Storage |
|-----------------------|-------------------|--------------------------------------|--------------------------|
| `CLEAR` | BCR = **CLR** | No automatic sync (line-level statuses take precedence) | Store "CLEAR: [description]" |
| `ERROR` (any variant: ERROR, ERROR - VALIDATION, ERROR - SUSPENDED, ERROR - EMBARGOED, ERROR - EXPIRED) | BCR = **ERR** | If header error (ERP location=0000), set all MAN = **REJ** | Store "ERROR - [suffix]: [description]" (include full suffix) |
| `REJECTED` | BCR = **REJ** | Set all MAN = **REJ** | Store "REJECTED: [description]" |
| `REVOKED` | BCR = **RVK** | No automatic sync | Store "REVOKED: [description]" |

**Line-Level Status Processing:**

For each CST segment in MSG-ESMR:

1. **Extract Line Number:** CST element 1496.
2. **Match Shipment:** Map line number to shipment where Declaration>Customs>Reference Numbers>DSQ matches (strip leading zeros).
3. **Extract Line Status:** FTX+AHN element 4440 - Line Status Type.
4. **Update Shipment MAN:**
   - `CLEAR` → MAN = **CLR**
   - `ERROR` (including `ERROR - EXPIRED`, `ERROR - VALIDATION`, etc.) → MAN = **ERR**
5. **Update Flow BCR Status:**
   - Map Shipment>Flow>Reference Numbers>MWB to Master Waybill>Number.
   - If Line Status = `CLEAR`, add Reference Number **BCRCLR** to flow.
   - If Line Status = `ERROR`, add Reference Number **BCRERR** to flow.
6. **Store Line Status:**
   - Shipment>Summary>Customer Supplied References>**ESMRSD**>Number = Line Status Type (e.g., `ERROR - EXPIRED`).
   - ESMRSD>Comment = Line Status Description.
   - **Critical:** Store entire status type including suffix (e.g., `ERROR - EXPIRED`, not just `ERROR`).

**Error Detail Processing (Segment Group 4: ERP-ERC-FTX):**

**If ERP location = 0000 (Header Error):**
- Store error in Master Waybill>Miscellaneous>Brokerage Events: "Error Code: Error Description".
- Example: "XM1016: EXPORT DOCUMENT STATUS IS ERROR BECAUSE A SUB-MANIFEST REPORT WITH A CARGO REPORT TYPE OF C (CONSOLIDATION) HAS NO LINES."

**If ERP location ≠ 0000 (Line Error):**
- Match location to shipment (map to DSQ).
- Store error in Shipment>Summary>Customer Supplied References>**ESMRED**>Number (error code) and Comment (error description).
- Example: ESMRED>Number = `XM1024`, Comment = "LINENUM=000000000000169 IS TRYING TO QUOTE EDN=AFENRN3NW THAT HAS ALREADY BEEN TALLY EXPIRED."

---

#### 3.5.2 Withdrawal Response (RFF+AFM = 50)

**Header-Level Status Processing:**

| MSG-ESMR Status (FTX+AHN) | Master BCR Update | Shipment MAN Update (all associated) | Brokerage Events Storage |
|-----------------------|-------------------|--------------------------------------|--------------------------|
| `REJECTED` | BCR = **WRJ** (Withdrawal Rejected) | Set all MAN = **WRJ** | Store "REJECTED: [description]" |
| `WITHDRAWN` | BCR = **WTD** (Withdrawn) | Set all MAN = **WTD** | Store "WITHDRAWN: [description]" |

**Line-Level Processing:**
- **Not applicable** for withdrawal responses (Function Code 50 withdrawals do not include line data).
- Any line-level segments in withdrawal MSG-ESMR are ignored.

**Charge File Suppression:**
- **If BCR = WTD:** Set UNS (Upload Not Sent) flag on all associated shipments to prevent charge file generation.

---

### 3.6 CONTRL (Syntax Error) Processing

**CONTRL Message Purpose:** EDIFACT syntax acknowledgment. If TPS cannot parse the MSG-ESM message due to syntax errors, it returns a CONTRL message with error details.

**CONTRL Processing Logic:**

1. **Identify Master Waybill:**
   - Extract `0020 - Interchange Control Reference Number (Inbound)` from UCI segment.
   - **Strip leading zero if present:** If 0020 starts with `0`, remove it (e.g., `0123456` → `123456`).
   - Match to Master Waybill>Miscellaneous>Reference Numbers>**IRN** (Interchange Reference Number).

2. **Identify Message Type:**
   - Extract `0065 - Message Type Identifier` from UCM segment.
   - Match to Master Waybill>Miscellaneous>Reference Numbers>**MTI** (Message Type Identifier).
   - **Example:** MTI = `CUSCAR` → MSG-ESM message.

3. **Update Master BCR Status:**
   - Set BCR = **SYN** (Syntax Error).

4. **Store Error Details:**
   - Extract error segments from CONTRL (UCS, UCF, etc.).
   - Store in Master Waybill>Miscellaneous>Brokerage Events: "Syntax Error: [details]".

5. **Notify Broker:**
   - Display error details in SBSS UI.
   - Broker must correct syntax issue and resubmit.

**IRN and MTI Assignment (Outbound MSG-ESM):**
- **IRN:** Assigned when constructing EDIFACT interchange header (UNB segment). Sequence starts from **500** for Master Waybills (distinct from shipment IRN sequence which starts from 1).
- **MTI:** Fixed value `CUSCAR` for MSG-ESM messages. Stored in Master Waybill>Miscellaneous>Reference Numbers>MTI.

**Example CONTRL Processing:**

**Inbound CONTRL:**
```
UCI+0123456+ABC+4'    (Interchange 0123456, syntax error code 4)
UCM+CUSCAR+1+2'       (Message CUSCAR, ref 1, error type 2)
UCS+7+NAD'            (Segment 7, NAD segment has error)
```

**Processing:**
1. Extract UCI 0020 = `0123456`.
2. Strip leading zero → `123456`.
3. Match to Master Waybill>Miscellaneous>Reference Numbers>IRN = `123456`.
4. Extract UCM 0065 = `CUSCAR`, match to MTI = `CUSCAR`.
5. Set Master BCR = **SYN**.
6. Store in Brokerage Events: "Syntax Error: Interchange 123456 (leading zero stripped), Message CUSCAR, Segment NAD (position 7) - syntax violation."

---

## 4. Status Model

This section defines all status codes, transition triggers, and priority rules for BCR (Master Waybill) and MAN (Shipment) statuses across the MSG-ESM lifecycle.

### 4.1 BCR Status Values (Master Waybill Level)

| Status Code | Description | Trigger Condition | Subsequent Statuses | Notes |
|-------------|-------------|-------------------|---------------------|-------|
| **RFC** | Ready for Customs | Master validated and approved for submission (Original MSG-ESM) | SNT, FAI | Prerequisite for Original MSG-ESM submission. |
| **SNT** | Sent to Customs | Original MSG-ESM message transmitted to TPS | SCR, SYN | Original submission acknowledged. |
| **SCR** | Successfully Received | TPS acknowledgment received (Original MSG-ESM) | CLR, ERR, REJ, RVK | Customs processing in progress. |
| **CLR** | Cleared | MSG-ESMR received with Header Status = CLEAR | AMD, WID | Manifest approved by customs. Can be amended or withdrawn. |
| **ERR** | Error | MSG-ESMR received with Header Status = ERROR | AMD | Manifest rejected with validation errors. Requires amendment. |
| **REJ** | Rejected | MSG-ESMR received with Header Status = REJECTED | AMD | Manifest rejected by customs officer. Requires amendment. |
| **RVK** | Revoked | MSG-ESMR received with Header Status = REVOKED | AMD | Customs revoked previously approved manifest. Requires amendment. |
| **AMD** | Amendment | Broker initiates amendment (user action) | AST, FAI | Broker sets BCR=AMD to trigger amendment. |
| **AST** | Amendment Sent | MSG-ESM Amendment message transmitted (Function Code 5) | AAC, ARJ, ERR, CLR, REJ, RVK | Amendment submitted to customs. **Note:** AST can transition to CLR (if header status CLEAR), ERR (if header status ERROR), REJ (if header status REJECTED), RVK (if header status REVOKED), or AAC/ARJ (deprecated statuses for amendment-specific responses). |
| **AAC** | Amendment Accepted | MSG-ESMR received with Header Status = CLEAR (for amendment) | AMD, WID | Amendment approved. Can be further amended or withdrawn. **Note:** AAC is effectively equivalent to CLR; both indicate approval. |
| **ARJ** | Amendment Rejected | MSG-ESMR received with Header Status = REJECTED (for amendment) | AMD | Amendment rejected. Requires re-amendment. **Note:** ARJ is effectively equivalent to REJ; both indicate rejection. |
| **WID** | Withdrawal | Broker initiates withdrawal (user action) | WST, FAI | Broker sets BCR=WID to trigger withdrawal. |
| **WST** | Withdrawal Sent | MSG-ESM Withdrawal message transmitted (Function Code 50) | WTD, WRJ | Withdrawal submitted to customs. |
| **WTD** | Withdrawn | MSG-ESMR received with Header Status = WITHDRAWN | - | Withdrawal accepted. Manifest no longer valid. Terminal status. |
| **WRJ** | Withdrawal Rejected | MSG-ESMR received with Header Status = REJECTED (for withdrawal) | WID | Withdrawal rejected. Broker must re-initiate or contact customs. |
| **SYN** | Syntax Error | CONTRL received with syntax errors | AMD, WID | Message syntax invalid. Broker must correct and resubmit. |
| **FAI** | Validation Failed | Master-level validation failed pre-submission OR all shipments failed validation (no PAS shipments) | AMD, WID | Broker must correct data and retry. |
| **UND** | Undefined | Unknown or unhandled status from customs | - | Exceptional status for troubleshooting. |

---

### 4.2 MAN Status Values (Shipment Level)

| Status Code | Description | Trigger Condition | Subsequent Statuses | Notes |
|-------------|-------------|-------------------|---------------------|-------|
| **RDY** | Ready for Validation | Broker sets MAN=RDY to trigger shipment-level validation | PAS, FAI | User-initiated status to validate shipment for MSG-ESM inclusion. |
| **PAS** | Passed Validation | Shipment-level validation successful | AST, CLR, ERR | Shipment eligible for inclusion in MSG-ESM Amendment. |
| **FAI** | Validation Failed | Shipment-level validation failed | RDY | Broker must correct data and retry. Validation warnings displayed in popup (not stored in comments). |
| **AST** | Amendment Sent | Shipment included in MSG-ESM Amendment message | CLR, ERR | Shipment-level amendment submitted. |
| **CLR** | Cleared | MSG-ESMR line status = CLEAR | - | Shipment approved by customs. Terminal status for successful clearance. |
| **ERR** | Error | MSG-ESMR line status = ERROR | AST | Shipment rejected with errors. Requires re-amendment. |
| **REJ** | Rejected | Header-level rejection (ERP location=0000) OR MAN update from master BCR=REJ | AST | All shipments rejected if master rejected. |
| **WST** | Withdrawal Sent | Shipment associated with withdrawn master (BCR=WST) | WTD, WRJ | Shipment withdrawal submitted. |
| **WTD** | Withdrawn | Master withdrawal accepted (BCR=WTD) | - | Shipment withdrawal accepted. Terminal status. |
| **WRJ** | Withdrawal Rejected | Master withdrawal rejected (BCR=WRJ) | WST | Shipment withdrawal rejected. |
| **SYN** | Syntax Error | Master CONTRL received (BCR=SYN) | RDY, AST | Syntax error in master message affects all shipments. |
| **UND** | Undefined | Unknown status | - | Exceptional status. |

---

### 4.3 Status Transition Rules

#### 4.3.1 Master BCR Transitions

**Transition Diagram (Simplified):**

```
RFC → SNT → SCR → CLR → AMD → AST → AAC/CLR → [loop: AMD/WID]
                  ↓         ↓             ↓
                 ERR/REJ → AMD          ARJ/REJ/ERR → AMD
                  ↓
                 WID → WST → WTD (terminal)
                         ↓
                       WRJ → WID
                  ↓
                 SYN → AMD/WID (after correction)
                  ↓
                 FAI → AMD/WID (after correction)
```

**Transition Constraints:**
- **CLR** can transition to **AMD** or **WID** (broker-initiated).
- **ERR/REJ** can only transition to **AMD** (amendment required).
- **WTD** is terminal (no further transitions).
- **SYN** can transition to **AMD** or **WID** after syntax correction.
- **FAI** can transition to **AMD** or **WID** after data correction (or after correcting shipments and retrying RDY→PAS).
- **AST** can transition to **CLR**, **ERR**, **REJ**, **RVK**, **AAC**, or **ARJ** depending on MSG-ESMR response.

---

#### 4.3.2 Shipment MAN Transitions

**Transition Diagram (Simplified):**

```
RDY → PAS → AST → CLR (terminal)
  ↓             ↓
 FAI          ERR → AST (re-amendment)
  ↓             ↓
 RDY (retry)   REJ (if header rejected)
```

**Withdrawal Path:**

```
WST → WTD (terminal)
  ↓
 WRJ → WST (retry)
```

**Transition Constraints:**
- **CLR** is terminal for successful clearance.
- **WTD** is terminal for successful withdrawal.
- **ERR** requires re-amendment (transition back to AST via broker action: correct data, set MAN=RDY→PAS, trigger new amendment).
- **FAI** requires data correction and retry (transition to RDY).

---

### 4.4 Status Priority Rules

**Conflict Resolution:** When multiple statuses could apply (e.g., line-level CLEAR but header-level ERROR), apply the following priority:

1. **Header-level statuses override line-level statuses** if header indicates failure (ERR, REJ).
   - Example: If Header Status = REJECTED (ERP location=0000), set all shipments' MAN=REJ, even if line-level statuses are CLEAR.

2. **Line-level statuses are independent** if header indicates success (CLEAR).
   - Example: If Header Status = CLEAR but one line has ERROR, set that shipment's MAN=ERR while others remain CLR.

3. **Syntax errors (CONTRL) override all MSG-ESMR statuses.**
   - If CONTRL received, set BCR=SYN and all shipments' MAN=SYN.

4. **Withdrawal overrides amendment.**
   - If BCR=WID is set while BCR=AMD is pending, cancel amendment and process withdrawal.

---

## 5. Error and Exception Handling

This section consolidates all error scenarios, recovery procedures, and logging requirements.

### 5.1 Pre-Submission Validation Errors

**Error Category:** Data Quality / Completeness

| Error Scenario | Detection Point | Error Message | Recovery Procedure | Logging Requirement |
|----------------|-----------------|---------------|---------------------|---------------------|
| Master validation fails (missing CRN, URM) | Master BCR status change to AMD/WID | "Customs Reference Number (CRN) required for amendment/withdrawal." | Broker verifies original MSG-ESM was submitted successfully. If not, submit Original MSG-ESM first. | Display popup. **Do NOT store validation error details in Master Waybill Brokerage Events.** |
| Shipment validation fails (missing DSQ, TRS, CAN/EDEC) | Shipment MAN status change to RDY | Warnings as defined in §3.3 (e.g., "TRS number is required...") | Broker corrects missing data in SBSS. Sets MAN=RDY again to retry validation. | **Do NOT log validation warning in Shipment Comment FAI.** Display warning in popup only. |
| No shipments eligible for amendment (all MAN ≠ PAS) | Master BCR status change to AMD | "No shipments eligible for amendment. Ensure MAN status = PAS and required fields populated." | Broker reviews shipments, corrects data, sets MAN=RDY → PAS. Retries BCR=AMD. | Display popup. **Do NOT log in Master Waybill Brokerage Events.** |

---

### 5.2 Message Transmission Errors

**Error Category:** Network / Gateway Failures

| Error Scenario | Detection Point | Error Handling | Recovery Procedure | Logging Requirement |
|----------------|-----------------|----------------|---------------------|---------------------|
| TPS gateway unreachable | Message submission attempt | Exception thrown by message queue. | System retries submission (configurable retry count and interval, e.g., 3 retries at 5-minute intervals). If all retries fail, set BCR=FAI. | Log in SBSS system logs: "MSG-ESM transmission failed: [error detail]. Retry [n]/[max]." |
| Message submission timeout | Message submission attempt | Timeout exception after configurable duration (e.g., 30 seconds). | Retry submission. If persistent, escalate to IT support to check TPS gateway status. | Log in system logs and Master Waybill>Miscellaneous>Brokerage Events: "Message submission timeout. [timestamp]". |

---

### 5.3 Syntax Errors (CONTRL Messages)

**Error Category:** EDIFACT Syntax Violations

| Error Scenario | Detection Point | Error Handling | Recovery Procedure | Logging Requirement |
|----------------|-----------------|----------------|---------------------|---------------------|
| TPS returns CONTRL with syntax errors | CONTRL message receipt | Parse CONTRL, extract error details (UCI, UCM, UCS segments). Set BCR=SYN. | Broker reviews CONTRL error details in SBSS UI. Corrects syntax issue (e.g., incorrect segment sequencing, invalid element format). Resubmits by setting BCR=AMD or WID again. | Store CONTRL error in Master Waybill>Miscellaneous>Brokerage Events: "Syntax Error: [CONTRL error detail]". |

**CONTRL Error Detail Extraction:**
- **UCI Segment:** Interchange control reference and syntax error code.
- **UCM Segment:** Message reference and error description.
- **UCS/UCF Segments:** Segment/element-level error details.

**Example CONTRL Error:**
```
UCI+0123456+ABC+4'    (Error code 4 = syntax error)
UCM+CUSCAR+1+2'       (Message CUSCAR, ref 1, error type 2)
UCS+7+NAD'            (Segment 7, NAD segment has error)
```
**Storage:**
- Master Waybill>Miscellaneous>Brokerage Events: "Syntax Error: Interchange 123456 (leading zero stripped), Message CUSCAR, Segment NAD (position 7) - syntax violation."

**Leading Zero Handling:**
- If UCI 0020 element starts with `0`, strip it before matching to Master IRN.
- Example: UCI 0020 = `0123456` → strip to `123456` → match to Master IRN = `123456`.

---

### 5.4 Validation Errors (MSG-ESMR with ERROR/REJECTED)

**Error Category:** Business Rule Violations

| Error Scenario | Detection Point | Error Handling | Recovery Procedure | Logging Requirement |
|----------------|-----------------|----------------|---------------------|---------------------|
| Header-level validation failure (e.g., consolidation report missing lines) | MSG-ESMR Header FTX+AHN = ERROR/REJECTED, ERP location=0000 | Set BCR=ERR or REJ. Set all shipments' MAN=REJ. Store error in Brokerage Events. | Broker reviews error details. Corrects issue at Master or Shipment level (e.g., add missing shipments to consolidation, correct MAWB data). Resubmits by setting BCR=AMD. | Store in Master Waybill>Miscellaneous>Brokerage Events: "Header Error: [error code] - [error description]". Example: "XM1016 - EXPORT DOCUMENT STATUS IS ERROR BECAUSE A SUB-MANIFEST REPORT WITH A CARGO REPORT TYPE OF C (CONSOLIDATION) HAS NO LINES." |
| Line-level validation failure (e.g., EDN expired, HS code invalid) | MSG-ESMR Line FTX+AHN = ERROR, ERP location≠0000 | Identify shipment via DSQ. Set shipment MAN=ERR. Store error in ESMRED. | Broker reviews error details in shipment's ESMRED reference. Corrects issue (e.g., update EDN, re-classify commodity). Sets MAN=RDY → PAS. Resubmits amendment. | Store in Shipment>Summary>Customer Supplied References>ESMRED>Number (error code) and Comment (error description). Example: ESMRED>Number=XM1024, Comment="LINENUM=000000000000169 IS TRYING TO QUOTE EDN=AFENRN3NW THAT HAS ALREADY BEEN TALLY EXPIRED". |

---

### 5.5 Withdrawal Rejection (MSG-ESMR with REJECTED)

**Error Category:** Customs Policy / Timing Issues

| Error Scenario | Detection Point | Error Handling | Recovery Procedure | Logging Requirement |
|----------------|-----------------|----------------|---------------------|---------------------|
| Withdrawal rejected by customs (e.g., cargo already departed, permit in use) | MSG-ESMR Header FTX+AHN = REJECTED (for withdrawal) | Set BCR=WRJ. Set all shipments' MAN=WRJ. Store rejection reason in Brokerage Events. | Broker reviews rejection reason. Contacts customs if necessary to clarify. If cargo cannot be withdrawn electronically, escalate to manual procedures. If timing issue (e.g., cargo not yet departed), retry withdrawal. | Store in Master Waybill>Miscellaneous>Brokerage Events: "Withdrawal Rejected: [description]". Example: "REJECTED: THE EXPORT DECLARATION OR CARGO REPORT CANNOT BE WITHDRAWN BECAUSE THE GOODS HAVE ALREADY BEEN EXPORTED." |

---

### 5.6 Duplicate Message Prevention

**Error Category:** Data Integrity

| Error Scenario | Detection Point | Prevention Mechanism | Recovery Procedure | Logging Requirement |
|----------------|-----------------|----------------------|---------------------|---------------------|
| Broker attempts to submit duplicate amendment (same SRV) | Pre-submission check | Before submitting MSG-ESM Amendment, check if SRV already exists in Master>Miscellaneous>Reference Numbers>SRV. If SRV matches most recent submission and BCR=AST (already sent), prevent submission. | Raise error: "Amendment already in progress for this version. Wait for MSG-ESMR response before resubmitting." Broker waits for MSG-ESMR. If MSG-ESMR not received within expected timeframe, contact IT support to check message queue. | Log prevention in Master Waybill>Miscellaneous>Brokerage Events: "Duplicate amendment prevented. SRV=[value], BCR=AST." |

---

### 5.7 Message Analyzer Refactoring

**Issue:** MSG-ESMR response messages fail to be processed correctly, resulting in BCR statuses not updating based on customs responses.

**Root Cause:** Message Analyzer logic for BCR status updates may be incomplete or incorrectly routing MSG-ESMR responses to Master Waybills.

**Solution:**
- **Refactor Message Analyzer** to correctly parse MSG-ESMR messages and update Master Waybill BCR statuses based on Header FTX+AHN segment.
- **Ensure mapping** of RFF+ABO (Sender Reference) to Master Waybill>Miscellaneous>Reference Numbers>URM.
- **Ensure mapping** of RFF+AFM (Message Function Code) to route MSG-ESMR logic based on function code (5=Amendment, 50=Withdrawal).
- **Validate** that BCR status transitions align with §4.1 status model.
- **Test** end-to-end MSG-ESMR processing for Amendment and Withdrawal responses.

**Logging Requirement:**
- Log all MSG-ESMR message processing events in SBSS system logs: "MSG-ESMR received: URM=[value], SRV=[value], AFM=[function code], Status=[status type]."
- If MSG-ESMR processing fails, log error: "MSG-ESMR processing failed: [error detail]. URM=[value]."

---

### 5.8 Logging and Audit Trail Requirements

**General Logging Principles:**
- All status transitions (BCR, MAN) must be logged with timestamp and user ID.
- All inbound MSG-ESMR messages stored in raw format for audit (database table or file archive).
- All validation failures logged with specific error details for troubleshooting.

**Log Storage Locations:**

| Event Type | SBSS Storage Location | Retention Period | Access Level |
|------------|----------------------|------------------|--------------|
| Master status changes (BCR) | Master Waybill>Miscellaneous>Brokerage Events | Permanent (archived after 7 years per regulatory requirement) | Broker, Admin, Auditor |
| Shipment status changes (MAN) | Shipment comment log (not displayed in UI by default, accessible via audit query) | Permanent | Broker, Admin, Auditor |
| MSG-ESMR response details | Master Waybill>Miscellaneous>Brokerage Events (header), Shipment>Summary>Customer Supplied References>ESMRSD (line status) | Permanent | Broker, Admin |
| Validation errors | **Popup display only** (not stored in Shipment Comment FAI or Master Waybill Brokerage Events per updated requirements) | N/A (transient, displayed during validation) | Broker |
| Line-level errors from MSG-ESMR | Shipment>Summary>Customer Supplied References>ESMRED (line errors) | Permanent | Broker |
| Header-level errors from MSG-ESMR | Master Waybill>Miscellaneous>Brokerage Events | Permanent | Broker, Admin |
| CONTRL syntax errors | Master Waybill>Miscellaneous>Brokerage Events | Permanent | Broker, Admin, IT Support |
| Message transmission logs | SBSS system logs (database or file system) | 90 days (configurable) | IT Support, Admin |

**Audit Query Capabilities:**
- Brokers must be able to query:
  - All amendments submitted for a given Master Waybill (by URM).
  - All MSG-ESMR responses received for a given Master (by SRV).
  - All validation errors for a given shipment (by HAWB or DSQ).
- Admins must be able to query:
  - All MSG-ESM messages sent within date range.
  - All syntax errors (CONTRL) received within date range.
  - All withdrawal rejections within date range.

---

## 6. Integration Points

This section defines all system interfaces, event triggers, and data dependencies for MSG-ESM Amendment/Withdrawal processing.

### 6.1 TPS Gateway Interface

**Protocol:** EDIFACT over TCP/IP (VPN-tunneled secure connection)

**Message Flow:**

**Outbound (SBSS → TPS):**
1. SBSS constructs MSG-ESM message (Amendment or Withdrawal).
2. Message queued in outbound message queue.
3. Gateway transmits message to TPS endpoint.
4. TPS returns synchronous acknowledgment (interchange accepted) or CONTRL (syntax error).

**Inbound (TPS → SBSS):**
1. TPS sends MSG-ESMR (response) or CONTRL (syntax error).
2. Gateway receives message, validates interchange envelope (UNB/UNZ).
3. Message queued in inbound message queue.
4. SBSS Message Analyzer parses message, extracts segments, updates SBSS entities.

**Error Handling:**
- **Transmission Failure:** Retry logic (§5.2).
- **Interchange Rejection:** Parse CONTRL, set BCR=SYN (§5.3).
- **Message Parsing Failure:** Log error in system logs, alert IT support. Do not update SBSS statuses until parsing succeeds.

**Performance SLA:**
- **Outbound Submission:** 99.9% success rate, <10 seconds per message.
- **Inbound Processing:** 99.9% success rate, <30 seconds from receipt to SBSS status update.

---

### 6.

User stories:

title: Trigger MSG-ESM Amendment and Withdrawal messages
description: As a SBSS user I want to send MSG-ESM messages to customs with different function codes based on specific SBSS statuses.
acceptance_criteria: Prerequisite The requirement below must be implemented after the following user stories are finished: User Story 6876551: Add new references and set default value for MSG-ESM outbound messages User Story 6901975: Add new references for MSG-ESMR on original messaging User Story 6928054: Implement validation logic on MSG-ESM message - Part 2 Trigger points for MSG-ESM Amendment message Trigger points on Master Waybill level: Master Waybill>Origin Country is AU Master Waybill>Brokerage Status>BCR is AMD Master Waybill>Miscellaneous>Reference Numbers>CRN is available Trigger points on Shipment level: Country Code (the first two characters) in Declaration>Customs>Reference Number>EAC is AU Declaration>Customs>Reference Numbers>CCN is available CUS status is CLR or AAC CT is ABK/DEM/FML/LND/TRS If all conditions above are met, submit MSG-ESM Amendment message following logic below: Set 1056 - Sender Reference Version in BGM segment as unique and incremental based on TPS regulation: Each Change, Replacement, Replace Heading Section Only or Withdrawal MSG-ESM message will be considered to be a new version of the message. For each version of a message the version number must be unique and increment upwards, to facilitate TPS processing. Set 1225 - MESSAGE FUNCTION CODE in BGM segment to 5 (Replace) Map the following data to define the association between Master and Shipment: Master Waybill>Number with BCR Status AMD Shipment>Master Waybill>Number Include Line Section data from corresponding shipments with the following conditions in MSG-ESM Amendment message: MAN status is PAS (based on User Story 6928054) Declaration Reference Number SEQ is available Trigger points for MSG-ESM Withdrawal message Master Waybill>Origin Country is AU Master Waybill>Brokerage Status>BCR is WID Master Waybill>Miscellaneous>Reference Numbers>CRN is available If all conditions above are met, submit MSG-ESM Withdrawal message following logic below: Set 1056 - Sender Reference Version in BGM segment as unique and incremental based on TPS regulation Set 1225 - MESSAGE FUNCTION CODE in BGM segment to 50 Exclude Line information (Segment Group 7: CNI-CNT-SG8) in the message Post submission status change Once MSG-ESM Amendment message is sent, update the following statuses on SBSS: Change Master Waybill>Brokerage Status>BCR to SNT Change MAN status on all shipments in MSG-ESM message to SNT Update flow level BCR status based on logic below: Check Shipment>Flow>Reference Numbers>MWB on all shipments with MAN Status SNT Map MWB value with Master Waybill>Number with BCR Status SNT If the data above are consistent, add Reference Numbers>BCRSNT to the flow. Once MSG-ESM Withdrawal message is sent, update the following statuses on SBSS: Change Master Waybill>Brokerage Status>BCR to WST Map the following data to define the association between Master and Shipment: Master Waybill>Number with BCR Status WID Shipment>Master Waybill>Number Change MAN status on all shipments associated with the Master to WST

title: Map SBSS values to MSG-ESM Amendment message
description: As a SBSS user, I want to include values from SBSS data into the MSG-ESM (Export Sub Manifest) Amendment message, so that the actual values are available on SBSS and the Air Cargo Report is compliant with customs regulations.
acceptance_criteria: Prerequisite Mappings of MSG-ESM Amendment need to be implemented after the following user stories are finished: User Story 6876551: Add new references and set default value for MSG-ESM outbound messages User Story 6623953: Map SBSS values to MSG-ESM Original message SBSS mapping sheet update Follow the mapping for the data elements as defined in the attached excel sheet. Follow rules for including, excluding and repeating segments as defined in the attached excel sheet. Follow rules for mandatory or conditional elements in User Story 6416685. Generate Sender Reference Version from system side When an MSG-ESM message is triggered with Function Code 5 Add 1 to existing data in Master Waybill>Miscellaneous>Reference Numbers>SRV Replace existing SRV data with the incremental number Apply the incremented number as the value of 1056 - Sender Reference Version in BGM segment of MSG-ESM triggered Follow SRV logic of User Story 6978822 as reference Remarks Sender Reference Version Based on TPS specification, each Change, Replacement, Replace Heading Section Only or Withdrawal MSG-ESM message will be considered to be a new version of the message. For each version of a message the version number must be unique and increment upwards, to facilitate TPS processing. Transaction Type (Message Function Code) Based on current CW1 flow, 5 - Replacement will applied for the fixed Function Code of MSG-ESM Amendment message to simplify the logic. The value of 8179 - Mode of Transport in TDT segment should be automatically converted from system side: If SBSS mapping data is "A", then insert "6" to the message. If SBSS mapping data is "S", then insert "11" to the message. The value of 6066 - Total Number of Packages in CNT (1) +11 should summarize all values of 6066 - Number of Packages of CNT+11 in Segment Group 7. The value of 6066 - Total Number of Containers in CNT (1) + 36 should summarize all values of 6066 - Number of Containers of CNT+36 in Segment Group 7. Mapping logic of CNI - Line Number Map the following data to define the association between Master and Shipment: Master Waybill>Number with BCR Status AMD Shipment>Master Waybill>Number Fetch the data from Declaration>Reference Number SEQ on all shipments associated with the Master Insert SEQ as the value of CNI - Line Number Segment Group 14: GID-FTX should only be include when Exemption Code (Declaration Reference Number EDEC) = "EXPE" or "EXLV".

title: Map SBSS values to MSG-ESM Withdrawal message
description: As a SBSS user, I want to include values from SBSS data into the MSG-ESM (Export Sub Manifest) Withdrawal message, so that the actual values are available on SBSS and the Air Cargo Report is compliant with customs regulations.
acceptance_criteria: Prerequisite The mappings of Amendment message must be implemented after User Story 6623953 of Original message is finished SBSS mapping sheet update Follow the mapping for the data elements as defined in the attached excel sheet Follow rules for including, excluding and repeating segments as defined in the attached excel sheet Follow rules for mandatory or conditional elements in User Story 6416685 Generate Sender Reference Version from system side When an MSG-ESM message is triggered with Function Code 50, Add 1 to existing data in Master Waybill>Miscellaneous>Reference Numbers>SRV Replace existing SRV data with the incremental number Apply the incremented number as the value of 1056 - Sender Reference Version in BGM segment of MSG-ESM triggered Follow SRV logic of User Story 6978822 as reference Remarks Sender Reference Version Based on TPS specification, each Change, Replacement, Replace Heading Section Only or Withdrawal MSG-ESM message will be considered to be a new version of the message. For each version of a message the version number must be unique and increment upwards, to facilitate TPS processing. The value of 8179 - Mode of Transport in TDT segment should be automatically converted from system side: If SBSS mapping data is "A", then insert "6" to the message. If SBSS mapping data is "S", then insert "11" to the message. Message structure Based on TPS specification, Line information is not required for “Header Only Change” and “Withdrawal” messages. So exclude Segment Group 7: CNI-CNT-SG8 in the message.

title: LOP - Project-A - Export - Brokerage Cargo Reports (Manual and Automatic) - Part C (** IT Request)
description: LOP for Project-A - Export - Brokerage Cargo Reports (Manual and Automatic) - Part C (** IT Request)
acceptance_criteria: Create LOP diagram in Visio for Project-A - Export - Brokerage Cargo Reports (Manual and Automatic) - Part C (** IT Request) Create Test Strategy Create Architectural Assessment

title: MSG-ESM Amendment / Cancellation Messaging Brokerage Status Values / Setting Default Values for NRI / CRT Master Waybill Reference Numbers
description: As a SBSS user, I want various references to be made available for MSG-ESM amendment and cancellation messaging purposes, and for some specific, previously-implemented Master Waybill properties to be assigned with default values.
acceptance_criteria: The following Brokerage Status Values (with corresponding Description) must be configured in the Admin > References > Brokerage Status Value table: Status Type Status Value Description BCR AAC Amendment Accepted BCR ARJ Amendment Rejected BCR AST Amendment Sent BCR SYN MSG-ESM Rejected (Syntax Error) BCR UND Undefined BCR WRJ Withdrawal Rejected BCR WST Withdrawal Sent BCR WTD Withdrawn MAN AAC Amendment Accepted MAN ARJ Amendment Rejected MAN AST Amendment Sent MAN SYN MSG-ESM Rejected (Syntax Error) MAN UND Undefined MAN WRJ Withdrawal Rejected MAN WST Withdrawal Sent MAN WTD Withdrawn On Load of Master Waybill. If Master Waybill > Master Waybill > Export / Import Information > Origin Country is AU: Add Master Waybill > Miscellaneous > Reference Numbers > NRI with No in the Ref Numbers field. If Master Waybill > Master Waybill > Master Waybill > Transport Type is A: Add Master Waybill > Miscellaneous > Reference Numbers > CRT with C in the Ref Numbers field. Else, if Master Waybill > ... > Transport Type is S: Add Master Waybill > ... > CRT with S in the Ref Numbers field. Else: Do nothing. Else: Do nothing.

title: Process MSG-ESMR on MSG-ESM Amendment messages - Part 1
description: As a SBSS user I want SBSS to be able to process MSG-ESMR (Export Sub Manifest Response) messages from customs so that the process status in SBSS can be updated and customs feedback is visible.
acceptance_criteria: Prerequisite The current user story needs to be implemented after the following ones are finished: User Story 4764788: Process MSG-ESMR on MSG-ESM Original message User Story 6978822: Apply ICR logic for MSG-ESMR and ICONTRL messaging Remark Refer to attached excel sheet as detailed clarification for MSG-ESMR process Refer to attached text file as MSG-ESMR sample message Process MSG-ESMR on MSG-ESM Amendment message Process RFF+ABO segment Map 1154 - Sender Reference with Master Waybill>Miscellaneous>Reference Numbers>URN to identify Master Waybill Map 4000 - Sender Reference Version with Master Waybill>Miscellaneous>Reference Numbers>SRV to define the corresponding MSG-ESM message Sample segment: RFF+ABO:K00098816/PRD1::002 Process RFF+AFM segment Apply 1154 - Message Function Code (Inbound) to identify the transaction type of corresponding MSG-ESM If Message Function Code (Inbound) is 5, apply the logic clarified below. Sample segment: RFF+AFM:5 Process FTX+AHN segment in Header section Update Master Waybill>Brokerage Status>BCR based on 4440 - Status Type If Status Type is CLEAR, update BCR status to CLR. If Status Type is ERROR, update BCR status to ERR. If Status Type is REJECTED, update BCR status to REJ. If Status Type is REVOKED, update BCR status to RVK Note: Sometimes ERROR will be received along with condition, i.e., FTX+AHN+++ERROR - VALIDATION. In that case, BCR status should be updated to ERR. Store the following data to Master Waybill>Miscellaneous>Brokerage Events: 4440 - Status Type: 4440 - Status Description Example: ERROR - EXPIRED: REPORTED VALIDATION:THE GOODS COVERED BY THE DOCUMENT CANNOT BE DEALT WITH. CUSTOMS DOES NOT EXPECT FURTHER QUOTATION OF THE RELATED CAN. THE LODGED OR AMENDED INFORMATION HAS NOT PASSED THE REQUIRED EDITS. Sample segment: FTX+AHN+++CLEAR:THE GOODS COVERED BY THE DOCUMENT ARE AUTHORISED FOR EXPORT AND MAY BE DEALT WITH. Process Segment Group 4: ERP-ERC-FTX Process ERP segment to define error location corresponding to Segment Group 4 1054 - Error Location is formatted as L0 = Header, L1 to L9999 referring to the line number reported to The Department If Error Location is 0000, meaning the error is on Header level, then apply logic below: Reflect Error Description in FTX+AAO segment to Master Waybill>Miscellaneous>Brokerage Events Map the following data to define the association between error Master Waybill and shipments: Master Waybill>Number Shipment>Master Waybill>Number Update MAN Status of the associated shipments based on 4440 - Status Type in FTX+AHN segment in Header section If Header level Status Type is REJECTED, update MAN Status to REJ. Sample segment group (Master level) ERP+::0000 ERC+XM1016::95 FTX+AAO+++EXPORT DOCUMENT STATUS IS ERROR BECAUSE A SUB-MANIFEST REPORT WITH A CARGO REPORT TYPE OF C (CONSOLIDATION) HAS NO LINES If Error Location is other than 0000, meaning the error is on Line level, then apply logic below: Map Error Location with Declaration Reference Number SEQ to identify error shipment. For example, if Error Location is 0178, the error shipment should be the one with SEQ 178. Store 9321 - Error Identifier in ERC segment to ESMRED>Number of error shipment Store 4440 - Error Description in FTX+AAO segment to ESMRED>Comment of error shipment Sample segment group (Line level) ERP+::0169 ERC+XM1024::95 FTX+AAO+++LINENUM=000000000000169 IS TRYING TO QUOTE EDN=AFENRN3NW THAT HAS ALREADY BEEN TALLY EXPIRED Process CST segment Map 1496 - Line Number with SEQ to identify corresponding shipments If the value is 0001, the corresponding Shipment sequence number in SEQ should be 1. Once the shipment is identified, apply the logic clarified below on that Shipment. Sample segment: CST+0001 Process FTX+AHN segment in Line section Map the following data to define the association between Master Waybill and Shipments: Master Waybill>Number Shipment>Master Waybill>Number Update SBSS status on corresponding shipments based on 4440 - Line Status Type: If Status Type is CLEAR, update MAN status to CLR. If Status Type is ERROR, update MAN status to ERR. Map Master Waybill>Master Waybill Num with Shipment>Flow>Reference Numbers>MWB Update flow level BCR status based on logic below: Check Shipment>Flow>Reference Numbers>MWB on all corresponding shipments: Map MWB value with Master Waybill>Number If Status Type is CLEAR, add Reference Number BCRCLR to the flow. If Status Type is ERROR, add Reference Number BCRERR to the flow. Store 4440 - Line Status Type to Shipment>Summary>Customer Supplied References>ESMRSD>Number Store 4440 - Line Status Description to Shipment>Summary>Customer Supplied References>ESMRSD>Comment Sample segment: FTX+AHN+++ERROR:LINENUM=000000000000169 IS TRYING TO QUOTE EDN=AFENRN3NW THAT HAS ALREADY BEEN TALLY EXPIRED Note: the value of 4440 - Status Type in FTX+AHN stored to HSD (Header Section) and ESMRSD (Line Section) must include the entire datalike references below: ERROR - VALIDATION ERROR - SUSPENDED ERROR - EMBARGOED ERROR - EXPIRED

title: Process MSG-ESMR on MSG-ESM Withdrawal messages
description: As a SBSS user I want SBSS to be able to process MSG-ESMR (Export Sub Manifest Response) messages from customs so that the process status in SBSS can be updated and customs feedback is visible.
acceptance_criteria: Prerequisite The current user story needs to be implemented after the following ones are finished: User Story 4764788: Process MSG-ESMR on MSG-ESM Original message User Story 6978822: Apply ICR logic for MSG-ESMR and ICONTRL messaging Remark Refer to attached excel sheet as detailed clarification for MSG-ESMR process Refer to attached text file as MSG-ESMR sample message Process MSG-ESMR on MSG-ESM Amendment message Process RFF+ABO segment Map 1154 - Sender Reference with Master Waybill>Miscellaneous>Reference Numbers>URN to identify Master Waybill Map 4000 - Sender Reference Version with Master Waybill>Miscellaneous>Reference Numbers>SRV to define the corresponding MSG-ESM message Sample segment: RFF+ABO:K00098816/PRD1::002 Process RFF+AFM segment Apply 1154 - Message Function Code (Inbound) to identify the transaction type of corresponding MSG-ESM If Message Function Code (Inbound) is 50, apply the logic clarified below. Sample segment: RFF+AFM:50 Process FTX+AHN segment in Header section Update Master Waybill>Brokerage Status>BCR based on 4440 - Status Type If Status Type is REJECTED, update BCR status to WRJ. If Status Type is WITHDRAWN, update BCR status to WTD. Store the following data to Master Waybill>Miscellaneous>Brokerage Events: 4440 - Status Type: 4440 - Status Description Example: WITHDRAWN: THE EXPORT DECLARATION OR CARGO REPORT HAS BEEN WITHDRAWN BY THE REPORTING PARTY AND MAY NOT BE DEALT WITH. Sample segment: FTX+AHN+++WITHDRAWN:THE EXPORT DECLARATION OR CARGO REPORT HAS BEEN WITHDRAWN BY THE REPORTING PARTY AND MAY NOT BE DEALT WITH. Map the following data to define the association between Master and Shipment corresponding to MSG-ESMR: Master Waybill>Number with BCR Status WST Shipment>Master Waybill>Number Update MAN status consistent with BCR status based on Status Type: If Status Type is REJECTED, update MAN status to WRJ. If Status Type is WITHDRAWN, update MAN status to WTD.

title: Process MSG-ESMR on MSG-ESM Amendment messages - Part 2
description: As a SBSS user I want SBSS to be able to process MSG-ESMR (Export Sub Manifest Response) messages from customs so that the process status in SBSS can be updated and customs feedback is visible.
acceptance_criteria: Prerequisite The current user story needs to be implemented after the following ones are finished: User Story 4764788: Process MSG-ESMR on MSG-ESM Original message User Story 6978822: Apply ICR logic for MSG-ESMR and ICONTRL messaging Remark Refer to attached excel sheet as detailed clarification for MSG-ESMR process Refer to attached text file as MSG-ESMR sample message Process MSG-ESMR on MSG-ESM Amendment message Process RFF+ABO segment Map 1154 - Sender Reference with Master Waybill>Miscellaneous>Reference Numbers>URN to identify Master Waybill Map 4000 - Sender Reference Version with Master Waybill>Miscellaneous>Reference Numbers>SRV to define the corresponding MSG-ESM message Sample segment: RFF+ABO:K00098816/PRD1::002 Process RFF+AFM segment Apply 1154 - Message Function Code (Inbound) to identify the transaction type of corresponding MSG-ESM If Message Function Code (Inbound) is 5, apply the logic clarified below. Sample segment: RFF+AFM:5 Process FTX+AHN segment in Header section Update Master Waybill>Brokerage Status>BCR based on 4440 - Status Type If Status Type is CLEAR, update BCR status to CLR. If Status Type is ERROR, update BCR status to ERR. If Status Type is REJECTED, update BCR status to REJ. If Status Type is REVOKED, update BCR status to RVK Note: Sometimes ERROR will be received along with condition, i.e., FTX+AHN+++ERROR - VALIDATION. In that case, BCR status should be updated to ERR. Store the following data to Master Waybill>Miscellaneous>Brokerage Events: 4440 - Status Type: 4440 - Status Description Example: ERROR - EXPIRED: REPORTED VALIDATION:THE GOODS COVERED BY THE DOCUMENT CANNOT BE DEALT WITH. CUSTOMS DOES NOT EXPECT FURTHER QUOTATION OF THE RELATED CAN. THE LODGED OR AMENDED INFORMATION HAS NOT PASSED THE REQUIRED EDITS. Sample segment: FTX+AHN+++CLEAR:THE GOODS COVERED BY THE DOCUMENT ARE AUTHORISED FOR EXPORT AND MAY BE DEALT WITH. Process Segment Group 4: ERP-ERC-FTX Process ERP segment to define error location corresponding to Segment Group 4 1054 - Error Location is formatted as L0 = Header, L1 to L9999 referring to the line number reported to The Department If Error Location is 0000, meaning the error is on Header level, then apply logic below: Reflect Error Description in FTX+AAO segment to Master Waybill>Miscellaneous>Brokerage Events Map the following data to define the association between error Master Waybill and shipments: Master Waybill>Number Shipment>Master Waybill>Number Update MAN Status of the associated shipments based on 4440 - Status Type in FTX+AHN segment in Header section If Header level Status Type is REJECTED, update MAN Status to REJ. Sample segment group (Master level) ERP+::0000 ERC+XM1016::95 FTX+AAO+++EXPORT DOCUMENT STATUS IS ERROR BECAUSE A SUB-MANIFEST REPORT WITH A CARGO REPORT TYPE OF C (CONSOLIDATION) HAS NO LINES If Error Location is other than 0000, meaning the error is on Line level, then apply logic below: Map Error Location with Declaration Reference Number SEQ to identify error shipment. For example, if Error Location is 0178, the error shipment should be the one with SEQ 178. Store 9321 - Error Identifier in ERC segment to ESMRED>Number of error shipment Store 4440 - Error Description in FTX+AAO segment to ESMRED>Comment of error shipment Sample segment group (Line level) ERP+::0169 ERC+XM1024::95 FTX+AAO+++LINENUM=000000000000169 IS TRYING TO QUOTE EDN=AFENRN3NW THAT HAS ALREADY BEEN TALLY EXPIRED Process CST segment Map 1496 - Line Number with SEQ to identify corresponding shipments If the value is 0001, the corresponding Shipment sequence number in SEQ should be 1. Once the shipment is identified, apply the logic clarified below on that Shipment. Sample segment: CST+0001 Process FTX+AHN segment in Line section Map the following data to define the association between Master Waybill and Shipments: Master Waybill>Number Shipment>Master Waybill>Number Update SBSS status on corresponding shipments based on 4440 - Line Status Type: If Status Type is CLEAR, update MAN status to CLR. If Status Type is ERROR, update MAN status to ERR. Map Master Waybill>Master Waybill Num with Shipment>Flow>Reference Numbers>MWB Update flow level BCR status based on logic below: Check Shipment>Flow>Reference Numbers>MWB on all corresponding shipments: Map MWB value with Master Waybill>Number If Status Type is CLEAR, add Reference Number BCRCLR to the flow. If Status Type is ERROR, add Reference Number BCRERR to the flow. Store 4440 - Line Status Type to Shipment>Summary>Customer Supplied References>ESMRSD>Number Store 4440 - Line Status Description to Shipment>Summary>Customer Supplied References>ESMRSD>Comment Sample segment: FTX+AHN+++ERROR:LINENUM=000000000000169 IS TRYING TO QUOTE EDN=AFENRN3NW THAT HAS ALREADY BEEN TALLY EXPIRED Note: the value of 4440 - Status Type in FTX+AHN stored to HSD (Header Section) and ESMRSD (Line Section) must include the entire datalike references below: ERROR - VALIDATION ERROR - SUSPENDED ERROR - EMBARGOED ERROR - EXPIRED

title: QA Story: E2E testing on MSG-ESM messaging part 1
description: As a SBSS user, I want the E2E flow for MSG-ESM outbound message submission and inbound message process to be tested based on customs regulations.
acceptance_criteria: Scope Bug fixing and enhancement required based on the following TPS regulations: MSG-ESM - Export Sub Manifest MSG-ESM Business Rules MSG-ESMR - MSG-ESM Response MSG-ESMR Business Rules Bug fixing and enhancement required based on the following features: Feature 5972642: Project-A - Export - Brokerage Cargo Reports (Manual and Automatic) - Part A Feature 6603297: Project-A - Export - Brokerage Cargo Reports (Manual and Automatic) - Part B-I and II Feature 6876845: Project-A - Export - Brokerage Cargo Reports (Manual and Automatic) - Part C (** IT Request) Improve Sender Reference format for MSG-ESM Applicable segment: BGM Applicable element: 1004 - Sender Reference SBSS mapping: Master Waybill>Miscellaneous>Reference Numbers>URN Relevant user stories: User Story 6987274: Improvement of MSG-ESM messaging based on SP10.1 review Feedback from BPO on SPI10.2: The current format of Sender Reference applied for MSG-EXP and MSG-ESM are just the same. The data could be duplicated to cause potential risk. Improvement requirement: When Sender Reference needs to be assigned to a Master Waybill to trigger MSG-ESM message, update the first two characters from AU to MW. Ensure the data assigned to the following SBSS mappings will not be duplicated: Master Waybill>Miscellaneous>Reference Numbers>URN Declaration>Customs>Reference Numbers>URN Data format: an..35 Improve generation logic of Transport Type Once Export Country of a Master Waybill is set to AU, check Transport Type of the Master. If Transport Type does not have a value, generate A as default value from system side. If Transport Type has a value, no change on the value from system side. Improve TRS mapping logic When the following conditions are met: Declaration>Customs>Reference Numbers>EAC is AU MAN status is RDY Validate SBSS mappings below:. Clearance Type TRS Shipment>Summary>Reference Numbers>TRS If CT is TRS but Reference Number TRS is not added, raise an error: Shipment Reference Number TRS is Mandatory when CT is TRS. If CT is TRS and Reference Number TRS is added, map 1154 - Customs Authority Number of RFF segment of MSG-ESM to TRS. Improve CNT values generation and validation logic Fix MRN issue Applicable element: UHN - 0062 - Message Reference Number Population logic: Fixed value 1 Improve warning and error logic for MSG-ESM validation On shipment level validation When MAN status is changed to RDY and the shipment is saved, trigger MSG-ESM Line level validation. If validation pass, change MAN status to PAS. If validation fail, change MAN status to FAI. Upon MANS status FAI, raise a popup window showing validation error detail. Remove the logic of adding validation error detail to Shipment Comment FAI. On Master level validation When BCR status is changed to RFC, AMD or WID and the Master Waybill is saved, trigger MSG-ESM Header level validation. If validation pass, trigger MSG-ESM message. If validation fail, change BCR status to FAI. Upon BCR status FAI, raise a popup window showing validation error detail. Remove the logic of adding validation error detail to Master Waybill Reference Numbers or Brokerage Events. Note: Other requirements or bugs need to be added to this story based on E2E testing.

title: QA Story: E2E testing on MSG-ESM messaging part 2
description: As a SBSS user, I want the E2E flow for MSG-ESM outbound message submission and inbound message process to be tested based on customs regulations.
acceptance_criteria: Scope Bug fixing and enhancement required based on the following TPS regulations: MSG-ESM - Export Sub Manifest MSG-ESM Business Rules MSG-ESMR - MSG-ESM Response MSG-ESMR Business Rules Bug fixing and enhancement required based on the following features: Feature 5972642: Project-A - Export - Brokerage Cargo Reports (Manual and Automatic) - Part A Feature 6603297: Project-A - Export - Brokerage Cargo Reports (Manual and Automatic) - Part B-I and II Feature 6876845: Project-A - Export - Brokerage Cargo Reports (Manual and Automatic) - Part C (** IT Request) 1.Remove logic below post MSG-ESM submission Map MWB value with Master Waybill>Number with BCR Status SNT If the data above are consistent, add Reference Numbers>BCRSNT to the flow. 2.The verification of the MAWB level failed; The value of BCR should be changed to FAI. If all shipments bound to the MAWB fail verification, the message cannot be successfully triggered on the MAWB page. 3.Updated trigger point EAC mapping for MSG-ESM normal message When MSG-ESM Original or Amendment message is triggered, check CT type on applicable shipments. If CT is other TRS, cover the following condition in message trigger points: Country Code (the first two characters) in Declaration>Customs>Reference Number>EAC is AU If CT is TRS, don't cover EAC condition above in message trigger points. Apart from EAC, other trigger conditions clarified in User Story 6930194 and 6623955 also need to be covered. 4.Update validation logic of RFF elements Applicable elements: RFF+TL: 1154 - Export Declaration Exemption Code RFF+TN: 1154 - Customs Authority Number When MSG-ESM shipment level data validation is triggered upon MAN status RDY, check CT type. If CT is other than TRS, check the following SBSS mappings: Shipment>Summary>Reference Numbers>CAN Declaration>Customs>Reference Numbers>EDEC If either mapping above is added with a value, pass validation on the element. If both CAN and EDEC values are not added: Validation fail and change MAN status to FAI Raise an error: Either Customer Authority Number or Export Declaration Exemption Code is required for MSG-ESM message. If CT is TRS, check if Shipment>Summary>Reference Numbers>TRS value is added. If TRS value is added, pass validation on the element. If TRS value is not added: Validation fail and change MAN status to FAI Raise an error: TRS number is mandatory for MSG-ESM on Transhipment. When MAN status is changed to RDY, no hard code, like TL or TN, is required for data validation on RFF elements. Only validate the value availability from applicable SBSS mapping. 5.Improve Sender Reference format for MSG-ESM Applicable segment: BGM Applicable element: 1004 - Sender Reference SBSS mapping: Master Waybill>Miscellaneous>Reference Numbers>URN Relevant user stories: User Story 6987274: Improvement of MSG-ESM messaging based on SP10.1 review Feedback from BPO on SPI10.2: The current format of Sender Reference applied for MSG-EXP and MSG-ESM are just the same. The data could be duplicated to cause potential risk. Improvement requirement: When Sender Reference needs to be assigned to a Master Waybill to trigger MSG-ESM message, update the first two characters from AU to MW. Ensure the data assigned to the following SBSS mappings will not be duplicated: Master Waybill>Miscellaneous>Reference Numbers>URN Declaration>Customs>Reference Numbers>URN Data format: an..35 6.Update mapping logic of CONTRL and corresponding MSG-ESM When an error CONTRL needs to be processed, map two messages based on logic below: Map the following data to identify corresponding Master Waybill: The value of 0020 - Interchange Control Reference Number (Inbound) in UCI segment of CONTRL The data in Master Waybill>Miscellaneous>Reference Numbers>IRN If 0020 value in CONTRL message starts with an extra 0, exclude the extra 0 in mapping logic. Map the following data to identify corresponding outbound message: The value of 0065 - Message Type Identifier in UCM segment of CONTRL message The data in Master Waybill>Miscellaneous>Reference Numbers>MTI Note: Apart from the update highlighted above, keep other requirement for CONTRL process in User Story 6901976. 7.Fix the issue that MSG-ESM response messages fail to be processed Issue clarification: Refactor Message Analyzer (BCR Status change based on the response) Action items: @Liu Dan (DGB9NQP) to add details in comment and fix the issue from coding side @Yang Chaodan (SBJ1ZVZ) follow Liu Dan's comment for QA implementation 8.Update the mapping of CNI value Applicable element: CNI: 1490 - Line Number Current mapping: Declaration>Customs>Reference Numbers>SEQ Updated mapping: Declaration>Customs>Reference Numbers>DSQ

title: QA Story: E2E testing on MSG-ESM messaging part 3
description: As a SBSS user, I want the E2E flow for MSG-ESM outbound message submission and inbound message process to be tested based on customs regulations.
acceptance_criteria: Scope Bug fixing and enhancement required based on the following TPS regulations: MSG-ESM - Export Sub Manifest MSG-ESM Business Rules MSG-ESMR - MSG-ESM Response MSG-ESMR Business Rules Bug fixing and enhancement required based on the following features: Feature 5972642: Project-A - Export - Brokerage Cargo Reports (Manual and Automatic) - Part A Feature 6603297: Project-A - Export - Brokerage Cargo Reports (Manual and Automatic) - Part B-I and II Feature 6876845: Project-A - Export - Brokerage Cargo Reports (Manual and Automatic) - Part C (** IT Request) Update mapping logic of CONTRL and corresponding MSG-ESM When an error CONTRL needs to be processed, map two messages based on logic below: Map the following data to identify corresponding Master Waybill: The value of 0020 - Interchange Control Reference Number (Inbound) in UCI segment of CONTRL The data in Master Waybill>Miscellaneous>Reference Numbers>IRN If 0020 value in CONTRL message starts with an extra 0, exclude the extra 0 in mapping logic. Map the following data to identify corresponding outbound message: The value of 0065 - Message Type Identifier in UCM segment of CONTRL message The data in Master Waybill>Miscellaneous>Reference Numbers>MTI Note: Apart from the update highlighted above, keep other requirement for CONTRL process in User Story 6901976. Fix the issue that MSG-ESM response messages fail to be processed Issue clarification: Refactor Message Analyzer (BCR Status change based on the response) Action items: @Liu Dan (DGB9NQP) to add details in comment and fix the issue from coding side @Yang Chaodan (SBJ1ZVZ) follow Liu Dan's comment for QA implementation Update trigger points of MSG-ESM messaging The requirement below is to correct the logic in the following user stories: User Story 6930194: Trigger MSG-ESM Original message - Part 2 User Story 6623955: Trigger MSG-ESM Amendment and Withdrawal messages User Story 6978897: Implement validation logic on MSG-ESM message - Part 3 When MSG-ESM Original or Amendment message is triggered, remove validation on the following conditions on shipment level: Country Code (the first two characters) in Declaration Reference Number EAC is AU Declaration Reference Number CCN is available CUS status is CLR or AAC CT is ABK/DEM/FML/LND/TRS When MAN status is changed to RDY, check the following condition: Country Code (the first two characters) in Declaration Reference Number EAC is AU if it's available Export Country is AU otherwise If EAC value includes AU or Export Country is AU, start MSG-ESM shipment level data validation with the following logic: If CT is FML, start validation when both conditions below are met: Declaration Reference Numbers CCN is available CUS status is CLR or AAC If CT is ABK, DEM, LND or TRS, start validation without both conditions above. Reflect Sender Reference from Master to Shipment Add new reference in SBSS Admin with script SBSS Admin table: Declaration Ref Type Data to be added: Code Description Print Code EDI Code URM MAWB Unique Reference Number Once MSG-ESM Original message is sent from Master Waybill, reflect the following data to all shipments included in the message: Source mapping: Master Waybill>Miscellaneous>Reference Numbers>URN Destination mapping: Declaration>Customs>Reference Numbers>URM Change the column tile "MAWB & SEQ" of AU Rating List to “MAWB & SEQ & URM”. Upon Declaration Reference Number URM availability, reflect URM value at the end of “MAWB & SEQ & URM” unit of corresponding shipment on Rating List as below: ServiceCategory MAWB & SEQ & URM Brokerage Representative SML 4067668094 / 002 / MW3658 /Ntsa Ntsa SML {} /Ntsa Ntsa SML {} /Ntsa Ntsa Update segment structure of NAD+GO Applicable elements: 3039 - Goods Owner Party Id 3055 - Code list responsible agency code 3036 - Owner Name Update requirement: Element 3055 (fixed value 95) is only required when element 3039 is included in NAD+95 segment For example: NAD+GO+AAA3437936M::95 When element 3036 is included in NAD+GO segment, element 3055 should be excluded. For example: NAD+GO+++BUSH BARRIER' Insert GID+1 between repeated RFF segments Based on CW1 samples and TPS approval, when RFF in Segment Group 8 is repeated, trigger segment GID+1 should be inserted in between like reference below: RFF+TL:EXLV' GID+1' RFF+HWB:1ZAA00356793546561' Apply warning on shipment data validation When MSG-ESM shipment level data validation fail, raise a warning instead of error to display validation details. The shipment should be stored successfully regardless of validation result Update mapping and validation logic of RFF segments Update the mapping of RFF+TN: 1154 - Customs Authority Number based on CT type: If CT is FML, map to Declaration>Customs>Reference Numbers>CCN If CT is TRS, map to Shipment>Summary>Reference Numbers>TRS If CT is other than FML or TRS, map to Shipment>Summary>Reference Numbers>CAN When MSG-ESM shipment level data validation is triggered, check CT type. If CT is FML, skip validation on RFF since CCN is already covered in data validation trigger points of FML shipments. If CT is TRS, check Shipment Reference Number TRS. If TRS is added with a value, validation pass on RFF. If TRS value is not added, validation fail and raise a warning: TRS number is required for Transhipment. If CT is other than FML or TRS, check the following SBSS mappings: Shipment>Summary>Reference Numbers>CAN Declaration>Customs>Reference Numbers>EDEC If either mapping above is added with a value, validation pass on RFF. If both CAN and EDEC values are not added, validation fail and raise a warning: Either Customer Authority Number or Export Declaration Exemption Code is required for MSG-ESM message. The updates above should cover both MSG-ESM Original and Amendment messages Apply specific validation on CCAN Applicable element: RFF+AHV: 1154 - Contingency Customs Authority Number SBSS mapping: Shipment Reference Numbers CCAN Data validation logic: Only mandatory when the value of RFF+TL: 1154 - Export Declaration Exemption Code (mapped to Declaration Reference Number EDEC) is EXCC When any condition below is met, validation pass on RFF+AHV EDEC value is EXCC and CCAN is added with a value with 14 characters EDEC value is other than EXCC (In this case, CCAN should not be included no matter CCAN is added or not) When any condition below is met, validation fail on RFF+AHV EDEC value is EXCC and CCAN value is missing. In this case, raise a warning: Contingency Customs Authority Number is required when Export Declaration Exemption Code is EXCC. EDEC value is EXCC and CCAN value is not with 14 characters. In this case, raise a warning: Contingency Customs Authority Number must be 14 characters. Update mapping logic of NAD segment Applicable elements: NAD+GO: 3039 - Goods Owner Party Id NAD+GO: 3036 - Owner Name Applicable mappings: Goods Owner Party Id: Declaration>Customer>Shipper>Reference Numbers>TIN if it has a value, OID otherwise. Owner Name: Declaration>Customer>Shipper>Shipper Name Validation logic on NAD+GO: When MSG-ESM shipment level data validation is triggered, validate if TIN or OID is available first If both TIN or OID are not added, then validate if Shipper Name is available Validation pass if any of TIN, OID or Shipper Name is available Validation fail if none of TIN, OID or Shipper Name is available. In this case, raise a warning: TIN/OEM Client ID or Shipper Name is required for MSG-ESM message Update the content of validation reminder When MSG-ESM Master or Shipment level data is validation failed, only include data name, like Export Declaration Exemption Code, in warning or error content, no need to include specific SBSS mapping. Add the logic to differentiate Master and Shipment Interchange Control Reference Number When an Interchange Control Reference Number needs to be generated on a Master Waybill from system side, the sequence number should starts from 500. Therefore, when a CONTRL message is received, SBSS can clearly define if it corresponds to a Master Waybill or a Shipment. Update the mapping of Sender Reference Add new Reference Number in Admin with script SBSS Admin table: Reference Number Type Data to be added: Reference Number Type Parent Type Description URM MW Sender Reference When URM is added in Admin, update the mapping in MSG-ESM as below: Applicable element: 1004 - Sender Reference in BGM segment Updated mapping: Master Waybill>Miscellaneous>Reference Numbers>URM Note: the mapping update should cover Original, Amendment and Withdrawal messages. When MSG-ESMR is received, map 1154 - Sender Reference with Master Waybill>Miscellaneous>Reference Numbers>URM to identify Master Waybill.

title: QA Story: E2E testing on MSG-ESM messaging part 4
description: As a SBSS user, I want the E2E flow for MSG-ESM outbound message submission and inbound message process to be tested based on customs regulations.
acceptance_criteria: ope Bug fixing and enhancement required based on the following TPS regulations: MSG-ESM - Export Sub Manifest MSG-ESM Business Rules MSG-ESMR - MSG-ESM Response MSG-ESMR Business Rules Bug fixing and enhancement required based on the following features: Feature 5972642: Project-A - Export - Brokerage Cargo Reports (Manual and Automatic) - Part A Feature 6603297: Project-A - Export - Brokerage Cargo Reports (Manual and Automatic) - Part B-I and II Feature 6876845: Project-A - Export - Brokerage Cargo Reports (Manual and Automatic) - Part C (** IT Request) Remove invalid Reference Number in Admin with script Remove existing Reference Number in Admin with script SBSS Admin table: Reference Number Type Data to be removed: Reference Number Type Parent Type Description URN MW Sender Reference Update mapping and validation logic of RFF segments Fix RFF structure issue when CT is DEM or LND Based QA test, when all conditions below are met: CIM is C CT type is DEM or LND Declaration Reference Number EDEC is added with value EXLV RFF+TN is included in the message without value as below: