XML Notifications On-Boarding Guide

Owned by Jerusha Nyashanu (Unlicensed)
Last updated: 23 Jul, 2024 by Chris Boxall
8 min read
Contents

What are Notifications?

PortConnect can send email notifications when a range of events occur against containers.

 

What event types are available?

A full list of events is available here,

Container Visit Event Types | Event Types

 

What is B2B Registration Of Interest (ROI)?

Business to Business (B2B) Registration Of Interest (ROI) is a way to register interest in containers so that you can automatically receive Notifications about events that occur against containers. A ROI message can be generated by your system and sent to PortConnect in a XML format. PortConnect will then register your interest in the requested container(s) and begin sending Notifications. This is an alternative to manual Registration of Interest through the PortConnect website.

By registering interest in containers you are registering to receive notifications for all the default notification types you are signed up for. Read the What are Notifications section to learn more about Notification types.

What does a Notification email look like?

The below example shows a Notification email. There is an XML file attached with the same information so that you can process it automatically if you wish.

XML example:

How can the XML file be sent to PortConnect?

The XML files can be sent by FTPS or email. Please confirm which option you would like to use and we can provide you with further details. If you are sending the file by email the body of the email needs to be blank and the only attachment should be the XML file. Any other attachments may stop the XML file from being processed.

When can I send ROI?

ROI can only be registered against active containers.

Imports become Active once the port receives the container information from the last port that the vessel visited before making its way to the discharge port. Imports become Inactive once they are delivered from the seaport or inland port facility.

Exports become Active once the container has been Pre-Advised. Exports become Inactive once they load on their outbound vessel.

If an ROI is received but PortConnect cannot find an active version of the container then you will receive an Acknowledgment email identifying the ROI is in the queue (see the following section).

How long will the ROI be queued for?

  • ROI's may be queued because PortConnect does not yet have a record of the container or because the information you have submitted does not match the details of the container you are trying to register interest in.

  • If an ROI is queued, it will stay queued for 30 days. After the 30 days are up the ROI request will be removed.

  • If PortConnect receives a record of the container within the 30 days then the ROI will be applied but you will not receive a success message - you will simply start receiving notifications.

PortConnect does not receive Import and Arriving Tranship container information from the ports until after the vessel leaves the previous port. Therefore, some containers may not come through to PortConnect until half a day or a day before the vessel is due to arrive at the port.

How will I know if the ROI has succeeded?

You will receive an automated acknowledgement email to confirm that the ROI message has been received. 

There is an XML file attached which specifies whether the ROI was Successful or Queued.

If you receive an acknowledgement response message where there is no customer reference, no success or queued status then there is an error with your customer code in you ROI XML. Contact info@portconnect.co.nz to check you have the correct code for your company.

Note - We recommend that you set up an automated process to record whether an Acknowledgment message has been received or not. If you do not receive an Acknowledgment email then please contact info@portconnect.co.nz as soon as possible so that we can investigate for you.

Notification Defaults

Notifications are sent to the defaults that you set up on the PortConnect website. Contact info@portconnect.co.nz to get access to the Notifications functionality in PortConnect.

Click on the following link to learn how to set up Notification defaults.

How do I get started with XML ROI?

  1. Contact the PortConnect team to advise that you would like to develop B2B ROI and Notifications.

  2. Send the link of this page to your IT team and they can review it and confirm whether your system can produce a XML file as per the format listed below.

  3. Once your IT team has developed the XML message you can contact info@portconnect.co.nz and let us know that you are ready to start testing. Please send PortConnect at least two test messages.

  4. PortConnect will review the test messages to confirm that they are in the correct format. Your IT team may need to make some revisions to the message format.

  5. Once the testing is complete you will be able to start sending B2B ROI messages to PortConnect.

XML Format

Note: XML Elements are case sensitive and must display exactly as per below

Level

XML Element

Req’d

Repeats

Data Type

Description

0

AutoTrack xmlns:ns0="http://PortConnect/B2BIn/External/B2B_RoI/20132211"

Y

N

--

This is the message header and includes an attribute. This must match exactly what is in the below examples. Please note that the header of the Notification XML is different from the header of the ROI XML as these are two separate processes. The B2B ROI message must always have the ROI header as shown in the below examples.

1

Header

Y

N

--



2

Timestamp

Y

N

Datetime

e.g. 2014-05-31T13:20:00.000

2

SenderReference

Y

N

String

This is your own internal reference to help you identify the ROI request message. The sender reference will be included in the response acknowledgment email you receive from PortConnect but will not be included in Notification emails.

2

CustomerCode

Y

N

String

PortConnect will inform you on what this code is

2

CustomerPassword

N

N

String

Segment is not mandatory but you wish to include it then enter “unknown” - (function still in development)

2

RoIAcknowledgementEmail

Y

Y

String

Semi colon separated list of emails to send the ROI receival Acknowledgment email to

