Landside Customs Clearance Specification (Export from Gravity)

1 Introduction
2 File Specification
- 2.1 File Type
- 2.2 Filename Convention
- 2.3 File Transfer
- 2.4 Error Handling
3 Schema
- 3.1 Customs Clearance Elements
- 3.2 Shipment Booking Elements
- 3.3 Shipment Order Elements
- 3.4 Shipment Item Elements
- 3.5 Node Elements
  - 3.5.1 Node Address Elements
4 XSD
5 Sample Landside Customs Clearance Export XML File

Introduction

This document is intended to provide specification requirements to enable the file-based Integration of Landside Customs Clearance Export within Gravity Supply Chain’s (GSC) Purchase Order Management (POM) product.

File Specification

File Type

The file format used to integrate Landside Customs Clearance data into GSC must be XML. The XML file must adhere to the XSD in the document below.

Filename Convention

All Customs Clearance exported files will follow the naming convention listed here:

CustomerFilePrefix_LandsideCustomsClearanceExport_YYYYMMDDhhmmss.xml

File Transfer

XML files generated will be transferred by push to an external FTP server (Customer/Forwarder). The Customer/Forwarder should provide credentials during implementation.

Error Handling

Should the XML file generation, Export process or File transfer encounter any errors, they would be logged and presented on the platform.

Schema

Customs Clearance Elements

Element	Description	Mandatory?	Data Type	Max Length	Example
AgentNumber	Agent number	Y	nvarchar	250	S208575 OB
BrokerNode	Broker node	N	See section Node Elements
EntryNumber	Customs entry number	N	nvarchar	250	AC6NK776R
EntryDate	Customs entry date	Y	dateTime		2018-05-06 16:40:03
ClearanceDate	Date of clearance	Y	dateTime		2018-05-06 16:40:03
EquipmentNumber	Container Number or MAWB Number	Y	nvarchar	14	MSKU1234565
HouseBill	Shipment HouseBill Number	Y	nvarchar	250	HBL12345678
Seal	Container Seal Number	Y	nvarchar	50	34567
ClearedBy	Username of the user who confirmed the customs clearance	Y	nvarchar	50	chris.wong
ClearedAt	The moment when the clearance was confirmed	Y	dateTime		2018-05-06 16:40:03
ShipmentBookings	Array of shipment bookings	Y	See section Shipment Booking Elements

Shipment Booking Elements

Element	Description	Mandatory?	Data Type	Max Length	Example
ThreePLBookingReference	3PL shipment booking reference	Y	nvarchar	250	REF-1234
ShipmentOrders	Array of shipped purchase orders	Y	See section Shipment Order Elements

Shipment Order Elements

Element	Description	Mandatory?	Data Type	Max Length	Example
OrderNumber	PO number	Y	nvarchar	250	PO1234
Identifier	Call off/Drop	N	nvarchar	250	Drop1001
ShipmentItems	Array of shipped purchase order items	Y	See section Shipment Item Elements

Shipment Item Elements

Element	Description	Mandatory?	Data Type	Max Length	Example
VendorBookingReference	A unique reference represents a vendor shipment booking created in the system and it must be supplied if created	N	nvarchar	250	VEN-1234
ItemCode	Product number/Item Code	Y	nvarchar	50	100013344
SKU	SKU (if available)	N	nvarchar	100	80018839298
Colour	Colour of item (if available)	N	nvarchar	50	Blue
Size	Size of item (if available)	N	nvarchar	50	Large
Cancelled	Cancelled flag	N	bool		false

Node Elements

Element	Description	Mandatory?	Data Type	Max Length	Example
Code	Code of the Node	Y	nvarchar	1000	MCRN
Name	Node name which is the UI display value in GRAVITY	Y	nvarchar	1000	MACARON
Description	Description of the Node	N	nvarchar	200	Food
Address	Address of Node	N	See section Node Address Elements

Node Address Elements

