Project-A - Import / Export - TIN and OEM Client ID (Customs Client ID - Individual) PI08 Validation (3)

**** This new feature is created per IT email request to veer away from umbrella features and accommodate new user stories added by team ITPOs as the scope of MSG-EXP, MSG-EXPR, and TIN/OEM Client ID features expands due to ongoing discussions and validation of these messages. A gap has been identified where the TIN (mapped on Tax ID field) resolves the TIR hold, but OEM Client ID (mapped on CZ/FW# field) does not resolve the TIR hold. Related User Story → User Story 4976163: OID Removal from TAXID and TIN/OID consider from customer accounts --------------------------------------------------------- This feature is to allow SBSS to comply with the AU Customs requirement of Customs Client IDs for shippers, importers and exporters (both individuals and organizations) which enables entry submission. OEM Client ID efforts are under Feature 5321174: Client registration integration with Customs for OEM Client ID (incl message visibility) Are trigger points required? On download, system to check for profile match including OEM Client ID, and either auto submits a OEM Client ID application or warns the user that a profile is not registered. User can manually submit an application via Custom Action. Enhancements to the custom action screen to accommodate new requirements for the OEM Client ID submission. * * Requirement added subsequent to Planning; to be investigated in Task 5952679: OEM Client ID screen to be modified under what conditions?.

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 - Import / Export - TIN and OEM Client ID (Customs Client ID - Individual) PI08 Validation (3) — Feature Brief
content: ## 1. Feature Title and Business Need

**Feature**: Australian Customs Client Registration and Validation Enhancement

**Business Need**: 
Customs Border Force (CBF) requires all parties involved in import/export transactions (importers, exporters, suppliers) to be registered with validated Customs Client IDs (OEM Client ID) and/or Australian Business Numbers (TIN) before declarations can be submitted. Currently, SBSS lacks comprehensive validation and management capabilities for these registration requirements, leading to declaration rejections, processing delays, and manual intervention requirements.

This feature implements the complete lifecycle for customs client registration: automated validation of party identifiers, submission of registration applications (MSG-CLR messages), processing of registration responses (MSG-CLRR and CLNTDUP messages), and conditional declaration holds based on identifier presence/absence.

## 2. Business Objectives

1. **Regulatory Compliance**: Ensure 100% compliance with CBF requirements for party registration before declaration submission
2. **Reduce Declaration Rejections**: Eliminate rejections caused by missing or invalid OEM Client ID/TIN identifiers
3. **Automate Registration Workflow**: Enable automatic submission of client registration applications when identifiers are missing
4. **Improve Data Quality**: Implement comprehensive validation of Australian addresses (postal codes, cities, address completeness) to prevent routing errors and interventions
5. **Enhance Visibility**: Provide brokers with clear feedback on registration status and error conditions through UI notifications and status tracking
6. **Minimize Manual Intervention**: Automatically resolve TIR (Tax ID Required) holds when valid OEM Client ID or TIN is provided

## 3. Scope

### In Scope

**Party Registration Management**:
- OEM Client ID and TIN capture and storage at both declaration and customer profile levels
- Automated MSG-CLR message generation and submission for individuals and organizations
- Processing of MSG-CLRR (registration response with errors) and CLNTDUP (duplicate registration notification) messages
- Mapping registration identifiers to appropriate party roles (Importer, Exporter, Supplier)
- Support for multiple registration applications per shipment (import scenarios with both Importer and Supplier requiring registration)

**Address Validation**:
- Australian postal code and city validation against master town reference data
- Metropolitan (MET) vs Non-Metropolitan (NMT) classification based on postal code province
- Address completeness validation for Australian and overseas addresses
- Intervention placement for invalid or incomplete addresses

**Hold and Status Management**:
- RAT hold (TIR - Tax ID Required) conditional logic based on OEM Client ID/TIN presence
- Brokerage Status OID tracking (RFC, SNT, SCR, CMP, ERR) throughout registration lifecycle
- Shipment Brokerage Status (MET/NMT/NIL) based on postal code validation results
- Automatic hold removal when valid identifiers are provided

**Response Handling**:
- Error message capture and display from MSG-CLRR responses
- Duplicate registration notification processing from CLNTDUP messages
- Synchronization of registration data between shipments and customer profiles
- Remark popup notifications for registration errors when shipments are opened

### Out of Scope

- Modification of existing declaration submission logic (INPDEC/IPTDEC/OUTDEC message structure)
- Changes to tariff calculation or duty assessment rules
- Integration with external customer master data management systems beyond SBSS customer profiles
- Retrospective correction of historical shipments with missing OEM Client ID/TIN
- Automated customer profile creation (registration data stored on existing profiles only)

## 4. Stakeholders and Actors

**Primary Users**:
- **Customs Brokers (BRK)**: Submit registration applications, resolve registration errors, validate addresses, clear TIR holds
- **Compilers (COM)**: Prepare declarations ensuring OEM Client ID/TIN completeness before broker review
- **Administrators (ADM)**: Configure address validation rules, monitor registration application volumes, troubleshoot error patterns

**External Systems**:
- **Customs Border Force TPS**: Receives MSG-CLR applications, returns MSG-CLRR responses and CLNTDUP notifications
- **SBSS Customer Profiles**: Source and destination for OEM Client ID/TIN master data
- **Master Town Reference Database**: Authority for Australian postal code and city validation

**Impacted Parties**:
- **Importers of Record**: Must have valid OEM Client ID or TIN to clear formal (FML) import declarations
- **Exporters/Shippers**: Must have valid OEM Client ID or TIN for formal export declarations and as Suppliers on import transactions
- **Carrier Co Operations**: Benefit from reduced interventions and faster clearance times

## 5. Dependencies

**Technical Dependencies**:
- EDIFACT message gateway connectivity to TPS for MSG-CLR/MSG-CLRR/CLNTDUP transmission
- Master town reference data table must include province classification (MET/NMT) for Australian postal codes
- Customer profile comment infrastructure must support OID, TIN, and CLS (Client Sent) comment types
- Declaration customer reference number infrastructure must support OID and TIN reference types
- Brokerage Status OID must be added to shipment status tracking model

**Data Dependencies**:
- Carrier Co Account associations on customer profiles required to determine matched vs unmatched customer scenarios
- Shipment type determination (Import/Export) based on Import Country and Export Country fields
- Movement number, flight/vessel details, and port codes must be populated for message mapping
- Travel document numbers and country of issue data required for individual MSG-CLR applications

**Process Dependencies**:
- Address entry must occur before postal code validation triggers
- Forecast status (FOR) may need to reach CMP before MSG-CLR submission in certain scenarios
- RAT rating completion prerequisite for TIR hold logic to evaluate
- MSG-CLR message must be sent before MSG-CLRR response can be processed
- Customs officer review of MSG-CLR application before MSG-CLRR/CLNTDUP is issued

## 6. Success Criteria

**Functional Success**:
- 100% of formal import/export declarations have valid OEM Client ID or TIN on required parties before submission
- MSG-CLR messages successfully transmit to TPS with all mandatory segments and elements populated
- MSG-CLRR error messages automatically populate remark popups visible to brokers on shipment open
- TIR holds automatically clear when OEM Client ID or TIN is added to Importer/Exporter profiles or declarations
- Postal code validation correctly assigns MET/NMT/NIL shipment brokerage status on every address change
- Address validation interventions trigger for all incomplete Australian and overseas addresses

**Operational Success**:
- 90% reduction in declaration rejections due to missing OEM Client ID/TIN within 30 days of deployment
- 50% reduction in manual interventions for address-related routing errors
- Zero duplicate MSG-CLR submissions for customers with existing CLS (Client Sent) or registered OEM Client ID/TIN
- Average registration approval time (MSG-CLR submission to MSG-CLRR receipt) tracked and visible in reporting

**Data Quality Success**:
- OEM Client ID and TIN stored consistently in both customer profiles and declaration references
- No orphaned registration data (CLS comment without corresponding MSG-CLR message URN)
- Sender Reference Version correctly differentiates Importer vs Supplier MSG-CLR messages on import shipments
- Role Name (IMPORTER, EXPORTER, SUPPLIER) captured accurately in customer supplied references

## 7. Assumptions and Risks

### Assumptions

1. **CBF Response Timeliness**: MSG-CLRR responses will be received within 24-48 hours of MSG-CLR submission under normal circumstances
2. **Master Town Data Quality**: The master town reference table is current and complete for all Australian postal codes
3. **Customer Profile Integrity**: Carrier Co Account fields on customer profiles are populated and accurate for all active trading partners
4. **Single Currency Declarations**: While the platform supports multi-currency invoices, MSG-CLR registration logic assumes declaration totals are already converted to AUD
5. **User Training**: Brokers will receive training on new OEM Client ID form fields, error remark interpretation, and TIR hold resolution procedures
6. **Business Address as Default**: For organizations, Business Address (BA) is the appropriate default address type in 95%+ of cases

### Risks

| Risk | Impact | Likelihood | Mitigation |
|------|--------|-----------|------------|
| **CBF Schema Changes**: TPS updates MSG-CLR/MSG-CLRR message structure without notice | High | Medium | Implement version detection logic; monitor CBF technical bulletins; maintain test message library for regression validation |
| **Duplicate Profile Data**: Same customer appears in multiple profiles with different Carrier Co Accounts, causing inconsistent OEM Client ID/TIN storage | Medium | High | Implement profile matching algorithm based on Tax ID, TIN, and Name; provide admin tool to merge duplicate profiles |
| **Postal Code Master Data Lag**: New suburbs or postal code reassignments not reflected in master town table | Medium | Medium | Establish monthly refresh schedule for master town data; provide override capability for brokers to manually set MET/NMT |
| **MSG-CLR Rejection Loop**: Registration application repeatedly rejected for same customer due to data quality issue | Medium | Low | Capture and display full error text from MSG-CLRR; provide escalation path to compliance team; implement "do not auto-retry" flag after 3 failures |
| **Performance Degradation**: Address validation on every keystroke causes UI lag on high-volume shipment entry | Low | Medium | Implement validation only on tab-out/field blur events; consider debounce logic for rapid data entry |
| **Import Supplier OEM Client ID Ambiguity**: Business rules unclear whether Supplier OEM Client ID is mandatory for all import shipments or only specific commodity types | High | Low | Confirm with CBF policy team; document conditional logic clearly; provide configuration toggle if requirement varies by clearance type |

### Key Constraints

- **Message Size Limits**: TradeNet EDIFACT messages limited to 50 commodity lines per declaration (existing constraint, not specific to this feature but relevant for consolidated shipments with multiple suppliers)
- **Comment Field Character Limits**: Customer profile comment text fields limited to 255 characters; MSG-CLRR error messages may exceed this and require truncation
- **Regulatory Retention**: MSG-CLR/MSG-CLRR message audit trail must be retained for 5 years per CBF record-keeping requirements
- **Address Type Restrictions**: CBF currently supports only Business Address (BA) and Postal Address (PA); additional types (e.g., registered office, trading address) not permitted in MSG-CLR schema

---

## 8. High-Level Feature Workflow

### Registration Application Scenario (Export - Organization)

1. Broker enters export declaration for shipment with Shipper (Exporter) party
2. SBSS detects Shipper has Carrier Co Account but no OEM Client ID or TIN on profile, and no CLS comment
3. Broker opens OEM Client ID form, selects "Organization" and "Exporter" role, enters shipper business details (name, address, contact)
4. Broker selects "Business Address" as address type, enters TIN (if applicable)
5. On submit, SBSS:
   - Generates Declaration Comment CCO ("Client - Company - Organization") with Address Type and TIN embedded
   - Constructs MSG-CLR message with BGM, RFF+TIN, FTX+ATY, FTX+CNP, FTX+CAT, MEA+RN, TDT+1, CNI+1, RFF+1, GID+1 segments
   - Submits message to TPS
   - Sets Brokerage Status OID to SNT
   - Adds CLS comment to Shipper profile with URN (unique reference number from Declaration > Customs > Reference Numbers)
6. SBSS receives MSG-CLRR response:
   - If approved (CNT+55 Total Comments = 0): Stores OEM Client ID in FTX+CCI segment to Shipper profile > Comments > OID, sets OID status to CMP
   - If rejected (CNT+55 > 0): Stores error text from FTX+AAO segments to Customer Supplied References > CLREGRED, sets OID status to ERR, displays remark popup on next shipment open

### TIR Hold Resolution Scenario (Import - Formal Entry)

1. Import shipment downloads with Importer party, Clearance Type = FML
2. Broker opens declaration in Full Turbo, navigates to Address > Importer
3. Tax ID field is blank, FZ/CW# (OEM Client ID) field is blank
4. On save, SBSS adds RAT Hold Reason TIR, sets RAT status to HLD
5. Broker retrieves TIN from customer records, enters in Tax ID field
6. On save, SBSS detects Tax ID is now populated, removes TIR hold, sets RAT to CMP (or per segregation logic)
7. Alternatively: Broker submits MSG-CLR for Importer, receives OEM Client ID in MSG-CLRR response, SBSS auto-populates FZ/CW# from profile, TIR hold auto-clears

### Address Validation Scenario (Australian Metropolitan)

1. Broker enters Import shipment, Importer address Country = AU
2. Broker enters Postal Code "3000", City "MELBOURNE"
3. On tab-out, SBSS queries master town table, finds match: Postal Code 3000, City MELBOURNE, Province = MET
4. SBSS sets Shipment Brokerage Status = MET
5. Broker modifies Postal Code to "9999" (invalid)
6. On tab-out, SBSS queries master town table, finds no match
7. SBSS sets Shipment Brokerage Status = NIL, places shipment in Intervention queue, adds remark "AU ADDRESS WITH INVALID POSTAL CODE"

---

This feature brief provides the business justification and high-level scope for the enhancement. The accompanying Technical Specification details the message structures, data mappings, validation rules, and processing logic required for implementation.

title: Project-A - Import / Export - TIN and OEM Client ID (Customs Client ID - Individual) PI08 Validation (3) — Technical Specification
content: **Version**: 1.0  
**Platform**: SBSS (Brokerage Operations Support System)  
**Regulatory Authority**: Customs Border Force (CBF)  
**Message Standards**: UN/EDIFACT, TPS Schema  
**Related Platform Documentation**: See Platform Knowledge §2.3 for TPS message patterns, §4 for SBSS data model entities

---

## 1. Message Format & Segment Reference

This section provides a unified reference for all EDIFACT message types used in customs client registration. Business Analysts must cross-reference this table to determine which segments apply to specific registration scenarios (Individual vs Organization, Importer vs Exporter vs Supplier).

### 1.1 Outbound Message: MSG-CLR (Client Registration Application)

**Message Function**: Submit client registration application to CBF for OEM Client ID or TIN validation

**Trigger Conditions**: See §5.2 for business rule matrix determining when MSG-CLR is submitted

| Segment | Element | Code | Description | Format | Mandatory | Conditional | Applies To |
|---------|---------|------|-------------|--------|-----------|-------------|------------|
| UNH | 0062 | - | Message reference number | n..14 | M | - | All |
| UNH | 0065 | MSG-CLR | Message type identifier | an..6 | M | - | All |
| BGM | 1004 | 351 | Document name code (Registration application) | an..3 | M | - | All |
| BGM | 1056 | - | Sender Reference Version | n..3 | M | - | All (see §1.1.1) |
| RFF+TIN | 1153 | TIN | Reference code qualifier | an..3 | C | Only for ORG role when TIN provided | ORG |
| RFF+TIN | 1154 | - | Australian Business Number | an..11 | C | If RFF+TIN included | ORG |
| RFF+TIN | 4000 | - | CAC Address Type (deprecated term, actually Address Type) | an..3 | C | If RFF+TIN included | ORG |
| FTX+ATY | 4451 | ATY | Text subject code qualifier (Address Type) | an..3 | M | - | All |
| FTX+ATY | 4453 | - | Address Type | an..3 | M | - | All (BA or PA) |
| FTX+ATY | 4440 | - | Address Line 1 | an..70 | M | - | All |
| FTX+ATY | 4440 | - | Address Line 2 | an..70 | O | - | All |
| FTX+ATY | 4440 | - | Suburb/City | an..35 | M | - | All |
| FTX+ATY | 4440 | - | State/Province | an..9 | M | - | All |
| FTX+ATY | 4440 | - | Postal Code | an..9 | M | - | All |
| FTX+ATY | 4440 | - | Country Code | an..2 | M | - | All |
| FTX+CNP | 4451 | CNP | Text subject code qualifier (Contact Name and Purpose) | an..3 | M | Only for ORG with TIN | ORG |
| FTX+CNP | 4440 | - | Contact Name | an..70 | M | If FTX+CNP included | ORG |
| FTX+CNP | 4440 | - | Contact Purpose | an..70 | M | If FTX+CNP included | ORG |
| FTX+CAT | 4451 | CAT | Text subject code qualifier (Contact Address Type) | an..3 | M | - | All |
| FTX+CAT | 4453 | - | Contact Address Type | an..3 | M | - | All (BA or PA) |
| FTX+CAT | 4440 | - | Contact Address Line 1 | an..70 | M | - | All |
| FTX+CAT | 4440 | - | Contact Address Line 2 | an..70 | O | - | All |
| FTX+CAT | 4440 | - | Contact Suburb/City | an..35 | M | - | All |
| FTX+CAT | 4440 | - | Contact State/Province | an..9 | M | - | All |
| FTX+CAT | 4440 | - | Contact Postal Code | an..9 | M | - | All |
| FTX+CAT | 4440 | - | Contact Country Code | an..2 | M | - | All |
| MEA+RN | 6311 | RN | Measurement attribute code (Role Name) | an..3 | M | - | All |
| MEA+RN | 6154 | - | Role Name | an..35 | M | - | All (see §1.1.2) |
| TDT+1 | 8051 | 1 | Transport stage code qualifier | an..3 | C | Only if LOC+ZZZ present AND client type = ORG | ORG |
| CNI+1 | 7001 | 1 | Consolidation item number | n..6 | M | Client type = ORG | ORG |
| RFF+1 | 1153 | (varies) | Reference code qualifier | an..3 | M | Client type = ORG | ORG |
| GID+1 | 1496 | 1 | Goods item number | n..5 | M | Client type = ORG | ORG |
| LOC+DN | 3227 | DN | Location code qualifier (Document Number) | an..3 | C | Client type = IND | IND |
| LOC+DN | 3225 | - | Document Number | an..35 | C | If LOC+DN included | IND |
| LOC+ISS | 3227 | ISS | Location code qualifier (Issuing Country) | an..3 | C | Client type = IND | IND |
| LOC+ISS | 3225 | - | Country Of Issue | an..2 | C | If LOC+ISS included | IND |
| AUT+GE | 9280 | GE | Validation key identifier (Gender) | an..3 | C | Client type = IND | IND |
| AUT+GE | 9282 | - | Gender code | an..3 | C | If AUT+GE included | IND |
| DTM+329 | 2005 | 329 | Date/time/period code qualifier (Date of Birth) | an..3 | C | Client type = IND | IND |
| DTM+329 | 2380 | - | Date of Birth | an..35 | C | If DTM+329 included | IND |

#### 1.1.1 Sender Reference Version Logic

**Purpose**: Differentiate multiple MSG-CLR messages on the same import shipment (one for Importer, one for Supplier)

**Derivation Rules**:
- First MSG-CLR message for a shipment: BGM-1056 = "1"
- Second MSG-CLR message for a shipment: BGM-1056 = "2"
- Export shipments: Always "1" (only one MSG-CLR per export shipment, for Shipper/Exporter)
- Import shipments: "1" for first party registered (typically Importer), "2" for second party (typically Supplier)

**Storage**: Declaration > Misc > Customer Supplied References > CLREGSRV > Number

#### 1.1.2 Role Name Values

**Allowed Values**:
- IMPORTER: Party importing goods into Australia (import shipments only)
- EXPORTER: Party exporting goods from Australia (export shipments only)
- SUPPLIER: Foreign party supplying goods to Australian importer (import shipments only, maps to Shipper in SBSS)

**Capitalization**: MUST be stored in all uppercase in Customer Supplied References

**Selection Logic**:
- Export shipment + Shipper registration → "EXPORTER"
- Import shipment + Importer registration → "IMPORTER"
- Import shipment + Shipper registration → "SUPPLIER"

**Storage**: Declaration > Misc > Customer Supplied References > CLREGSRV > Comment

---

### 1.2 Inbound Message: MSG-CLRR (Client Registration Response with Errors)

**Message Function**: Receive registration application result from CBF, including error details if application rejected

**Processing Logic**: See §4 for status update rules, §6 for error display requirements

| Segment | Element | Code | Description | Format | Mandatory | Conditional | Processing Note |
|---------|---------|------|-------------|--------|-----------|-------------|-----------------|
| UNH | 0062 | - | Message reference number | n..14 | M | - | - |
| UNH | 0065 | MSG-CLRR | Message type identifier | an..6 | M | - | - |
| BGM | 1004 | 352 | Document name code (Registration response) | an..3 | M | - | - |
| RFF+ABO | 1153 | ABO | Reference code qualifier (Sender Reference) | an..3 | M | - | - |
| RFF+ABO | 1154 | - | Sender Reference (URN from original MSG-CLR) | an..35 | M | - | Match to Declaration > Customs > Reference Numbers > URN |
| RFF+ABO | 4000 | - | Sender Reference Version | n..3 | M | Import only | Match to CLREGSRV > Number to identify which MSG-CLR this response corresponds to |
| FTX+CCI | 4451 | CCI | Text subject code qualifier (Customs Client ID) | an..3 | C | If OEM Client ID assigned | - |
| FTX+CCI | 4441 | - | Customs Client Id | an..11 | C | If FTX+CCI present | Store per §2.2 |
| FTX+TIN | 4451 | TIN | Text subject code qualifier (TIN) | an..3 | C | If TIN validated | - |
| FTX+TIN | 4441 | - | Australian Business Number | an..11 | C | If FTX+TIN present | Store per §2.2 |
| CNT+55 | 6069 | 55 | Control total type code qualifier (Total Comments) | an..3 | M | - | - |
| CNT+55 | 6066 | - | Total Comments | n..18 | M | - | 0 = success, >0 = errors present |
| FTX+AAO | 4451 | AAO | Text subject code qualifier (Error Message Text) | an..3 | C | If CNT+55 > 0 | - |
| FTX+AAO | 4440 | - | Message Text | an..512 | C | Multiple instances allowed | Store each message text as separate CLREGRED item per §6.1 |

**Message Matching**:
- Match RFF+ABO-1154 (Sender Reference) to Declaration > Customs > Reference Numbers > URN
- For import shipments with multiple CLREGs: Additionally match RFF+ABO-4000 (Sender Reference Version) to Declaration > Misc > Customer Supplied References > CLREGSRV > Number to determine if error applies to Importer or Supplier

---

### 1.3 Inbound Message: CLNTDUP (Client Duplicate Notification)

**Message Function**: Notify that client is already registered in CBF system, provide existing OEM Client ID/TIN

**Processing Logic**: See §4 for status update rules, §2.2 for data storage destinations

| Segment | Element | Code | Description | Format | Mandatory | Conditional | Processing Note |
|---------|---------|------|-------------|--------|-----------|-------------|-----------------|
| UNH | 0062 | - | Message reference number | n..14 | M | - | - |
| UNH | 0065 | CLNTDUP | Message type identifier | an..6 | M | - | - |
| BGM | 1004 | 353 | Document name code (Duplicate notification) | an..3 | M | - | - |
| RFF+ABO | 1153 | ABO | Reference code qualifier | an..3 | M | - | - |
| RFF+ABO | 1154 | - | Sender Reference (URN from original MSG-CLR) | an..35 | M | - | Match to Declaration > Customs > Reference Numbers > URN |
| DOC+CCI | 1001 | CCI | Document name code (OEM Client ID) | an..3 | C | If OEM Client ID exists | - |
| DOC+CCI | 1000 | - | Customs Client Id | an..11 | C | If DOC+CCI present | Store per §2.2 based on TAX+RN role |
| DOC+TIN | 1001 | TIN | Document name code (TIN) | an..3 | C | If TIN exists | - |
| DOC+TIN | 1000 | - | Australian Business Number | an..11 | C | If DOC+TIN present | Store per §2.2 based on TAX+RN role |
| TAX+RN | 5283 | RN | Duty/tax/fee type code qualifier (Role Name) | an..3 | M | - | - |
| TAX+RN | 5152 | - | Role Name | an..35 | M | - | IMPORTER, EXPORTER, or SUPPLIER |

**Message Matching**:
- Match RFF+ABO-1154 to Declaration > Customs > Reference Numbers > URN
- Use TAX+RN-5152 (Role Name) to determine which party (Importer/Shipper) to update

---

## 2. Data Mapping Rules

This section defines ALL field mappings for OEM Client ID/TIN registration data flow. Mappings are organized by SBSS target entity, NOT by message type or scenario. Business Analysts must synthesize across source columns to understand complete data flow for a given registration action.

### 2.1 Declaration Comment Codes (Registration Context Indicators)

**Purpose**: Declaration Comments serve as trigger flags indicating a MSG-CLR message has been requested or is in-process. These codes embed metadata used for message construction.

| Comment Code | Full Description | Client Type | Role | Shipment Type | Embedded Metadata |
|--------------|------------------|-------------|------|---------------|-------------------|
| CCI | Client - Company - Individual | IND | Importer | Import | "Address Type = BA" or "Address Type = PA" |
| CCO | Client - Company - Organization | ORG | Exporter/Shipper | Export | "Address Type = BA" or "Address Type = PA", "TIN = [11-digit number]" (if provided) |
| COI | Client - Organization - Individual | IND | Importer | Import | "Address Type = BA" or "Address Type = PA" |
| COS | Client - Organization - Supplier | ORG | Supplier/Shipper | Import | "Address Type = BA" or "Address Type = PA" (TIN not included for Supplier per §1.1) |
| CIS | Client - Individual - Supplier | IND | Supplier/Shipper | Import | "Address Type = BA" or "Address Type = PA" |

**Parsing Rules**:
- Extract "Address Type = XX" → Maps to FTX+ATY-4453 and FTX+CAT-4453 in MSG-CLR
- Extract "TIN = XXXXXXXXXXX" → Maps to RFF+TIN-1154 in MSG-CLR (only for COI, not COS)
- Comment code itself (CCI/CCO/COI/COS/CIS) determines client type (IND/ORG) and role for message construction

**Storage Location**: Declaration > Comments (specific comment type determined by client type and role selection on OEM Client ID form)

---

### 2.2 OEM Client ID and TIN Storage Matrix

**Principle**: Registration identifiers are stored in DIFFERENT locations depending on whether the customer has a matched Carrier Co Account profile. This dual-path storage pattern applies to ALL inbound messages (MSG-CLRR, CLNTDUP).

#### 2.2.1 Source: MSG-CLRR Message (FTX+CCI or FTX+TIN segments)

| Scenario | Shipment Type | Role in Message | Carrier Co Account on Profile? | OEM Client ID Destination | TIN Destination | CLS Removal |
|----------|---------------|-----------------|-------------------------|------------------|-----------------|-------------|
| Export | Export | Exporter | Yes | Shipment > Shipper > Profile > Comments > OID > Comment Text | Shipment > Shipper > Profile > Comments > TIN > Comment Text | Remove CLS from Shipper profile |
| Export | Export | Exporter | No | Declaration > Customer > Shipper > Tax ID > Reference Numbers > OID > Number | Declaration > Customer > Shipper > Tax ID > Reference Numbers > TIN > Number | N/A |
| Import (Importer) | Import | Importer | Yes | Shipment > Importer > Profile > Comments > OID > Comment Text | Shipment > Importer > Profile > Comments > TIN > Comment Text | Remove CLS from Importer profile |
| Import (Importer) | Import | Importer | No | Declaration > Customer > Importer > Tax ID > Reference Numbers > OID > Number | Declaration > Customer > Importer > Tax ID > Reference Numbers > TIN > Number | N/A |
| Import (Supplier) | Import | Supplier | Yes (on Shipper) | Shipment > Shipper > Profile > Comments > OID > Comment Text | Shipment > Shipper > Profile > Comments > TIN > Comment Text | Remove CLS from Shipper profile |
| Import (Supplier) | Import | Supplier | No (on Shipper) | Declaration > Customer > Shipper > Tax ID > Reference Numbers > OID > Number | Declaration > Customer > Shipper > Tax ID > Reference Numbers > TIN > Number | N/A |

**Role Determination for Import Shipments**:
- Match MSG-CLRR to original MSG-CLR using RFF+ABO-4000 (Sender Reference Version)
- Retrieve CLREGSRV > Comment (Role Name) where CLREGSRV > Number = Sender Reference Version
- If Role Name = "IMPORTER" → Process on Importer party
- If Role Name = "SUPPLIER" → Process on Shipper party

#### 2.2.2 Source: CLNTDUP Message (DOC+CCI or DOC+TIN segments)

| Role in TAX+RN | Carrier Co Account on Profile? | OEM Client ID Destination | TIN Destination | CLS Removal |
|----------------|-------------------------|------------------|-----------------|-------------|
| IMPORTER | Yes (Importer) | Shipment > Importer > Profile > Comments > OID > Comment Text | Shipment > Importer > Profile > Comments > TIN > Comment Text | Remove CLS from Importer profile |
| IMPORTER | No (Importer) | Declaration > Customer > Importer > Tax ID > Reference Numbers > OID > Number | Declaration > Customer > Importer > Tax ID > Reference Numbers > TIN > Number | N/A |
| EXPORTER | Yes (Shipper) | Shipment > Shipper > Profile > Comments > OID > Comment Text | Shipment > Shipper > Profile > Comments > TIN > Comment Text | Remove CLS from Shipper profile |
| EXPORTER | No (Shipper) | Declaration > Customer > Shipper > Tax ID > Reference Numbers > OID > Number | Declaration > Customer > Shipper > Tax ID > Reference Numbers > TIN > Number | N/A |
| SUPPLIER | Yes (Shipper) | Shipment > Shipper > Profile > Comments > OID > Comment Text | Shipment > Shipper > Profile > Comments > TIN > Comment Text | Remove CLS from Shipper profile |
| SUPPLIER | No (Shipper) | Declaration > Customer > Shipper > Tax ID > Reference Numbers > OID > Number | Declaration > Customer > Shipper > Tax ID > Reference Numbers > TIN > Number | N/A |

---

### 2.3 TIN Special Handling: Profile Pre-Population Scenarios

**Context**: TIN may be manually entered by broker BEFORE MSG-CLRR/CLNTDUP is received. This creates a scenario where TIN exists on customer profile Comments > TIN, but the response message also contains TIN. Special mapping rules prevent overwriting profile data.

**Mapping Rule**:
- When MSG-CLRR (FTX+TIN) or CLNTDUP (DOC+TIN) is received:
  - Check if Shipment > Customer Profile > Comments > TIN exists for the matched party (Shipper/Importer)
  - **If TIN comment exists**: Store TIN from message to Declaration > Misc > Customer Supplied References > TIN > Ref Comment (new reference type, do NOT overwrite profile)
  - **If TIN comment does NOT exist**: Store TIN to Shipment > Customer Profile > Comments > TIN > Comment Text (standard path per §2.2)
  - **Always**: Also store TIN to Declaration > Misc > Customer Supplied References > TIN > Ref Comment for audit trail

**Reference Type Setup** (SBSS Admin > Shipment Reference Number Type):
- Code: TIN
- Description: TIN# in response message
- Parent Type Code: CUREF
- Quick Searchable: Yes

---

### 2.4 OEM Client ID/TIN Capture from SBSS UI to Profile

**Trigger Points**:
1. Broker manually enters Tax ID on Full Turbo > Address > Importer/Shipper > Tax ID field
2. Broker manually enters FZ/CW# on Full Turbo > Address > Importer/Shipper > FZ/CW# field
3. Broker submits OEM Client ID form with new OEM Client ID or TIN

**Popup Prompt Logic**:
- **Condition**: Tax ID or FZ/CW# field modified AND Customer has Carrier Co Account on profile
- **Prompt**: "Would you like to save the [OEM Client ID/TIN] in [Shipper/Importer]'s profile?"
- **If Yes**: Store value to Shipment > Customer Profile > Comments > [OID or TIN] > Comment Text
- **If No**: Retain value only on Declaration > Customer > Tax ID or FZ/CW# field (no profile update)

**Bidirectional Sync**:
- Tax ID field ↔ Declaration > Customer > Tax ID
- FZ/CW# field ↔ Declaration > Customer > FZ/CW# AND Customer Profile > Comments > OID (if user confirms profile save)
- If OEM Client ID entered in Reference Numbers > OID, must also populate FZ/CW# field (and vice versa)

**Format Validation**:
- OEM Client ID: Alphanumeric, maximum 11 characters
- TIN: Numeric, exactly 11 digits
- System must throw error if character limit exceeded

---

### 2.5 Sender Reference Version (CLREGSRV) Mapping

**Purpose**: Track which MSG-CLR message (Importer vs Supplier) a MSG-CLRR response corresponds to on import shipments with multiple registration applications.

**Reference Type Setup** (SBSS Admin > Shipment Reference Number Type):
- Code: CLREGSRV
- Description: MSG-CLR Sender Reference Version
- Parent Type Code: CUREF
- Quick Searchable: Yes

**Mapping Sources and Destinations**:

| Data Element | Source | Destination Field | Destination Value |
|--------------|--------|-------------------|-------------------|
| Sender Reference Version (outbound) | BGM-1056 in MSG-CLR message | Declaration > Misc > Customer Supplied References > CLREGSRV > Number | "1" or "2" |
| Role Name (outbound) | MEA+RN-6154 in MSG-CLR message | Declaration > Misc > Customer Supplied References > CLREGSRV > Comment | "IMPORTER", "EXPORTER", or "SUPPLIER" (uppercase) |
| Sender Reference Version (inbound) | RFF+ABO-4000 in MSG-CLRR message | (Used to MATCH existing CLREGSRV, not to create new) | - |

**Lifecycle**:
1. MSG-CLR message #1 sent for Importer: Create CLREGSRV with Number = "1", Comment = "IMPORTER"
2. MSG-CLR message #2 sent for Supplier: Create CLREGSRV with Number = "2", Comment = "SUPPLIER"
3. MSG-CLRR received with RFF+ABO-4000 = "2": Match to CLREGSRV where Number = "2", read Comment = "SUPPLIER", process FTX+CCI/TIN on Shipper party

---

### 2.6 Error Response Data (CLREGRED) Mapping

**Purpose**: Store error messages from MSG-CLRR for display to brokers when shipments are opened.

**Reference Type Setup** (SBSS Admin > Shipment Reference Number Type):
- Code: CLREGRED
- Description: MSG-CLR Response Error Description
- Parent Type Code: CUREF
- Quick Searchable: Yes

**Mapping Rules**:

| Shipment Type | Role Name (from CLREGSRV) | CLREGRED > Number | CLREGRED > Comment |
|---------------|---------------------------|-------------------|--------------------|
| Export | EXPORTER | "EXPORTER" | Message text from FTX+AAO-4440 (one CLREGRED per FTX+AAO segment) |
| Import | IMPORTER | "IMPORTER" | Message text from FTX+AAO-4440 (one CLREGRED per FTX+AAO segment) |
| Import | SUPPLIER | "SUPPLIER" | Message text from FTX+AAO-4440 (one CLREGRED per FTX+AAO segment) |

**Replacement Logic**:
- When new MSG-CLRR received for same role (e.g., second MSG-CLRR for IMPORTER after first one had errors):
  - Delete ALL existing CLREGRED items with matching Number (e.g., all "IMPORTER" CLREGREDs)
  - Replace with new CLREGRED items from latest MSG-CLRR message
- This ensures remark popup always shows most recent error state, not cumulative history

---

### 2.7 Address Validation Postal Code Mapping

**Purpose**: Validate Australian addresses against master town reference data and classify shipments for routing purposes.

**Master Town Table Schema** (reference data source):

| Column | Description | Example Values |
|--------|-------------|----------------|
| Postal Code | Australian postal code | "3000", "2000", "4000" |
| City | Suburb/city name | "MELBOURNE", "SYDNEY", "BRISBANE" |
| Province | Metropolitan classification | "MET", "" (blank for non-metropolitan) |

**Mapping Sources and Destinations**:

| SBSS UI Field | Master Town Column | Validation Rule | Shipment Brokerage Status Value |
|---------------|-------------------|-----------------|--------------------------------|
| Full Turbo > Address > Postal Code | Postal Code | Exact match required | - |
| Full Turbo > Address > City | City | Exact match required (case-insensitive) | - |
| (Derived from lookup) | Province | "MET" | MET |
| (Derived from lookup) | Province | "" (blank/null) | NMT |
| (No match found) | - | - | NIL |

**Validation Trigger Points**:
- Tab-out from Postal Code field
- Tab-out from City field
- Save action on Declaration

**Scope**:
- Applies to BOTH Import and Export shipments
- Checks performed on ALL parties with Country Code = "AU" (Shipper, Importer, Exporter addresses)
- Non-AU addresses: See §3.2 for completeness validation (no postal code lookup performed)

---

## 3. Business Rules & Validation

This section consolidates all conditional logic, validation constraints, and processing rules. A single business action (e.g., submitting a MSG-CLR) may trigger rules from multiple subsections.

### 3.1 Australian Address Validation Rules

#### 3.1.1 Postal Code and City Synchronization

**Trigger**: Tab-out from Postal Code field OR City field on any address with Country Code = "AU"

**Validation Logic**:
1. Query Master Town table: `WHERE Postal Code = [entered value] AND City = [entered value]` (case-insensitive on City)
2. **If match found**:
   - Check Province value from matched row
   - If Province = "MET": Set Shipment Brokerage Status = MET
   - If Province = "" (blank/null): Set Shipment Brokerage Status = NMT
3. **If no match found**:
   - Set Shipment Brokerage Status = NIL
   - Place shipment in Intervention queue
   - Add remark: "AU ADDRESS WITH INVALID POSTAL CODE"

**Scope**: Applies to Shipper, Importer, Exporter, Consignee addresses (any party address can trigger)

#### 3.1.2 Australian Address Completeness Validation

**Trigger**: Save action on Declaration OR tab-out from Address Line 1 field

**Validation Logic for AU Addresses** (Country Code = "AU"):

| Condition | Action |
|-----------|--------|
| Address Line 1 is blank | Place in Intervention, add remark "INCOMPLETE AU ADDRESS" |
| Postal Code and City validation failed (per §3.1.1) | Place in Intervention, add remark "AU ADDRESS WITH INVALID POSTAL CODE" |
| Both checks pass | Allow shipment to proceed |

**Validation Logic for Non-AU Addresses**:

| Condition | Action |
|-----------|--------|
| Name is blank | Place in Intervention, add remark "INCOMPLETE OVERSEAS ADDRESS" |
| Address Line 1 is blank | Place in Intervention, add remark "INCOMPLETE OVERSEAS ADDRESS" |
| Country Code is blank | Place in Intervention, add remark "INCOMPLETE OVERSEAS ADDRESS" |
| All three fields populated | Allow shipment to proceed |

**Scope**: Applies to ALL shipments, regardless of Import/Export type

---

### 3.2 TIR Hold (Tax ID Required) Conditional Logic

**Background**: RAT Hold Reason "TIR" prevents declaration submission until valid tax identifier (TIN or OEM Client ID) is provided for relevant parties.

#### 3.2.1 Hold Application Rules

**Import Shipments (Clearance Type = FML)**:

**Condition to ADD TIR Hold**:
```
IF (Importer Tax ID is blank AND Importer FZ/CW# is blank)
OR (Shipper Tax ID is blank AND Shipper FZ/CW# is blank)
THEN
  Add RAT Hold Reason = TIR
  Set RAT status = HLD
```

**Condition to REMOVE TIR Hold**:
```
IF (Importer Tax ID is NOT blank OR Importer FZ/CW# is NOT blank)
AND (Shipper Tax ID is NOT blank OR Shipper FZ/CW# is NOT blank)
AND RAT Hold Reason TIR exists
THEN
  Remove RAT Hold Reason TIR
  Set RAT status per segregation logic
```

**Export Shipments (Clearance Type = FML)**:

**Condition to ADD TIR Hold**:
```
IF (Shipper Tax ID is blank AND Shipper FZ/CW# is blank)
THEN
  Add RAT Hold Reason = TIR
  Set RAT status = HLD
```

**Condition to REMOVE TIR Hold**:
```
IF (Shipper Tax ID is NOT blank OR Shipper FZ/CW# is NOT blank)
AND RAT Hold Reason TIR exists
THEN
  Remove RAT Hold Reason TIR
  Set RAT status per segregation logic
```

#### 3.2.2 Field Equivalency Matrix

**For TIR hold logic purposes**, the following fields are considered equivalent sources of tax identifiers:

| SBSS UI Field | Declaration Entity | Profile Entity | Comment Type |
|---------------|-------------------|----------------|--------------|
| Full Turbo > Address > Importer > Tax ID | Declaration > Customer > Importer > Tax ID | - | - |
| Full Turbo > Address > Importer > FZ/CW# | Declaration > Customer > Importer > FZ/CW# | Shipment > Importer > Profile > Comments > OID | OID |
| Full Turbo > Address > Shipper > Tax ID | Declaration > Customer > Shipper > Tax ID | - | - |
| Full Turbo > Address > Shipper > FZ/CW# | Declaration > Customer > Shipper > FZ/CW# | Shipment > Shipper > Profile > Comments > OID | OID |

**Evaluation Priority** (check in order, stop at first non-blank):
1. Declaration > Customer > Tax ID
2. Declaration > Customer > FZ/CW#
3. Shipment > Customer Profile > Comments > OID (if profile matched via Carrier Co Account)
4. Shipment > Customer Profile > Comments > TIN (if profile matched via Carrier Co Account)

**Note**: If ANY of these sources contain a value, the identifier is considered "provided" and TIR hold should not apply (or should be removed if it exists).

---

### 3.3 MSG-CLR Submission Blocking Rules

**Purpose**: Prevent duplicate or invalid MSG-CLR submissions based on existing registration state.

#### 3.3.1 Error Message Matrix

| Error Message | Blocking Condition (Export) | Blocking Condition (Import - Importer) | Blocking Condition (Import - Supplier) |
|---------------|----------------------------|---------------------------------------|---------------------------------------|
| "Client registration message has already been sent." | Shipment > Shipper > Profile > Comments > CLS exists | Shipment > Importer > Profile > Comments > CLS exists | Shipment > Shipper > Profile > Comments > CLS exists |
| "OEM Client ID has already been registered." | Shipment > Shipper > Profile > Comments > OID exists OR Declaration > Customer > Shipper > Tax ID > Reference Numbers > OID exists | Shipment > Importer > Profile > Comments > OID exists OR Declaration > Customer > Importer > Tax ID > Reference Numbers > OID exists | Shipment > Shipper > Profile > Comments > OID exists OR Declaration > Customer > Shipper > Tax ID > Reference Numbers > OID exists |
| "TIN has already been registered." (Scenario A) | Shipment > Shipper > Profile > Comments > TIN exists OR Declaration > Customer > Shipper > Tax ID > Reference Numbers > TIN exists | Shipment > Importer > Profile > Comments > TIN exists OR Declaration > Customer > Importer > Tax ID > Reference Numbers > TIN exists | (Not applicable - Supplier TIN not sent per §1.1) |
| "TIN has already been registered." (Scenario B) | Declaration > Misc > Customer Supplied References > TIN exists | Declaration > Misc > Customer Supplied References > TIN with Role Name "IMPORTER" exists | Declaration > Misc > Customer Supplied References > TIN with Role Name "SUPPLIER" exists |

**Blocking Behavior**: If ANY condition in the relevant column evaluates to true, MSG-CLR message submission MUST be blocked and the corresponding error message displayed.

**Exception for Import Shipments with Two MSG-CLR Messages**:
- If first MSG-CLR has been sent (CLS exists on Importer profile) and user attempts to send second MSG-CLR for Supplier:
  - Check CLS on Shipper profile (NOT Importer profile)
  - Allow submission if Shipper profile CLS does NOT exist, even if Importer profile CLS exists

---

### 3.4 MSG-CLR Mandatory Field Validation

#### 3.4.1 Organization (ORG) with TIN

**Mandatory Segments/Elements**:
- RFF+TIN: 1154 - Australian Business Number (11 digits, numeric)
- FTX+CNP: 4440 - Contact Name (must not be blank)
- FTX+CNP: 4440 - Contact Purpose (must not be blank)
- FTX+CAT: 4440 - Address Line 1 (must not be blank)
- MEA+RN: 6165 - Role Name (must not be blank)

**Validation Trigger**: When Declaration Comment CCO, COI, or COS is added AND "TIN = " is present in comment text

**Failure Action**: Display error message listing missing mandatory fields, block MSG-CLR submission

#### 3.4.2 Individual (IND) - All Roles

**Non-Mandatory Elements** (despite appearing in message schema):
- FTX+CNP: 4440 - First Name (optional)
- FTX+CNP: 4440 - Second Name (optional)
- FTX+CNP: 4440 - Suffix (optional)

**Rationale**: CBF may accept individual registrations with partial name data in certain circumstances (e.g., single-name individuals, cultural naming conventions)

**Validation Trigger**: Individual MSG-CLR messages should NOT fail validation if these name fields are blank

#### 3.4.3 Address Type Validation

**Non-Mandatory Elements**:
- FTX+ATY: 4440 - Address Line 2 (optional for all client types and roles)
- FTX+CAT: 4440 - Contact Address Line 2 (optional for all client types and roles)

**Validation Trigger**: Address Line 2 blank should NOT block MSG-CLR submission

---

### 3.5 CLS (Client Sent) Comment Management

**Purpose**: CLS comment tracks that a MSG-CLR message has been sent for a customer, preventing duplicate applications until response is received.

**Lifecycle**:
1. **Add CLS**: When MSG-CLR message is successfully transmitted to TPS
   - Storage: Shipment > Customer Profile > Comments > CLS
   - Comment Text: URN (Unique Reference Number from Declaration > Customs > Reference Numbers > URN)
2. **Remove CLS**: When MSG-CLRR or CLNTDUP response is received AND processed successfully (OID or TIN stored)
   - Removal Condition: FTX+CCI, FTX+TIN (MSG-CLRR) or DOC+CCI, DOC+TIN (CLNTDUP) processed
   - Timing: Remove CLS from profile simultaneously with storing OID/TIN
3. **Remove CLS on Error**: When MSG-CLRR received with CNT+55 > 0 (error count > 0)
   - Removal Condition: Brokerage Status OID set to ERR
   - Rationale: Allow broker to correct data and resubmit MSG-CLR for same customer

**Special Case - Import Shipments with Two CLREGs**:
- If MSG-CLR sent for Importer: Add CLS to Importer profile
- If MSG-CLR sent for Supplier: Add CLS to Shipper profile
- Two separate CLS comments may exist simultaneously on different profiles for the same shipment

---

## 4. Status Model

This section defines all Brokerage Status OID values, transition triggers, and priority rules. Status changes may be triggered by message receipt (MSG-CLRR, CLNTDUP), UI actions (MSG-CLR submission), or conditional logic evaluation (error count checks).

### 4.1 Brokerage Status OID State Diagram

```
[No MSG-CLR Needed] ──(User initiates MSG-CLR)──> [RFC: Ready for Customs]
                                                       │
                                                       │ (MSG-CLR sent to TPS)
                                                       ▼
                                                  [SNT: Sent]
                                                       │
                                        ┌──────────────┼──────────────┐
                                        │              │              │
                              (MSG-CLRR, CNT=0)  (MSG-CLRR, CNT>0)  (CLNTDUP received)
                                        │              │              │
                                        ▼              ▼              ▼
                                    [CMP]          [ERR]          [CMP]
                                  Complete        Error          Complete
```

### 4.2 Status Definitions and Transitions

| Status Code | Status Name | Description | Entry Trigger | Exit Trigger |
|-------------|-------------|-------------|---------------|--------------|
| RFC | Ready for Customs | MSG-CLR message constructed and validated, pending user approval to send | OEM Client ID form submitted with valid data, all mandatory fields populated | User confirms send action |
| SNT | Sent | MSG-CLR message transmitted to TPS, awaiting response | TPS gateway confirms message receipt | MSG-CLRR or CLNTDUP message received |
| SCR | Successfully Received | TPS acknowledged message format is valid (legacy status, may not apply to MSG-CLR) | Not used for MSG-CLR workflow | - |
| CMP | Complete | Registration successful, OEM Client ID/TIN stored on profile or declaration | MSG-CLRR CNT+55 = 0 OR CLNTDUP received and processed | - |
| ERR | Error | Registration failed, error messages available for broker review | MSG-CLRR CNT+55 > 0 | User corrects data and resubmits MSG-CLR (transitions back to RFC) |

### 4.3 Status Transition Rules for Import Shipments with Multiple CLREGs

**Complexity**: Import shipments may have TWO separate MSG-CLR messages (one for Importer, one for Supplier), but only ONE Brokerage Status OID field.

**Priority Logic**:
1. If EITHER Importer or Supplier MSG-CLR is in ERR state: Overall OID status = ERR
2. If BOTH Importer and Supplier CLREGs are in CMP state: Overall OID status = CMP
3. If one is CMP and the other is SNT (awaiting response): Overall OID status = SNT
4. If only one MSG-CLR sent so far (e.g., Importer SNT, Supplier not sent): Overall OID status = SNT

**Decision Matrix**:

| Importer MSG-CLR State | Supplier MSG-CLR State | Overall OID Status | Rationale |
|----------------------|---------------------|--------------------|-----------|
| Not sent | Not sent | (No OID status) | No registration initiated |
| SNT | Not sent | SNT | Waiting for Importer response |
| CMP | Not sent | SNT | Importer complete, but Supplier still needed |
| CMP | SNT | SNT | Importer complete, waiting for Supplier |
| CMP | CMP | CMP | Both complete, shipment fully registered |
| ERR | SNT | ERR | Error takes priority over in-progress |
| ERR | CMP | ERR | Error takes priority over complete |
| SNT | ERR | ERR | Error takes priority over in-progress |
| CMP | ERR | ERR | Error takes priority over complete |

**Evaluation Trigger Points**:
- MSG-CLRR received: Re-evaluate status based on CNT+55 value and existing data for other party
- CLNTDUP received: Re-evaluate status based on TAX+RN role and existing data for other party
- User submits second MSG-CLR: Transition from CMP (first MSG-CLR complete) back to SNT (awaiting second response)

### 4.4 OID Status Impact on TIR Hold

**Cross-Reference**: See §3.2 for TIR hold logic

**Rule**: OID status of CMP does NOT automatically remove TIR hold. TIR removal requires EITHER:
- Tax ID field populated (TIN entered manually), OR
- FZ/CW# field populated (OEM Client ID entered manually or synced from profile)

**Scenario**: MSG-CLRR received, OID stored on profile, OID status → CMP, BUT if broker has not yet opened shipment or triggered field sync, FZ/CW# field on declaration may still be blank, so TIR hold remains.

**Auto-Sync Requirement**: When OID status changes to CMP, system should:
1. Check if customer profile OID comment exists
2. If yes, auto-populate Declaration > Customer > FZ/CW# field from profile > Comments > OID
3. Trigger TIR hold re-evaluation (per §3.2.1)

---

## 5. Error & Exception Handling

This section covers error scenarios, recovery procedures, and logging requirements across the MSG-CLR/MSG-CLRR/CLNTDUP lifecycle.

### 5.1 MSG-CLRR Error Response Processing

**Trigger**: MSG-CLRR message received with CNT+55-6066 (Total Comments) > 0

**Processing Steps**:
1. Set Brokerage Status OID = ERR
2. Remove CLS comment from customer profile (allow resubmission after correction)
3. Parse all FTX+AAO segments in message
4. For each FTX+AAO-4440 (Message Text):
   - Create Declaration > Misc > Customer Supplied References > CLREGRED item
   - Populate CLREGRED > Number with Role Name (IMPORTER/EXPORTER/SUPPLIER) from CLREGSRV
   - Populate CLREGRED > Comment with message text from FTX+AAO-4440
5. If CLREGRED items already exist for same Role Name: Delete all existing items, replace with new (latest MSG-CLRR errors only)
6. Trigger remark popup display logic (see §6.1)

**Remark Popup Suppression**: Do NOT display remark popup until user explicitly opens shipment (on-demand display, not automatic on message receipt)

---

### 5.2 MSG-CLR Pre-Submission Validation Failures

**Validation Failure Scenarios**:

| Validation Type | Failure Condition | Error Message | Recovery Action |
|----------------|-------------------|---------------|-----------------|
| Duplicate MSG-CLR (CLS exists) | CLS comment present on customer profile | "Client registration message has already been sent." | Wait for MSG-CLRR response before retrying |
| Duplicate OEM Client ID | OID comment or reference number exists | "OEM Client ID has already been registered." | Use existing OEM Client ID, no MSG-CLR needed |
| Duplicate TIN | TIN comment or reference number exists | "TIN has already been registered." | Use existing TIN, no MSG-CLR needed |
| Missing Mandatory Field | Required element blank in MSG-CLR message | "Missing mandatory field: [field name]" | Populate missing data on OEM Client ID form, resubmit |

**Logging Requirement**: All validation failures must log to Declaration > Comments with timestamp and user ID for audit trail

---

### 5.3 Message Transmission Failures

**Scenario**: MSG-CLR message constructed but TPS gateway fails to transmit (network error, gateway timeout, message size exceeded)

**Error Handling**:
1. Do NOT set Brokerage Status OID to SNT
2. Do NOT add CLS comment to customer profile
3. Display error message to user: "Message transmission failed: [technical error details]"
4. Log failure event to shipment event log with:
   - Event Type: "MSG-CLR Transmission Failure"
   - Event Details: Gateway error code, timestamp, message payload size
   - User ID: Broker who initiated submission
5. Allow immediate retry (validation already passed, no cooldown period)

**Recovery**: User clicks "Retry" button on error popup, system re-attempts transmission without rebuilding message

---

### 5.4 CLNTDUP Unexpected Scenarios

**Scenario A**: CLNTDUP received, but no prior MSG-CLR was sent from SBSS for this customer

**Handling**:
- Process CLNTDUP normally (store OID/TIN per §2.2.2)
- Set OID status = CMP
- Do NOT raise error (customer may have been registered via CBF portal outside SBSS)
- Log event: "CLNTDUP received without prior MSG-CLR submission"

**Scenario B**: CLNTDUP received with DOC+CCI AND DOC+TIN (both OEM Client ID and TIN present)

**Handling**:
- Store both identifiers per §2.2.2 mapping rules
- Set OID status = CMP
- If customer profile has Carrier Co Account: Store both to profile > Comments > OID and > Comments > TIN
- If no Carrier Co Account: Store both to Declaration > Customer > Tax ID > Reference Numbers > OID and > TIN

**Scenario C**: CLNTDUP received, but TAX+RN-5152 (Role Name) value is unexpected (e.g., "CONSIGNEE")

**Handling**:
- Log error: "CLNTDUP received with unsupported Role Name: [value]"
- Do NOT process DOC segments (do not store OEM Client ID/TIN, uncertain which party to map to)
- Set OID status = ERR
- Create CLREGRED with Number = "UNKNOWN", Comment = "Unsupported role in duplicate notification: [Role Name]"

---

### 5.5 Postal Code Validation Performance Considerations

**Issue**: Real-time master town lookup on every keystroke could cause UI lag if postal code table is large

**Mitigation**:
- Validation triggers ONLY on tab-out/blur events (NOT on keyup/input events)
- Query should include index on Postal Code + City columns in master town table
- Query timeout: 2 seconds maximum
- If query times out: Log warning, set Shipment Brokerage Status = NIL, do NOT place in Intervention (avoid false positives from database performance issues)

**Fallback**: If master town table unavailable (database connection error):
- Allow address entry to proceed
- Set Shipment Brokerage Status = NIL
- Log critical error for admin investigation
- Display warning to broker: "Postal code validation temporarily unavailable, manual verification required"

---

## 6. Integration Points and Event Logging

This section specifies system interfaces, reference data dependencies, and event logging requirements for audit and troubleshooting.

### 6.1 Remark Popup Display Logic

**Trigger**: User opens shipment (navigation to Shipment Detail screen or Declaration Entry form)

**Display Condition**:
- Brokerage Status OID = ERR
- AND Declaration > Misc > Customer Supplied References > CLREGRED exists (at least one item)

**Popup Format**:

```
Title: Error Response on Client Registration Message - [Role Name]

Content:
[Error message text from CLREGRED > Comment, line 1]
[Error message text from CLREGRED > Comment, line 2]
[Error message text from CLREGRED > Comment, line N]
```

**Multi-Role Scenario (Import with both Importer and Supplier errors)**:

```
Title: Error Response on Client Registration Message - IMPORTER

Content:
[Importer error message 1]
[Importer error message 2]

---

Title: Error Response on Client Registration Message - SUPPLIER

Content:
[Supplier error message 1]
[Supplier error message 2]
```

**Popup Behavior**:
- Modal display (blocks shipment interaction until acknowledged)
- "OK" button to dismiss
- Popup displays ONCE per shipment open (do not re-display on tab changes within same session)
- If OID status changes from ERR to CMP (after correction and successful MSG-CLRR), do NOT display remark popup even if CLREGRED items still exist (status takes precedence)

**Remark Popup Suppression**: If CLREGRED exists but OID status = CMP, do NOT display (user has already corrected issue)

---

### 6.2 Event Logging Specifications

**Event Types** (to be added to Shipment Event Log):

| Event Type Code | Event Description | Trigger | Data Captured |
|----------------|-------------------|---------|---------------|
| CLREGSUB | MSG-CLR Message Submitted | MSG-CLR transmitted to TPS | URN, Role Name, Client Type, Brokerage Status OID, Timestamp, User ID |
| CLREGRCV | MSG-CLRR Message Received | MSG-CLRR processed | URN, Sender Reference Version, CNT+55 value, OID stored (Y/N), TIN stored (Y/N), Timestamp |
| CLNTDUPRCV | CLNTDUP Message Received | CLNTDUP processed | URN, Role Name, OID stored (Y/N), TIN stored (Y/N), Timestamp |
| CLREGERR | MSG-CLR Error Logged | MSG-CLRR CNT+55 > 0 processed | URN, Role Name, Error count, CLREGRED item count, Timestamp |
| CIDUPD | OEM Client ID Updated on Profile | OEM Client ID synced to customer profile | Carrier Co Account, Customer Name, OID value, Source (MSG-CLRR/CLNTDUP/Manual), Timestamp, User ID |
| TINUPD | TIN Updated on Profile | TIN synced to customer profile | Carrier Co Account, Customer Name, TIN value, Source (MSG-CLRR/CLNTDUP/Manual), Timestamp, User ID |
| TIRADD | TIR Hold Added | RAT hold applied due to missing Tax ID/OEM Client ID | Party (Importer/Shipper), RAT status, Timestamp |
| TIRRM | TIR Hold Removed | RAT hold removed after Tax ID/OEM Client ID provided | Party (Importer/Shipper), RAT status, Tax ID source (Tax ID field/FZ-CW# field/Profile), Timestamp |
| PCCVAL | Postal Code Validated | Address validation completed | Country, Postal Code, City, Province, Shipment Brokerage Status, Validation result (Match/No Match), Timestamp |

**Log Retention**: Event log entries must be retained for minimum 7 years per CBF audit requirements

---

### 6.3 Reference Data Dependencies

**Master Town Reference Data**:
- **Source System**: SBSS Admin > Master Town table (populated from CBF or Australia Post official data)
- **Update Frequency**: Monthly refresh recommended to capture new postal codes and suburb reassignments
- **Data Quality Requirements**:
  - Postal Code: Mandatory, 4-digit numeric format
  - City: Mandatory, uppercase preferred for consistency
  - Province: Optional, but MUST be populated with "MET" for metropolitan areas if shipment routing depends on this classification
- **Missing Data Handling**: If Province is null for a valid Postal Code + City match, default to NMT (non-metropolitan)

**SBSS Admin Configuration Tables** (new reference types required):

| Admin Table | New Reference Code | Description | Parent Type | Searchable |
|-------------|-------------------|-------------|-------------|------------|
| Shipment Reference Number Type | TIN | Australian Business Number | AD (Address) | Yes |
| Shipment Reference Number Type | CLREGERR | Error encountered in Registration Message (DEPRECATED, replaced by CLREGRED) | CUREF (Customer Reference) | No |
| Shipment Reference Number Type | CLREGRED | MSG-CLR Response Error Description | CUREF | Yes |
| Shipment Reference Number Type | CLREGSRV | MSG-CLR Sender Reference Version | CUREF | Yes |

---

### 6.4 TPS Gateway Interface Specifications

**Message Exchange Pattern**: Asynchronous request-response

**Outbound (SBSS → TPS)**:
- Message Type: MSG-CLR
- Protocol: UN/EDIFACT over secure VPN tunnel
- Acknowledgment: Synchronous transport-level ACK (message received by gateway), NOT application-level ACK
- Timeout: 30 seconds for transmission, no retry on timeout (user must manually retry)

**Inbound (TPS → SBSS)**:
- Message Types: MSG-CLRR, CLNTDUP
- Expected Response Time: 24-48 hours typical, up to 7 days if manual officer review required
- Processing Window: SBSS must poll/receive inbound messages every 15 minutes during business hours
- Message Matching: Match RFF+ABO-1154 (Sender Reference) to Declaration > Customs > Reference Numbers > URN

**Error Scenarios**:
- MSG-CLR transmission failure: Log to event log, display error to user, do NOT set OID status to SNT
- MSG-CLRR not received within 7 days: Escalate to support team (possible message loss or TPS system issue)
- MSG-CLRR received with no matching URN: Log orphaned message error, store to exception queue for manual investigation

---

### 6.5 Customer Profile Matching Logic

**Purpose**: Determine whether to store OEM Client ID/TIN on customer profile (matched customer) or declaration reference numbers (unmatched customer)

**Matching Criteria**:
- **Primary Key**: Carrier Co Account field populated on Shipment > [Party] > Profile page
- **Fallback**: NOT SUPPORTED (if Carrier Co Account is blank, customer is considered unmatched regardless of name/address similarity)

**Matching Decision Tree**:

```
Does Shipment > Shipper/Importer > Profile > Carrier Co Account exist?
├─ YES → Matched customer
│         └─ Store OEM Client ID/TIN to Profile > Comments
│         └─ Allow CLS comment management
│         └─ Popup prompt for manual OEM Client ID/TIN entry
│
└─ NO → Unmatched customer
          └─ Store OEM Client ID/TIN to Declaration > Customer > Tax ID > Reference Numbers
          └─ Do NOT add CLS comment (no profile to attach to)
          └─ Do NOT popup prompt for profile save
```

**Multi-Profile Ambiguity**: If multiple customer profiles exist with same Carrier Co Account (data quality issue):
- Use the profile currently attached to the shipment (Shipment > Customer > Profile linkage)
- Log warning event: "Multiple profiles found for Carrier Co Account [value], using shipment-attached profile"

---

## 7. OEM Client ID Form UI Specifications

This section defines the user interface behavior for the OEM Client ID application form (Declaration Entry Form > Customer Client Identifier screen).

### 7.1 Form Field Definitions and Behavior

| Field Label | Field Type | Allowed Values | Mandatory | Default Value | Conditional Logic |
|-------------|-----------|----------------|-----------|---------------|-------------------|
| Client Type | Radio button | Individual (IND), Organization (ORG) | Yes | (No default, user must select) | - |
| Role | Dropdown | Exporter, Importer, Supplier | Yes | (No default) | If Import shipment: Show Importer, Supplier. If Export shipment: Show Exporter only |
| Address Type | Dropdown | BA (Business Address), PA (Postal Address) | Yes | BA (for ORG), BA (for IND) | Enabled for ALL client types and roles (changed from previous logic that disabled for IND) |
| TIN | Text input | Numeric, 11 digits exactly | Conditional | (Blank) | Enabled ONLY if Client Type = ORG AND Role = Exporter or Importer. Disabled if Client Type = IND or Role = Supplier |
| Family Name | Text input | Alphanumeric, max 70 chars | No | (Blank) | Visible only if Client Type = IND |
| First Name | Text input | Alphanumeric, max 70 chars | No | (Blank) | Visible only if Client Type = IND |
| Second Name | Text input | Alphanumeric, max 70 chars | No | (Blank) | Visible only if Client Type = IND |
| Suffix | Text input | Alphanumeric, max 10 chars | No | (Blank) | Visible only if Client Type = IND |
| Contact Name | Text input | Alphanumeric, max 70 chars | Conditional | (Blank) | Mandatory if Client Type = ORG AND TIN provided |
| Contact Purpose | Text input | Alphanumeric, max 70 chars | Conditional | (Blank) | Mandatory if Client Type = ORG AND TIN provided |
| Address Line 1 | Text input | Alphanumeric, max 70 chars | Yes | (Blank) | - |
| Address Line 2 | Text input | Alphanumeric, max 70 chars | No | (Blank) | - |
| Suburb/City | Text input | Alphanumeric, max 35 chars | Yes | (Blank) | - |
| State/Province | Text input | Alphanumeric, max 9 chars | Yes | (Blank) | - |
| Postal Code | Text input | Alphanumeric, max 9 chars | Yes | (Blank) | - |
| Country Code | Text input | ISO 2-letter code | Yes | AU | - |

**Form Layout Adjustments**:
- Label "CAC Address Type" corrected to "Address Type" (typo fix)
- Address Type dropdown always enabled (previously disabled for certain client type + role combinations)
- Address Line 2 visually de-emphasized (lighter label color) to indicate optional status

---

### 7.2 Form Submission Validation

**Pre-Submission Checks** (all must pass before MSG-CLR message generation):

1. **Duplicate MSG-CLR Check**: Query blocking rules per §3.3.1, display error if CLS/OID/TIN already exists
2. **Mandatory Field Check**: Validate all required fields per §7.1 are populated
3. **Format Check**: TIN must be exactly 11 numeric digits if provided
4. **Address Type Check**: Address Type must be BA or PA (no other values accepted)
5. **Role Name Check**: Role must match shipment type (Importer/Supplier for Import, Exporter for Export)

**Validation Failure Behavior**:
- Display inline error messages below failed fields
- Highlight failed fields in red
- Submit button remains disabled until all errors cleared
- Error summary displayed at top of form: "[N] validation errors must be corrected before submission"

---

### 7.3 Form Submission Success Flow

**On Submit Button Click**:
1. Run pre-submission validation (§7.2)
2. If validation passes:
   - Generate Declaration Comment (CCI/CCO/COI/COS/CIS) with embedded Address Type and TIN (if applicable)
   - Construct MSG-CLR EDIFACT message per §1.1
   - Set Brokerage Status OID = RFC
   - Display confirmation popup: "MSG-CLR application ready for submission. Send to Customs?"
3. If user confirms "Yes" on popup:
   - Transmit MSG-CLR to TPS gateway
   - Set Brokerage Status OID = SNT
   - Add CLS comment to customer profile (if Carrier Co Account exists)
   - Store URN in CLS comment text
   - Store CLREGSRV (Sender Reference Version + Role Name) per §2.5
   - Close OEM Client ID form, return to Declaration Entry screen
   - Display toast notification: "Client registration application submitted successfully. URN: [value]"
4. If user confirms "No" on popup:
   - Return to OEM Client ID form (OID status remains RFC, message not sent)
   - User can modify data or cancel

---

### 7.4 Individual Name Concatenation Logic

**Purpose**: Construct full name from individual name components for storage in MSG-CLR message FTX segments

**Concatenation Rule** (hierarchy order):
```
Full Name = [First Name] + " " + [Second Name] + " " + [Family Name] + " " + [Suffix]
```

**Examples**:
- First: Gail, Second: Julieta, Family: Buenaventura, Suffix: III → "Gail Julieta Buenaventura III"
- First: Mary, Second: (blank), Family: Smith, Suffix: (blank) → "Mary Smith"
- First: (blank), Second: (blank), Family: Madonna, Suffix: (blank) → "Madonna"

**Whitespace Handling**:
- Trim leading/trailing spaces from each component before concatenation
- Collapse multiple consecutive spaces to single space in final output
- If a component is blank, skip it entirely (do not add extra spaces)

**Storage Destination**: Full name stored in FTX+CNP-4440 (Contact Name) segment for Individual MSG-CLR messages

---

## 8. Data Migration and Historical Data Handling

**Out of Scope**: This specification does NOT include requirements for retrospective data correction or migration of historical shipments.

**Rationale**: OEM Client ID/TIN registration is a forward-looking compliance requirement. Existing closed/archived shipments do not require retroactive OEM Client ID application.

**Future Consideration**: If CBF mandates retrospective registration for active/open shipments, a separate data migration specification will be required covering:
- Bulk MSG-CLR generation for unregistered customers with open shipments
- Batch processing of MSG-CLRR responses
- Profile update automation for matched customers
- Exception handling for customers with data quality issues (missing addresses, invalid TINs)

---

## 9. Cross-Reference to Platform Knowledge

**Message Patterns**: See Platform Knowledge §2.3 for general TPS EDIFACT messaging patterns (UNH/UNT segment structure, interchange envelopes, character set encoding)

**Data Model Entities**:
- Shipment entity: Platform Knowledge §4
- Declaration entity: Platform Knowledge §4
- Customer Profile entity: Platform Knowledge §4
- Reference Number Type configuration: Platform Knowledge §5

**Status Codes**: Platform Knowledge §8 for general brokerage status definitions (RAT, EBC, CUS). This specification extends with OID status model (§4).

**Party Roles**: Platform Knowledge §4 for Shipper, Consignee, Importer, Broker party types. This specification introduces Supplier as distinct role (maps to Shipper entity but treated differently for MSG-CLR purposes).

---

## 10. Acceptance Criteria Derivation Guidance for Business Analysts

This specification provides the WHAT and HOW of the OEM Client ID/TIN registration feature. Business Analysts are responsible for:

1. **Decomposing into testable work items**: Determine appropriate story granularity (e.g., separate stories for MSG-CLR submission vs MSG-CLRR processing vs postal code validation)

2. **Writing user-facing acceptance criteria**: Translate technical mapping rules (§2) into "Given/When/Then" scenarios from broker perspective

3. **Identifying edge cases**: Use business rules (§3) and error handling (§5) to derive negative test scenarios

4. **Defining test data requirements**: Based on segment reference (§1), create test MSG-CLRR messages with various CNT+55 values, FTX+AAO error texts, etc.

5. **Cross-referencing sections**: A single story (e.g., "Process MSG-CLRR response for Importer") requires reading:
   - §1.2 for message structure
   - §2.2 for data storage destinations
   - §4 for status transitions
   - §5.1 for error processing
   - §6.1 for remark popup display
   
   The BA must synthesize these scattered requirements into a cohesive, testable story.

**Example Synthesis** (NOT a story, but demonstration of cross-section integration):

"When a MSG-CLRR message is received for an import shipment with Sender Reference Version = '1' (matching CLREGSRV indicating Importer), and CNT+55 value = 0 (no errors), and FTX+CCI segment contains OEM Client ID '12345678901', and Shipment > Importer > Profile has Carrier Co Account 'AUSYD001':
- Store OEM Client ID to Shipment > Importer > Profile > Comments > OID > Comment Text = '12345678901' (per §2.2.1)
- Set Brokerage Status OID = CMP (per §4.2)
- Remove CLS comment from Importer profile (per §3.5)
- Check if Shipper profile has OID or TIN (per §4.3):
  - If Shipper OID/TIN exists: Overall OID status remains CMP
  - If Shipper OID/TIN missing: Overall OID status = SNT (awaiting Supplier MSG-CLR response)
- Do NOT display remark popup (OID status = CMP, no errors) (per §6.1)"

This level of detail, derived from multiple spec sections, forms the basis for acceptance criteria.

---

**End of Technical Specification**

User stories:

title: Enhance Postal code Validation
description: As a RATER, I want to validate the post code of both export & import shipments so that I can avoid shipment going into wrong location and interventions.
acceptance_criteria: As is: Export & Import shipment: For both Export & Import system is checking Importer address Country & Postal code = AU so, all the export shipment is settling in INTERVENTION ref User Story 4722122: Postal code Validation To be: Irrespective of any address (shipper, importer) for all the shipment system to check whether address country code = AU or non-AU Please refer the below SS for reference. If country code = AU do the below 2 checks Check 1: Is Postal code = any of the AU postal code and City = related to that postal code --> proceed further,if not move the shipment to INT and add "AU ADDRESS WITH INVALID POSTAL CODE" in remarks pop up. Check 2: Is Address line1 is filled --> proceed furtherif not move the shipment to INT and add "INCOMPLETE AU ADDRESS" in remarks pop up. If country code = non-AU do the below 1 check Check 1: Is following items is filled Name, Address line 1 & Country code proceed further, if anyone items are not filled move the shipment to INT and add "INCOMPLETE OVERSEAS ADDRESS" in remarks pop up. User Story 4722122: Postal code Validation -> (enhancing point 2 - MET/NMT) Irrespective of shipper & importer address check whether postal code & city = AU comes under MET If postal code & city coming under MET set shipment brokerage status type = MET If postal code & city not coming under MET set shipment brokerage status type = NMT If postal code & city itself is not matching set shipment brokerage status type = NIL

title: Update process logic for multiple segments in MSG-CLRR
description: As a SBSS user, I want MSG-CLRR messages to be processed correctly based on customs regulations.
acceptance_criteria: Add new reference in SBSS Admin with script SBSS Admin table: Shipment Reference Number Type Data to be added: Code Description Parent Type Code Quick Searchable TIN Australian Business Number AD CLREGERR Error encountered in a Registration Message CUREF SBSS mappings: Declaration>Customer>Tax ID>Reference>TIN Declaration>Mic>Customer Supplied References>CLREGERR When a MSG-CLRR is received, process multiple segments as below: Process RFF+ABO (already developed) Map 1154 - Sender Reference with Declaration>Customs>Reference Numbers>URN to identify the shipment MSG-CLRR corresponds to. Remove the logic of setting Brokerage Status OID to ATN Process FTX (1) (already developed) When FTX+CCI or FTX+TIN is received, check shipment type based on logic below: The shipment is an import one if Import Country is AU The shipment is an export one if Export Country is AU If current shipment is an export one Check if Carrier Co Account is available on Shipment>Shipper>Profile page to define matched customer If Carrier Co Account is available on Shipper Profile page Store the value of element 4441 - Customs Client Id in Shipment>Shipper>Profile>Comments>OID>Comment Text for FTX+CCI Store the value of element 4441 - Australian Business Number in Shipment>Shipper>Profile>Comments>TIN>Comment Text for FTX+TIN Remove Comment CLS from Shipment>Shipper>Profile page in the meantime If Carrier Co Account is unavailable on Shipper Profile page Store the value of element 4441 - Customs Client Id in Declaration>Customer>Shipper>Tax ID>Reference Numbers>OID>Number for FTX+CCI Store the value of element 4441 - Australian Business Number in Declaration>Customer>Shipper>Tax ID>Reference Numbers>TIN>Number for FTX+TIN If current shipment is an import one Map MSG-CLRR and corresponding MSG-CLR based on Sender Reference Version (User Story 6678567) to define Role Name If Role Name in corresponding MSG-CLR is Importer, check Carrier Co Account is available on Importer Profile page to define matched customer If Carrier Co Account is available on Importer Profile page Store the value of element 4441 - Customs Client Id in Shipment>Importer>Profile>Comments>OID>Comment Text for FTX+CCI Store the value of element 4441 - Australian Business Number in Shipment>Importer>Profile>Comments>TIN>Comment Text for FTX+TIN Remove Comment CLS from Shipment>Importer>Profile page in the meantime If Carrier Co Account is unavailable on Importer Profile page Store the value of element 4441 - Customs Client Id in Declaration>Customer>Importer>Tax ID>Reference Numbers>OID>Number for FTX+CCI Store the value of element 4441 - Australian Business Number in Declaration>Customer>Importer>Tax ID>Reference Numbers>TIN>Number for FTX+TIN If Role Name in corresponding MSG-CLR is Supplier, check Carrier Co Account is available on Shipper Profile page to define matched customer If Carrier Co Account is available on Shipper Profile page Store the value of element 4441 - Customs Client Id in Shipment>Shipper>Profile>Comments>OID>Comment Text for FTX+CCI Store the value of element 4441 - Australian Business Number in Shipment>Shipper>Profile>Comments>TIN>Comment Text for FTX+TIN Remove Comment CLS from Shipment>Shipper>Profile page in the meantime If Carrier Co Account is unavailable on Shipper Profile page Store the value of element 4441 - Customs Client Id in Declaration>Customer>Shipper>Tax ID>Reference Numbers>OID>Number for FTX+CCI Store the value of element 4441 - Australian Business Number in Declaration>Customer>Shipper>Tax ID>Reference Numbers>TIN>Number for FTX+TIN When FTX+CCI or FTX +TIN is processed, set Brokerage Status>OID to CMP. Process CNT+55 When the value of element 6066 - Total Comments > 0, set Brokerage Status>OID to ERR Remove Comment CLS from corresponding Customer Profile page. Process FTX+AAO When Brokerage Status OID is set to ERR, store the value of element 4440 - Message Text in Declaration>Misc>Customer Supplied References>CLREGERR>Comment Message Text in multiple FTX+AAO segments should be stored in different CLREGERR respectively

title: OID in customer profile
description: As a RATER I want to add OID in customer profile even If I capture the data manually so that I can we don't miss the OID value in customer profile.
acceptance_criteria: As is: If OID has been entered/capture (manually) in FZ/CW# field, it will not be reflected in customer profile. To be: Adding OID under Address (full turbo) User should be able to add OID under reference number > OID or directly in FZ/CW# field Format: Alpha numeric 11 Validation: If character limit exceeds 11 system need to through the error. If user entered OID under reference number, it needs to be reflected in FZ/CW# and vice versa. Adding OID under shipper/Importer's profile (only for interactive mode) Upon adding OID in address, by tab out system need to open a pop up with "Would you like to save the OID in Shipper/Importer's profile" If yes save the OID in Shipper/Importer's profile If no, let it be. Mapping: Export shipment: Full turbo > Address > Shipper > FZ/CW#(OID) ---> Shipper profile > Comments Full turbo > Address > Importer> FZ/CW#(OID) ---> Disregard the input Import shipment: Full turbo > Address > Shipper> FZ/CW#(OID) ---> Shipper profile > Comments Full turbo > Address > Importer> FZ/CW#(OID) ---> Importer profile > Comments (Shipper/Importer's) Customer profile > Comments

title: Update to TIR Hold Removal Conditions to Include Provision of OEM Client ID
description: As a SBSS user, I want to remove any existing holds related to "Tax ID Required" when either an TIN (Australian Business Number) or OEM Client ID (Customs Client ID) is provided.
acceptance_criteria: As described in User Story 4976070: RAT to RAT Hold Reasons, currently, upon saving: For Import, if CT = FML: If Full Turbo > Address > Importer > Tax ID ⁽¹⁾ is blank: RAT Hold Reason TIR will be added to the Declaration and RAT set to HLD. If Full Turbo > ... > Importer > Tax ID is not blank and RAT Hold Reason TIR exists on the Declaration: RAT Hold Reason TIR will be removed and RAT set as per segregation logic. For Export, if CT = FML: If Full Turbo > Address > Shipper > Tax ID ⁽²⁾ is blank: RAT Hold Reason TIR will be added to the Declaration and RAT set to HLD. If Full Turbo > ... > Shipper > Tax ID is not blank and RAT Hold Reason TIR exists on the Declaration: RAT Hold Reason TIR will be removed and RAT set as per segregation logic. This functionality must be updated to: For Import, if CT = FML: If Full Turbo > Address > Importer > Tax ID is blank and Full Turbo > Address > Importer > FZ / CW # ⁽³⁾ is blank: RAT Hold Reason TIR will be added to the Declaration and RAT set to HLD. If Full Turbo > ... > Importer > Tax ID is not blank or Full Turbo > ... > Importer > FZ / CW # is not blank, and RAT Hold Reason TIR exists on the Declaration: RAT Hold Reason TIR will be removed and RAT set as per segregation logic. For Export, if CT = FML: If Full Turbo > Address > Shipper > Tax ID is blank and Full Turbo > Address > Shipper > FZ / CW # is blank: RAT Hold Reason TIR will be added to the Declaration and RAT set to HLD. If Full Turbo > ... > Shipper > Tax ID is not blank or Full Turbo > ... > Shipper > FZ / CW # is not blank, and RAT Hold Reason TIR exists on the Declaration: RAT Hold Reason TIR will be removed and RAT set as per segregation logic. ⁽¹⁾ Presumed to be connected with Declaration > Customer > Importer > Tax ID, as per User Story 4252970: [Project-A Country Name] Business Number (TIN). ⁽²⁾ Presumed to be connected with Declaration > Customer > Shipper > Tax ID, as per User Story 4252970: [Project-A Country Name] Business Number (TIN). ⁽³⁾ Presumed to be connected with Customer Profile > Profile > Comments > OID, as per User Story 4976163: OID Removal from TAXID and TIN/OID consider from customer accounts.

title: Update process logic for multiple segments in CLNTDUP
description: As a SBSS user, I want CLNDUP messages to be processed correctly based on customs regulations.
acceptance_criteria: Prerequisite The requirement needs to be implemented based on the following user story: User Story 6606329: Update process logic for multiple segments in MSG-CLRR When a CLNTDUP is received, process multiple segments as below: Process RFF+ABO Map 1154 - Sender Reference with Declaration>Customs>Reference Numbers>URN to identify the shipment CLNTDUP corresponds to. Remove the logic of setting Brokerage Status OID to ATN Process DOC and TAX Check the value of element 5152 - Role Name in Segment TAX+RN If the value is IMPORTER, check if Carrier Co Account is available on Shipment>Importer>Profile page for matched customer validation If Carrier Co Account is available Store the value of element 1000 - Customs Client Id in Shipment>Importer>Profile>Comments>OID>Comment Text for DOC+CCI Store the value of element 1000 - Australian Business Number in Shipment>Importer>Profile>Comments>TIN>Comment Text for DOC+TIN Remove Comment CLS from Shipment>Shipper>Profile page in the meantime If Carrier Co Account is unavailable Store the value of element 1000 - Customs Client Id in Declaration>Customer>Importer>Tax ID>Reference Numbers>OID>Number for DOC+CCI Store the value of element 1000 - Australian Business Number in Declaration>Customer>Importer>Tax ID>Reference Numbers>TIN>Number for DOC+TIN If the value is EXPORTER or SUPPLIER, check if Carrier Co Account is available on Shipment>Shipper>Profile page for matched customer validation If Carrier Co Account is available Store the value of element 1000 - Customs Client Id in Shipment>Shipper>Profile>Comments>OID>Comment Text for DOC+CCI Store the value of element 1000 - Australian Business Number in Shipment>Shipper>Profile>Comments>TIN>Comment Text for DOC+TIN Remove Comment CLS from Shipment>Shipper>Profile page in the meantime If Carrier Co Account is unavailable Store the value of element 1000 - Customs Client Id in Declaration>Customer>Shipper>Tax ID>Reference Numbers>OID>Number for DOC+CCI Store the value of element 1000 - Australian Business Number in Declaration>Customer>Shipper>Tax ID>Reference Numbers>TIN>Number for DOC+TIN When DOC+CCI or DOC +TIN is processed, set Brokerage Status>OID to CMP.

title: Improvements on MSG-CLR mapping, trigger point and validation
description: As a SBSS user, I want MSG-CLR messages to be mapped, triggered and validated correctly based on customs regulations
acceptance_criteria: MSG-CLR message mappings RFF+TIN: Element 4000 - CAC Address Type Mapping: the data after "CAC Address Type =" in Declaration Comment CCO, COI or COS FTX+ATY: Element 4453 - Address Type Mapping: Fixed value "BA" FTX+CAT: Element 4453 - Contact Address Type Mapping: Fixed value "BA" TDT+1 Only included when LOC+ZZZ is available in the message Only added when Client Type is ORG CNI+1: Always include the segment RFF+1: Always include the segment GID+1: Always include the segment LOC+DN: Element 3225 - Document Number Mapping: The first digit after "Travel Documents =" in Declaration Comment CCI, CII or CIS LOC+ISS: Element 3225 - Country Of Issue Mapping: Data after the first digit and "," before the second digit AUT+GE: Only include when Client Type is IND DTM+329: Only include when Client Type is IND MSG-CLR message trigger point When a MSG-CLR message needs to be triggered, raise an error with different reminder under different condition Raise the error with reminder "Client registration message has already been sent." when Declaration Comment CII or COI is added and Shipment>Importer>Profile>Comments>CLS is available Declaration Comment CCI or CCO is added and Shipment>Shipper>Profile>Comments>CLS is available Declaration Comment CIS or COS is added and Shipment>Shipper>Profile>Comments>CLS is available Raise the error with reminder "OEM Client ID has already been registered." when Scenario A Declaration Comment CII or COI is added and Shipment>Importer>Profile>Comments>OID is available, or Declaration Comment CII or COI is added and Declaration>Customer>Importer>Tax Id>Reference Numbers>OID is available Scenario B Declaration Comment CCI, CCO, CIS or COS is added and Shipment>Shipper>Profile>Comments>OID is available, or Declaration Comment CCI, CCO, CIS or COS is added and Declaration>Customer>Shipper>Tax Id>Reference Numbers>OID is available Raise the error with reminder "TIN has already been registered." when Scenario A Declaration Comment CII or COI is added and Shipment>Importer>Profile>Comments>TIN is available, or Declaration Comment CII or COI is added and Declaration>Customer>Importer>Tax Id>Reference Numbers>TIN is available Scenario B Declaration Comment CCI, CCO, CIS or COS is added and Shipment>Shipper>Profile>Comments>TIN is available, or Declaration Comment CCI, CCO, CIS or COS is added and Declaration>Customer>Shipper>Tax Id>Reference Numbers>TIN is available MSG-CLR submission should be blocked after the message is sent, or the response is received for the same customer type. Therefore, when any error above is raised, MSG-CLR should not be sent in the meantime. MSG-CLR message validation When TIN is added in Declaration Comment CCO, COI or COS, check if the message include mandatory data as below: RFF+TIN: 1154 - Australian Business Number FTX+CNP: 4440 - Contact Name FTX+CNP: 4440 - Contact Purpose FTX+CAT: 4440 - Address Line 1 MEA+RN: 6165 - Role Name

title: Enhance Postal code validation (ADD)
description: As a RATER I want to validate the postal code and city whenever there is a change so that shipment brokerage status update accordingly.
acceptance_criteria: Continuation of User Story 6563451: Enhance Postal code Validation Navigation: Declaration > Shipper & Importer > Address > Postal code & City New logic: Whenever there is a change in postal code & city check whether both are in sync and its province in Master town table. If postal code & city is in sync check whether its province = MET, then set shipment brokerage status = MET If postal code & city is in sync check whether its province = Blank, then set shipment brokerage status = NMT If postal code & city is in not sync, then set shipment brokerage status = NIL Above changes applies for both export & import shipment Trigger point: Tab out of each field (Postal code & City) Impact area: shipment brokerage status

title: Map MSG-CLRR and MSG-CLR based on Sender Reference Version
description: As a SBSS user, I want MSG-CLRR and MSG-CLR for import shipments to be mapped based on Sender Reference Version to define Role Name the messages refer to.
acceptance_criteria: The logic below is only applied for import shipments with two MSG-CLR messages Add New reference in SBSS Admin with script SBSS Admin table: Shipment Reference Number Type Data to be added: Code Description Parent Type Code Quick Searchable CLREGSRV MSG-CLR Sender Reference Version CUREF SBSS mapping: Declaration>Mic>Customer Supplied References>CLREGSRV MSG-CLR Sender Reference Version reflection When a MSG-CLR message needs to be triggered for an import shipment Fetch the following data in the message The value of element 1056 - Sender Reference Version in BGM segment The value of element 6154 - Role Name in MEA segment Store the data in CLREGSRV Store Sender Reference Version in Declaration>Mic>Customer Supplied References>CLREGSRV>Number Store Role Name in Declaration>Mic>Customer Supplied References>CLREGERV>Comment MSG-CLR Sender Reference Version logic Apply unique value of element 1056 - Sender Reference Version in BGM segment of MSG-CLR messages for import shipments. For example When the first MSG-CLR message is triggered for an import shipment, element 1056 - Sender Reference Version in BGM segment of the message should be set to 1. When the second MSG-CLR message is triggered for an import shipment, element 1056 - Sender Reference Version in BGM segment of the message should be set to 2. When MSG-CLR message for both Importer and Supplier are sent for an import shipment, there should be two CLREGSRV added as below: If the first MSG-CLR message is sent for Importer, the first CLREGSRV>Number should be 1, the first CLREGSRV>Comment should be Importer. If the second MSG-CLR message is sent for Supplier, the second CLREGSRV>Number should be 2, the second CLREGSRV>Comment should be Supplier. Apply CLREGSRV to map MSG-CLRR and MSG-CLR and define customer type When a MSG-CLRR message is received on an import shipment Check the value of element 4000 - Sender Reference Version in RFF+ABO segment Map Sender Reference Version with the data in Declaration>Mic>Customer Supplied References>CLREGSRV>Number to define corresponding MSG-CLR Once corresponding MSG-CLR is mapped, check the data in Declaration>Mic>Customer Supplied References>CLREGSRV>Comment. Process FTX+CCI or FTX+TIN segment in MSG-CLRR message based on logic of User Story 6606329. If the data in CLREGSRV Comment filed is Importer, then process FTX+CCI or FTX+TIN on Importer. If the data in CLREGSRV Comment filed is Supplier, then process FTX+CCI or FTX+TIN on Shipper.

title: Enhance OEM Client ID form
description: As a RATER I want to enable CAC address type all the time with BA as default value when organization is selected.
acceptance_criteria: Enhance OEM Client ID form Navigation: Declaration entry form > customer client identifier > CAC address type As is: To be: Changes: Remove the CAC from "CAC Address type" Correct the typo of Adress type -> Address type above 2 points are common for OEM Client ID form. Remove the linkage between CAC & Address type above point is applicable only for organization + role: Importer & Exporter Enable address type with BA (Business Address) as default value. above point is applicable for organization irrespective of role. Enable address type alone above point is applicable for Individual irrespective of role. TIN & CAC remain disabled for individual irrespective of role

title: Update the mapping logic of Address Type for MSG-CLR
description: As a SBSS user, I want the mappings relevant to Address Type in multiple segments in MSG-CLR message.
acceptance_criteria: Prerequisites The current story needs to be implemented based on the following changes on OEM Client ID form from Savages: The naming of "CAC Address Type" dropdown list will be changed to "Address Type" "Address Type" dropdown list will be enabled all the time for IND, ORG and TIN. Once users select an address type and submit the data on OEM Client ID form, "Address Type = BA" or "Address Type = PA" should be reflected on any Declaration Comment related to MSG-CLR accordingly. Update the mapping of following elements in MSG-CLR message RFF+TIN Element: 4000 - CAC Address Type Updated mapping: Data after "Address Type =" in Declaration Comment CCO, COI or COS, only applied for "TIN' FTX+ATY Element: 4453 - Address Type Updated mapping: Data after "Address Type =" in Declaration Comment CCI, CII, CIS, CCO, COI or COS FTX+CAT Element: 4453 - Contact Address Type Updated mapping: Data after "Address Type =" in Declaration Comment CCI, CII, CIS, CCO, COI or COS Update the validation logic on Address Line 2 4440 - Address Line 2 in FTX+ATY and FTX+CAT should not be mandatory. Remove mandatory field validation on this element.

title: Improvement on logic of customer profile comment TIN for MSG-CLR messaging
description: As a SBSS user, I want MSG-CLR messages to be triggered on the circumstances that comment TIN is added on customer profile page before MSG-CLRR or CLNTDUP received.
acceptance_criteria: The logic below is required since some conflict is found between the following user stories: User Story 4252970: [Project-A Country Name] Business Number (TIN) User Story 6653275: Improvements on MSG-CLR mapping, trigger point and validation Current TIN logic on SBSS UI When users take the following actions Add or modify Tax ID on full turbo or Declaration Customer page Send OEM Client ID form with new TIN# which is reflected as Tax ID There will be a window popup to ask if they want to store the TIN# to the Shipper/Importer's profile. If they hit Yes, comment TIN will be added on Shipment Customer Profile page with TIN# added in Comment Text field Improvement requirement Add new reference to SBSS Admin with script SBSS Admin table: Shipment Reference Number Type Data to be added: Code Description Parent Type Code Quick Searchable TIN TIN# in response message CUREF SBSS UI mapping: Declaration>Misc>Customer Supplied References>TIN When the following messages are received MSG-CLRR message including FTX+TIN CLNTDUP message including DOC+TIN Check if the shipment has matched customer based on Carrier Co account If the shipment does not have matched customer, store TIN number in Declaration>Customer>Tax ID>Reference Numbers>TIN If the shipment has matched customer, check if Comment TIN is available on Shipment Customer Profile page. If Comment TIN is available, store Australian Business Number in FTX+TIN or DOC+TIN to: Declaration>Misc>Customer Supplied References>TIN>Ref Comment If Comment TIN is unavailable, store Australian Business Number in FTX+TIN or DOC+TIN to: Shipment>Customer Profile>Comments>TIN Declaration>Misc>Customer Supplied References>TIN>Ref Comment Once Declaration Customer Supplied Reference TIN is added, remove Comment CLS from Customer Profile page in the meantime. When a MSG-CLR message is triggered, take the actions accordingly: For export shipment Block MSG-CLR message submission and raise an error with reminder "Client registration message has already been sent." when Only CLS is available on Shipment Shipper Profile page Both CLS and TIN are available on Shipment Shipper Profile page Block MSG-CLR message submission and raise an error with reminder "TIN has already been registered." when Declaration>Misc>Customer Supplied References>TIN is available Submit MSG-CLR message when Neither CLS nor TIN is available on Shipment Shipper Profile page Only TIN is available on Shipment Shipper Profile page and Declaration>Misc>Customer Supplied References>TIN is unavailable For import shipment Block MSG-CLR message submission and raise an error with reminder "Client registration message has already been sent." when The message is on Importer and CLS is available on Shipment Importer Profile page The message is on Shipper and CLS is available on Shipment Shipper Profile page The message is on Importer and both CLS and TIN are available on Shipment Importer Profile page The message is on Shipper and both CLS and TIN are available on Shipment Shipper Profile page Block MSG-CLR message submission and raise an error with reminder "TIN has already been registered." when The message is on Importer and Declaration>Misc>Customer Supplied References>TIN with Role Name "IMPORTER" is available The message is on Supplier and Declaration>Misc>Customer Supplied References>TIN with Role Name "SUPPIER" is available Notes: The improvement requirement is only on TIN relevant logic of MSG-CLR messaging. The requirement above not marked in red are existing logic and no need to be updated.

title: Update the TIN mapping logic in MSG-CLR for supplier
description: As a SBSS user, I want TIN# for supplier to be mapped correctly based on business requirement.
acceptance_criteria: The requirement below is only applicable to: Shipment type: Import 6154 - Role Name in MEA+RN segment Supplier Confirmed logic on OEM Client ID form When "Organization" and "Supplier" are both selected on OEM Client ID form, TIN field is disabled so no TIN# is allowed to be sent for supplier. Mapping logic change Remove Declaration Comment COS from TIN mapping 1153 - Australian Business Number in RFF+TIN should only be mapped to data after "TIN =" in Declaration Comment COI for import shipments

title: Improvement of MSG-CLR, MSG-CLRR and CLNTDUP logic
description: As a SBSS user, I want multiple logic for MSG-CLR submission, MSG-CLRR and CLNTDUP process to be improved based on QA findings and BPO's requirement.
acceptance_criteria: Purpose of the story Covering ITPO requirement missed in last sprint Add some backend technical logic to fulfill ITPO requirement Fix some bugs found in demo meeting Store Role Name in Customer Supplied Reference with capital letters When a MSG-CLR message is triggered for an import shipment Fetch the following data in the message The value of element 1056 - Sender Reference Version in BGM segment The value of element 6154 - Role Name in MEA segment Store the data in CLREGSRV Store Sender Reference Version in Declaration>Mic>Customer Supplied References>CLREGSRV>Number Store Role Name in Declaration>Mic>Customer Supplied References>CLREGSRV>Comment with capital letters, i.e. SUPPLIER. Apply Brokerage Status OID to both OEM Client ID and TIN When MSG-CLR message needs to be submitted or MSG-CLRR/CLNTDUP needs to be processed, apply the following statuses for both OEM Client ID and TIN Brokerage Status OID>RFC Brokerage Status OID>SNT Brokerage Status OID>CMP Brokerage Status OID>ERR Savages will help change "Address type" to "Address Type" from their side. (@Reddy Rahul (ZTH2PZZ) @Raghupathi Aravind (NWP9CKL)) Add CLS validation when two MSG-CLR messages need to be sent for an import shipment Allow users to sent two MSG-CLR messages, one on Importer, the other one on Supplier, for an import shipment. Validate Comment CLS on Shipment Customer Profile when the second MSG-CLR message is triggered. Remove CLS when OID changed to ERR When a MSG-CLRR message is received, check segment CNT+55. If the value of element 6066 - Total Comments > 0 Set Brokerage Status>OID to ERR (already covered in User Story 6606329) Remove Comment CLS from corresponding Customer Profile page Update mandatory element validation logic on MSG-CLR The following elements should not be mandatory in MSG-CLR - Individual 4440 - First Name 4440 - Second Name 4440 - Suffix

title: Add MSG-CLRR error responses in remark popup
description: As a SBSS user, I want the error responses included in MSG-CLRR to be reflected in remark pop up so that I can know MSG-CLR messaging status when the shipment is opened.
acceptance_criteria: The requirement below is to improve the logic of the following user story for the purpose of making MSG-CLRR response more visible to users: User Story 6606329: Update process logic for multiple segments in MSG-CLRR Improvement requirement Update the code and description of the following Customer Supplied Reference SBSS Admin table: Shipment Reference Number Type Current data: Code Description Parent Type Code Quick Searchable CLREGERR Error encountered in a Registration Message CUREF Updated data: Code Description Parent Type Code Quick Searchable CLREGRED MSG-CLR Response Error Description CUREF Improve the process logic of FTX+AAO segment When a MSG-CLRR message is received and Brokerage Status>OID is set to ERR accordingly Check the current shipment is an export or import one If it's an export shipment Store "EXPORTER" in Declaration>Misc>Customer Supplied References>CLREGRED>Number Store the values of element 4440 - Message Text in Declaration>Misc>Customer Supplied References>CLREGRED>Comment (already developed in User Story 6606329) If CLREGRED already added on Customer Supplied References, replace all the existing CLREGRED items with the values of element 4440 - Message Text in the latest MSG-CLRR. If it's an import shipment Map MSG-CLRR with corresponding MSG-CLR with Sender Reference Version based on the logic of User Story 6678567. If the error response is on MSG-CLR - Importer Store "IMPORTER" in Declaration>Misc>Customer Supplied References>CLREGRED>Number Store the values of element 4440 - Message Text in Declaration>Misc>Customer Supplied References>CLREGRED>Comment If the error response is on MSG-CLR - Supplier Store "SUPPLIER" in Declaration>Misc>Customer Supplied References>CLREGRED>Number Store the values of element 4440 - Message Text in Declaration>Misc>Customer Supplied References>CLREGRED>Comment If there are multiple FTX+AAO segments, each Message Text should be stored in different CLREGRED respectively with same Role Name, like IMPORTER or SUPPLIER. If CLREGRED already added on Customer Supplied References, replace all the existing CLREGRED items with the values of element 4440 - Message Text in the latest MSG-CLRR. When the following conditions are fulfilled on SBSS UI: Brokerage Status>OID is set to ERR Declaration>Mic>Customer Supplied References>CLREGRED is available Reflect the error response in Remark popup when the shipment is opened with format below: Title: Error Response on Client Registration Message - XXX Content: The data fetched from CLREGRED>Comment filed XXX refers to Role Name in MSG-CLR message got error. Replace XXX with the data from Declaration>Mic>Customer Supplied References>CLREGRED>Number in the title Reflect all data from Declaration>Mic>Customer Supplied References>CLREGRED>Comment correspondingly beneath. If there are more than one error response, each CLREGRED item should be reflected in a specific line. For import shipment, if CLREGRED are added on both Importer and Supplier, they should be reflected in Remark popup in two sections respectively, refer to the screenshot below. When shipment is opened on SBSS, check if Brokerage Status>OID is ERR. If yes, fetch the latest data from CLREGRED and reflect the data in Remark popup. MSG-CLRR error response will only be reflected in Remark popup when Brokerage Status>OID is ERR. If Brokerage Status>OID is changed to CMP, no need to reflect even if CLREGRED is available. Remark popup format reference

title: Enhance OEM Client ID form (1)
description: As a RATER I want to enable CAC address type all the time with BA as default value when organization is selected.
acceptance_criteria: Enhance OEM Client ID form Navigation: Declaration entry form > customer client identifier > CAC address type As is: To be: Changes: Correct the typo of Address type -> Address Type (common) set address type with BA (Business Address) as default value for individual (irrespective of any role)

title: Update Brokerage Status OID setup logic for import shipments
description: As a SBSS user, I want Brokerage Status OID on import shipment to be setup correctly based on business requirement.
acceptance_criteria: Background The purpose of the user story is to improve Brokerage Status OID setup logic on import shipments with two MSG-CLR messages. According to business requirement on import shipments OID/TIN needs to be added on Importer OID needs to be added on Shipper (Supplier) Brokerage Status OID should be set to CMP when both conditions above are fulfilled. Improvement requirement When MSG-CLRR message is received on an import shipment Check 6066 - Total Comments in CNT+55 segment If Total Comments > 0, set Brokerage Status OID to ERR. If Total Comments = 0, define Role Name the message corresponds to based on Sender Reference Version. If Role Name is Importer, check the following data on SBSS UI: If Shipment>Shipper>Profile>Comments>OID is available If Declaration>Customer>Shipper>Tax ID>Reference Numbers>OID is available If none data above is available, keep Brokerage Status OID as SNT. If any data above is available, set Brokerage Status OID to CMP. If Role Name is Supplier, check the following data on SBSS UI: If Shipment>Importer>Profile>Comments>OID is available If Declaration>Customer>Importer>Tax ID>Reference Numbers>OID is available If Declaration>Customer>Importer>Tax ID>Reference Numbers>TIN is available If Declaration>Misc>Customer Supplied References>TIN is available If none data above is available, keep Brokerage Status OID as SNT. If any data above is available, set Brokerage Status OID to CMP. When CLNTDUP message is received on an import shipment Check 5152 - Role Name in TAX+RN segment If Role Name is Importer, check the following data on SBSS UI: If Shipment>Shipper>Profile>Comments>OID is available If Declaration>Customer>Shipper>Tax ID>Reference Numbers>OID is available If none data above is available, keep Brokerage Status OID as SNT. If any data above is available, set Brokerage Status OID to CMP. If Role Name is Supplier, check the following data on SBSS UI: If Shipment>Importer>Profile>Comments>OID is available If Declaration>Customer>Importer>Tax ID>Reference Numbers>OID is available If Declaration>Customer>Importer>Tax ID>Reference Numbers>TIN is available If Declaration>Misc>Customer Supplied References>TIN is available If none data above is available, keep Brokerage Status OID as SNT. If any data above is available, set Brokerage Status OID to CMP.

title: Enhancement to TIR Hold Removal Conditions for Import Shipments
description: As a SBSS user, I want to remove any existing holds related to "Tax ID Required" when either an TIN (Australian Business Number) or OEM Client ID (Customs Client ID) is provided. Specifically, the conditions for Import shipments must be enhanced to factor-in the presence (or absence) of the Exporter / Shipper Tax ID and / or OEM Client ID.
acceptance_criteria: As described in User Story 6644525: Update to TIR Hold Removal Conditions to Include Provision of OEM Client ID, currently, upon saving: For Import, if CT = FML: If Full Turbo > Address > Importer > Tax ID ⁽¹⁾ is blank and Full Turbo > Address > Importer > FZ / CW # ⁽²⁾ is blank: RAT Hold Reason TIR will be added to the Declaration and RAT set to HLD. If Full Turbo > ... > Importer > Tax ID is not blank or Full Turbo > ... > Importer > FZ / CW # is not blank, and RAT Hold Reason TIR exists on the Declaration: RAT Hold Reason TIR will be removed and RAT set as per segregation logic. This functionality must be updated to: For Import, if CT = FML: If (Full Turbo > ... > Importer > Tax ID is blank and Full Turbo > ... > Importer > FZ / CW # is blank) or (Full Turbo > Address > Exporter > Tax ID ⁽³⁾ is blank and Full Turbo > Address > Exporter > FZ / CW # is blank): RAT Hold Reason TIR will be added to the Declaration and RAT set to HLD. If (Full Turbo > ... > Importer > Tax ID is not blank or Full Turbo > ... > Importer > FZ / CW # is not blank) and (Full Turbo > ... > Exporter > Tax ID is not blank or Full Turbo > ... > Exporter > FZ / CW # is not blank) and RAT Hold Reason TIR exists on the Declaration: RAT Hold Reason TIR will be removed and RAT set as per segregation logic. ⁽¹⁾ Presumed to be connected with Declaration > Customer > Importer > Tax ID, as per User Story 4252970: [Project-A Country Name] Business Number (TIN). ⁽²⁾ Presumed to be connected with Customer Profile > Profile > Comments > OID, as per User Story 4976163: OID Removal from TAXID and TIN/OID consider from customer accounts. ⁽³⁾ Presumed to be connected with Declaration > Customer > Shipper > Tax ID, as per User Story 4252970: [Project-A Country Name] Business Number (TIN).

title: OEM Client ID | Name mapping
description: As a RATER I want to consider other fields in Name section on top of FAMILY so that I will send full name of the individual to customs.Predecessor: User Story 5534700: Customs Client ID (OID) Application & Submission – Individual & Organization
acceptance_criteria: OEM Client ID form As is: Individual -> Role: Exporter, Importer & Supplier Name section: system considered only below following field. Family To be: Individual -> Role: Exporter, Importer & Supplier Name section: The system should consider below following fields in the specified hierarchy First Second family suffix Example: First: Gail Second: JulietaFamily: BuenaventuraSuffix: III Full name: Gail Julieta Buenaventura III