2

ContainerNotificationEmail

Y

N

String

This segment is mandatory but is no longer used. The value can be left blank or your can enter the email from the acknowledgment segment.

1

RegisterOfInterest

Y

N

--



2

Containers

Y

N

--



3

Container

Y

Y

--



4

PartnerPortCode

Y

N

String

NZAKL, NZTRG, NZTIU, NZLYT or DEPOT

4

ContainerNumber

Y

N

String

Container Number

4

CustomerReference

N

N

String

This is your own internal reference

4

ClientReference

N

N

String

This is your own internal reference

4

SupplyChainCode

Y

N

String

Enter E, I, T, D.

  • E= Export

  • I= Import

  • T=Transhipment

  • D=Domestic

  • S=Storage

Domestic is used for any container that has Load and Discharge ports that are both in NZ.

4

SpecialInstructions

N

N

String



4

Associates

N

N

--



5

Associate

N

N

--



5

AssociateCode

N

N

String

This field can be used to identify another Trading Party to also send the Notification to

5

ContainerNotificationEmail

N

N

String

Semi colon separated list of emails to send Notification emails to

Customer Reference within the ROI

  • Users can send multiple Customer References per container. This is an unlimited character field and designed to support container visit identifiers.

  • The Customer Reference will be included in the Notification (both in the email body and XML file attached).

  • To include this in the ROI, each Customer Reference needs to be set for each container segment.

  • If you submit a new ROI it will overwrite the existing ROI including the Customer Reference.

  • If you have already received Notifications against the first ROI you would receive them again against the new ROI with the new Customer Reference included in the Notification.

  • If you submit an ROI with the same Customer Reference as the previous ROI, it will not send new Notifications.

Partner Port and Supply Chain Codes

To receive Notifications for both the terminal and inland port, the PartnerPortCode needs to be specified:

Partner Port Code

Notifications sent for Sea port and Inland Port

Partner Port Code

Notifications sent for Sea port and Inland Port

NZTRG

NZTRG - Port of Tauranga (Sulphur Point)
NZMKL - MetroPort Auckland

NZAKL

NZAKL - Ports of Auckland 
NZWII - Wiri, Ports of Auckland South Auckland Freight Hub

NZTIU

NZTIU - Timaru Container Terminal
NZOLT - MetroPort Christchurch Rolleston

NZLYT

NZLYT - Lyttelton Port Company
NZCHC - CityDepot
NZOLT - MetroPort Christchurch Rolleston

The correct PartnerPortCode and SupplyChainCode must be sent in the ROI message.

E.g. Container ABCD1234567 is an Import at NZTRG.
An ROI is received with SupplyChainCode 'E' (Export) and PartnerPortCode ‘NZAKL’.
This will result in the ROI being queued but no notification will be sent unless an Export version of this container moves through NZAKL.

Once a ROI message is received, PortConnect attempts to identify the container based on the notified Supply Chain and Port codes.

If PortConnect cannot find a current active container of the notified supply chain type and Port then the ROI request will be stored for 30 days to wait for a version of the requested container that matches the supplied details.

If a container cannot be identified then the XML message will display an error and say the ROI is in the Queue waiting.

Example ROI messages

All Fields Example

<ns0:AutoTrack xmlns:ns0="http://PortConnect/B2BIn/External/B2B_RoI/20132211">

<ns0:Header>

<ns0:Timestamp>2016-07-18T13:45:00</ns0:Timestamp>

<ns0:SenderReference>Chris</ns0:SenderReference>

<ns0:CustomerCode>PortConnect Ltd</ns0:CustomerCode>

<ns0:CustomerPassword>unknown</ns0:CustomerPassword/>

<ns0:RoIAcknowledgementEmail>info@portconnect.co.nz</ns0:RoIAcknowledgementEmail>

<ns0:ContainerNotificationEmail>info@portconnect.co.nz</ns0:ContainerNotificationEmail>

</ns0:Header>

<ns0:RegisterOfInterest>

<ns0:Containers>

<ns0:Container>

<ns0:PartnerPortCode>NZAKL</ns0:PartnerPortCode>

<ns0:ContainerNumber>TTNU3158385</ns0:ContainerNumber>

<ns0:CustomerReference>ABCD123</ns0:CustomerReference>

<ns0:ClientReference/>

<ns0:SupplyChainCode>I</ns0:SupplyChainCode>

<ns0:specialInstructions/>

<ns0:Associates>

<ns0:Associate>

<ns0:Associate>MOND</ns0:Associate>

<ns0:ContainerNotificationEmail>info@portconnect.co.nz</ns0:ContainerNotificationEmail>

</ns0:Associate>

</ns0:Associates>

</ns0:Container>

</ns0:Containers>

</ns0:RegisterOfInterest>

</ns0:AutoTrack>



Short Example