Element	Description	Mandatory?	Data Type	Max Length	Example
Line1	Line1	N	nvarchar	100	Rm 801-807, 8/F, Hoplite Industrial Building
Line2	Line2	N	nvarchar	100	3-5 Wang Tai Road, Shenzhen Bay
Line3	City	N	nvarchar	100	Shenzhen
Line4	State/Province	N	nvarchar	100	Guandong
PostCode	Postcode/Zip	N	nvarchar	50	31515412
Email	Email	N	nvarchar	250	Tim.R@mlogistics.com
Fax	Fax	N	nvarchar	20	+854423512
Telephone	Telephone	N	nvarchar	20	+8432173475
Longitude	Longitude	N	decimal	12	121.45806
Latitude	Latitude	N	decimal	12	31.22222
Contact	Contact Name	N	nvarchar	100	Tim R
CountryCode	Country Code	N	nvarchar	50	CN

XSD

<?xml version="1.0" encoding="utf-8"?>
<xs:schema elementFormDefault="qualified" xmlns:xs="http://www.w3.org/2001/XMLSchema">
	<xs:element name="CustomsClearances" type="ArrayOfCustomsClearance" />
	<xs:complexType name="ArrayOfCustomsClearance">
		<xs:sequence>
			<xs:element minOccurs="1" maxOccurs="unbounded" name="CustomsClearance" type="CustomsClearance" />
		</xs:sequence>
	</xs:complexType>
	<xs:complexType name="CustomsClearance">
		<xs:sequence>
			<xs:element minOccurs="1" maxOccurs="1" name="AgentNumber" type="xs:string" />
			<xs:element minOccurs="0" maxOccurs="0" name="BrokerNode" type="Node" />
			<xs:element minOccurs="0" maxOccurs="1" name="EntryNumber" type="xs:string" />
			<xs:element minOccurs="1" maxOccurs="1" name="EntryDate" type="xs:dateTime" />
			<xs:element minOccurs="1" maxOccurs="1" name="ClearanceDate" type="xs:dateTime" />
			<xs:element minOccurs="1" maxOccurs="1" name="EquipmentNumber" type="xs:string"/>
			<xs:element minOccurs="1" maxOccurs="1" name="HouseBill" type="xs:string"/>
			<xs:element minOccurs="0" maxOccurs="1" name="Seal" type="xs:string"/>
			<xs:element minOccurs="1" maxOccurs="1" name="ClearedBy" type="xs:string"/>
			<xs:element minOccurs="1" maxOccurs="1" name="ClearedAt" type="xs:dateTime"/>
			<xs:element minOccurs="1" maxOccurs="1" name="ShipmentBookings" type="ArrayOfShipmentBooking"/>
		</xs:sequence>
	</xs:complexType>
	<xs:complexType name="ArrayOfShipmentBooking">
		<xs:sequence>
			<xs:element minOccurs="1" maxOccurs="unbounded" name="ShipmentBooking" type="ShipmentBooking" />
		</xs:sequence>
	</xs:complexType>
	<xs:complexType name="ShipmentBooking">
		<xs:sequence>
			<xs:element minOccurs="1" maxOccurs="1" name="ThreePLBookingReference" type="xs:string" />
			<xs:element minOccurs="1" maxOccurs="1" name="ShipmentOrders" type="ArrayOfShipmentOrder" />
		</xs:sequence>
	</xs:complexType>
	<xs:complexType name="ArrayOfShipmentOrder">
		<xs:sequence>
			<xs:element minOccurs="1" maxOccurs="unbounded" name="ShipmentOrder" type="ShipmentOrder" />
		</xs:sequence>
	</xs:complexType>
	<xs:complexType name="ShipmentOrder">
		<xs:sequence>
			<xs:element minOccurs="1" maxOccurs="1" name="OrderNumber" type="xs:string" />
			<xs:element minOccurs="0" maxOccurs="1" name="Identifier" type="xs:string" />
			<xs:element minOccurs="1" maxOccurs="1" name="ShipmentItems" type="ArrayOfShipmentItem" />
		</xs:sequence>
	</xs:complexType>
	<xs:complexType name="ArrayOfShipmentItem">
		<xs:sequence>
			<xs:element minOccurs="1" maxOccurs="unbounded" name="ShipmentItem" type="ShipmentItem" />
		</xs:sequence>
	</xs:complexType>
	<xs:complexType name="ShipmentItem">
		<xs:sequence>
			<xs:element minOccurs="0" maxOccurs="1" name="VendorBookingReference" type="xs:string" />
            <xs:element minOccurs="1" maxOccurs="1" name="ItemCode" type="xs:string" />
            <xs:element minOccurs="0" maxOccurs="1" name="SKU" type="xs:string" />
            <xs:element minOccurs="0" maxOccurs="1" name="Colour" type="xs:string" />
            <xs:element minOccurs="0" maxOccurs="1" name="Size" type="xs:string" />
            <xs:element minOccurs="0" maxOccurs="1" name="Cancelled" type="xs:boolean" />
		</xs:sequence>
	</xs:complexType>
	 <xs:complexType name="Node">
    <xs:all>
      <xs:element minOccurs="1" maxOccurs="1" name="Code" type="xs:string" />
      <xs:element minOccurs="1" maxOccurs="1" name="Name" type="xs:string" />
      <xs:element minOccurs="0" maxOccurs="1" name="Description" type="xs:string" />
      <xs:element minOccurs="0" maxOccurs="1" name="Address" type="NodeAddress" />
    </xs:all>
  </xs:complexType>
  <xs:complexType name="NodeAddress">
    <xs:all>
      <xs:element minOccurs="0" maxOccurs="1" name="Line1" type="xs:string" />
      <xs:element minOccurs="0" maxOccurs="1" name="Line2" type="xs:string" />
      <xs:element minOccurs="0" maxOccurs="1" name="Line3" type="xs:string" />
      <xs:element minOccurs="0" maxOccurs="1" name="Line4" type="xs:string" />
      <xs:element minOccurs="0" maxOccurs="1" name="PostCode" type="xs:string" />
      <xs:element minOccurs="0" maxOccurs="1" name="Email" type="xs:string" />
      <xs:element minOccurs="0" maxOccurs="1" name="Fax" type="xs:string" />
      <xs:element minOccurs="0" maxOccurs="1" name="Telephone" type="xs:string" />
      <xs:element minOccurs="0" maxOccurs="1" name="Longitude" type="xs:decimal" />
      <xs:element minOccurs="0" maxOccurs="1" name="Latitude" type="xs:decimal" />
      <xs:element minOccurs="0" maxOccurs="1" name="Contact" type="xs:string" />
      <xs:element minOccurs="0" maxOccurs="1" name="CountryCode" type="xs:string" />
    </xs:all>
  </xs:complexType>
</xs:schema>

Sample Landside Customs Clearance Export XML File

<?xml version="1.0" encoding="utf-8"?>
<CustomsClearances xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <CustomsClearance>
      <AgentNumber>str1234</AgentNumber>
      <BrokerNode>
        <Code>CUSTOMER_B123456</Code>
        <Name>BROKER LTD</Name>
        <Address>
          <Line1>3 North Road</Line1>
          <Longitude>103.850882600</Longitude>
          <Latitude>1.292340700</Latitude>
          <CountryCode>SG</CountryCode>
        </Address>
      </BrokerNode>
	  <EntryNumber>str1234</EntryNumber>
	  <EntryDate>2012-12-13T12:12:12</EntryDate>
	  <ClearanceDate>2012-12-13T12:12:12</ClearanceDate>
	  <EquipmentNumber>str1234</EquipmentNumber>
	  <HouseBill>str1234</HouseBill>
	  <Seal>str1234</Seal>
	  <ClearedBy>chris.wong</ClearedBy>
	  <ClearedAt>2012-12-13T12:12:12</ClearedAt>
      <ShipmentBookings>
		<ShipmentBooking>
			<ThreePLBookingReference>REF-1234</ThreePLBookingReference>
			<ShipmentOrders>
				<ShipmentOrder>
					<OrderNumber>PO1234</OrderNumber>
					<Identifier>Drop1</Identifier>
					<ShipmentItems>
						<ShipmentItem>
							<VendorBookingReference>VEN-12345</VendorBookingReference>
							<ItemCode>6900018992</ItemCode>
							<SKU>900012911</SKU>
							<Colour>Blue</Colour>
							<Size>10</Size>
							<Cancelled>false</Cancelled>
						</ShipmentItem>
					</ShipmentItems>
				</ShipmentOrder>
			</ShipmentOrders>
		</ShipmentBooking>
	  </ShipmentBookings>
	</CustomsClearance>
</CustomsClearances>

Community