<ns0:AutoTrack xmlns:ns0="http://PortConnect/B2BIn/External/B2B_RoI/20132211">

<ns0:Header>

<ns0:Timestamp>2016-07-18T13:45:00</ns0:Timestamp>

<ns0:SenderReference>Chris</ns0:SenderReference>

<ns0:CustomerCode>PortConnect Ltd</ns0:CustomerCode>

<ns0:RoIAcknowledgementEmail>info@portconnect.co.nz</ns0:RoIAcknowledgementEmail>

<ns0:ContainerNotificationEmail>info@portconnect.co.nz</ns0:ContainerNotificationEmail>

</ns0:Header>

<ns0:RegisterOfInterest>

<ns0:Containers>

<ns0:Container>

<ns0:PartnerPortCode>NZAKL</ns0:PartnerPortCode>

<ns0:ContainerNumber>TTNU3158385</ns0:ContainerNumber>

<ns0:SupplyChainCode>I</ns0:SupplyChainCode>

</ns0:Container>

</ns0:Containers>

</ns0:RegisterOfInterest>

</ns0:AutoTrack>



One Container Example

<ns0:AutoTrack xmlns:ns0="http://PortConnect/B2BIn/External/B2B_RoI/20132211">

<ns0:Header>

<ns0:Timestamp>2016-07-18T13:45:00</ns0:Timestamp>

<ns0:SenderReference>Chris</ns0:SenderReference>

<ns0:CustomerCode>PortConnect Ltd</ns0:CustomerCode>

<ns0:CustomerPassword/>

<ns0:RoIAcknowledgementEmail>info@portconnect.co.nz</ns0:RoIAcknowledgementEmail>

<ns0:ContainerNotificationEmail>info@portconnect.co.nz</ns0:ContainerNotificationEmail>

</ns0:Header>

<ns0:RegisterOfInterest>

<ns0:Containers>

<ns0:Container>

<ns0:PartnerPortCode>NZAKL</ns0:PartnerPortCode>

<ns0:ContainerNumber>TTNU3158385</ns0:ContainerNumber>

<ns0:CustomerReference>ABCD123</ns0:CustomerReference>

<ns0:ClientReference/>

<ns0:SupplyChainCode>I</ns0:SupplyChainCode>

</ns0:Container>

</ns0:Containers>

</ns0:RegisterOfInterest>

</ns0:AutoTrack>



Multiple Containers Example

<ns0:AutoTrack xmlns:ns0="http://PortConnect/B2BIn/External/B2B_RoI/20132211">

<ns0:Header>

<ns0:Timestamp>2016-07-18T13:45:00</ns0:Timestamp>

<ns0:SenderReference>Chris</ns0:SenderReference>

<ns0:CustomerCode>PortConnect Ltd</ns0:CustomerCode>

<ns0:CustomerPassword/>

<ns0:RoIAcknowledgementEmail>info@portconnect.co.nz</ns0:RoIAcknowledgementEmail>

<ns0:ContainerNotificationEmail>info@portconnect.co.nz</ns0:ContainerNotificationEmail>

</ns0:Header>

<ns0:RegisterOfInterest>

<ns0:Containers>

<ns0:Container>

<ns0:PartnerPortCode>NZAKL</ns0:PartnerPortCode>

<ns0:ContainerNumber>TTNU3158385</ns0:ContainerNumber>

<ns0:CustomerReference>ABCD123</ns0:CustomerReference>

<ns0:ClientReference/>

<ns0:SupplyChainCode>I</ns0:SupplyChainCode>

</ns0:Container>

<ns0:Container>

<ns0:PartnerPortCode>NZTRG</ns0:PartnerPortCode>

<ns0:ContainerNumber>MSKU5614589</ns0:ContainerNumber>

<ns0:CustomerReference>ExportDG</ns0:CustomerReference>

<ns0:ClientReference/>

<ns0:SupplyChainCode>E</ns0:SupplyChainCode>

</ns0:Container>

<ns0:Container>

<ns0:PartnerPortCode>NZTRG</ns0:PartnerPortCode>

<ns0:ContainerNumber>COSU5665812</ns0:ContainerNumber>

<ns0:CustomerReference>TT</ns0:CustomerReference>

<ns0:ClientReference/>

<ns0:SupplyChainCode>T</ns0:SupplyChainCode>

</ns0:Container>

<ns0:Container>

<ns0:PartnerPortCode>NZAKL</ns0:PartnerPortCode>

<ns0:ContainerNumber>OOLU1247411</ns0:ContainerNumber>

<ns0:CustomerReference>A3</ns0:CustomerReference>

<ns0:ClientReference/>

<ns0:SupplyChainCode>D</ns0:SupplyChainCode>

</ns0:Container>

</ns0:Containers>

</ns0:RegisterOfInterest>

</ns0:AutoTrack>



Related Articles



© PortConnect 2023