Portbase Notifications
Borderbolt can notify port terminals through Portbase that the customs documents for a shipment are ready. There are two kinds of message:
- MID (import notification): tells the receiving terminal that the import documents are ready, so the cargo can be released for pickup.
- MED (export notification): tells the outgoing terminal that the export documents are ready for loading.
You choose per declaration or transit whether it goes to Portbase. Borderbolt then creates the message automatically at the right moment, and either sends it straight away or keeps it as a draft for you to check and submit, depending on your settings. You can also create messages yourself from the Portbase overview, based on a declaration, a transit or entirely by hand.
Portbase must be switched on and fully set up by an administrator first, in Settings → Portbase (host, username and a generated SSH key). Until then, the Portbase block does not appear on declarations and transits. See Portbase Settings. Saved settings take effect immediately.
Turning On Portbase for a Declaration or Transit
On a Declaration
Open the declaration and go to the Container section. Below Shipment contains container you’ll find the Portbase logo and Submit to Portbase with Yes / No. It is No by default, and nothing is sent to Portbase for that declaration until you set it to Yes.
With Submit to Portbase set to Yes:
- Import declarations show a Terminal picker. Choose the terminal that handles the shipment. In the test environment, only the Portbase test terminal is offered.
- Export declarations show a note that an export notification (MED) is prepared for Portbase when the declaration is released, and that you add the booking numbers and submit it on the Portbase page. If export notifications are switched off in Settings → Portbase, you see a warning instead that nothing will be sent.
Your choices are saved as soon as you change them.
On a Transit Departure
Open the departure and go to the Container & Seals section. There you’ll find Submit to Portbase (Yes / No) and, when it’s set to Yes:
- Terminal: the terminal that handles the shipment, used for the import notification (MID).
- MED Document Type: how the goods reach the outgoing terminal. This is required for the export notification (MED) of a transit. As long as it’s empty, a warning is shown and no MED is sent.
| MED document type | Meaning |
|---|---|
| RT1 | T1, direct to loading port terminal |
| RT2 | T2, direct to loading port terminal |
| TT1 | T1, in transit via the port |
| TT2 | T2, in transit via the port |
| TEX | Continuation of Union goods, not yet at outgoing terminal |
| TZ1 | Continuation of transit goods, not yet at outgoing terminal |
The Portbase block does not appear on arrival transits.
Copying a declaration or transit does not copy its Portbase choices. The copy starts with Submit to Portbase set to No and no terminal selected.
When Messages Are Sent Automatically
For a declaration or transit with Submit to Portbase set to Yes, Borderbolt creates the message at these moments, provided the matching service (MID or MED) is switched on in Settings → Portbase:
| Declaration or transit | Message | Created when |
|---|---|---|
| Import declaration | MID | The declaration is released |
| Import pre-declaration (declaration lodged before the goods arrive) | MID | Customs accepts the declaration |
| Export declaration | MED | The declaration is released |
| Transit departure | MID, and MED when a MED document type is chosen | The transit is released |
Whether the message is also sent straight away depends on the setting Submit automatically when valid in Settings → Portbase (see Portbase Settings):
- Off (the default): every automatic message is created as a Draft, with all values from the declaration or transit already filled in, including the terminal. Nothing goes to Portbase until someone opens the message, checks it and clicks Submit.
- On: a message that passes every check is sent straight away, as described below.
With Submit automatically when valid switched on, Borderbolt first checks the values the message would be sent with, using the same checks as when you submit a message yourself (see Checks Before Submitting): the MRN, the container or trailer numbers, for a MID the submitter’s EORI number, and for a MED the gross weights and booking numbers. What happens next depends on the result:
- Terminal chosen, containers known and all values valid: the MID is sent straight away.
- No terminal chosen (or the chosen terminal is no longer available): the MID gets the status Awaiting Terminal Selection and waits until someone picks a terminal on the message page. See Choosing a Terminal Afterwards.
- No containers on the declaration or transit: the message is not sent. Borderbolt creates it as a Draft instead. A MID gets terminal type Ferry, so you can add the transport means identification; a MED needs at least one container or trailer number, because Portbase refuses an export notification without one.
- A missing or invalid value (for example an MRN with a wrong check digit, a container number that isn’t valid, or a declarant EORI number in the wrong format): the message is not sent. Borderbolt creates it as a Draft with the values from the declaration or transit already filled in, so you can correct them and submit it yourself on the message page. Spaces around a value and lowercase letters don’t count as invalid: Borderbolt removes the spaces and sends MRNs, container numbers and EORI numbers in capitals automatically.
- MED: always created as a Draft, also when automatic submission is on. Portbase needs a booking number for every container or trailer, and Borderbolt doesn’t store booking numbers on declarations or transits. The MRN, containers and gross weights are filled in; enter the booking numbers on the message page and click Submit. No terminal is needed for a MED.
Drafts that Borderbolt creates this way show System as the user in the Timeline. Look for them in the Portbase overview with the status Draft.
Gross Weights of a MED
A MED carries two kinds of gross weight, both in kilograms, and Borderbolt fills them in from the declaration or transit:
- Shipment gross weight: the total of the shipment. For a declaration this is the sum of the gross weights of all its lines, the same total that goes to customs; for a transit, its total gross mass.
- Gross weight per container or trailer: with one container, this is the shipment gross weight. With several containers, each container gets the sum of the gross weights of the declaration lines linked to that container.
When a declaration line with a weight is not linked to any container, or is linked to more than one, Borderbolt can’t tell how the weight is divided. The weights per container are then left empty for you to enter; Borderbolt never divides or estimates a weight.
An automatic MID is sent on behalf of the declarant of the declaration or transit when that declarant has an EORI number, and otherwise on behalf of your organization (the Sender EORI from Settings → Portbase).
Borderbolt does not create a second automatic message for the same declaration or transit while an earlier one exists. A draft you created yourself does not block a new one, but a draft Borderbolt created automatically does. A rejected or failed message blocks one too: correct it and submit it again on its message page (see Correcting and Resubmitting a Message), so the terminal isn’t notified twice.
The Portbase Overview
Open Portbase in the sidebar to see all Portbase messages for your organization, both the ones you send and the responses that come back from Portbase. The sidebar item appears once Portbase is switched on and fully set up in Settings → Portbase (host, username and a generated SSH key).
The table works like the declarations overview:
- The ID column comes first and links to the message page.
- Use the column headers to filter and sort, for example on Message Type, Direction, Status or Created.
- Reference links to the declaration or transit the message belongs to.
- Switch between Last 90 days and All time, and use Clear Filters to reset all filters.
- Failed messages have a Retry button in the actions column. All other rows have View.
- The table refreshes itself every 30 seconds while the page is open, keeping your filters, sorting and scroll position, so new messages and status changes appear without reloading.
Creating a Message Yourself
Click New message and choose:
| Option | What it creates |
|---|---|
| From declaration | Search for an import or export declaration by reference, LRN or MRN. An import declaration gives a MID, an export declaration a MED. |
| From transit | First choose MID (import notification) or MED (export notification), then search for the transit by reference, LRN or MRN. |
| Manual MID (import notification) | An empty MID that you fill in completely yourself. |
| Manual MED (export notification) | An empty MED that you fill in completely yourself. |
Every new message starts as a Draft and opens straight on its message page. Nothing is sent until you click Submit.
A draft created from a declaration or transit is pre-filled with its MRN, containers, terminal and document type, and for a MED with the gross weights (see Gross Weights of a MED). Booking numbers are never pre-filled. You can change any of these values. When you submit, the values on screen are what’s sent.
The Message Page
Header
The header shows the message type (for example MID (import notification)), its status, the message ID and when it was created. Depending on the status, these buttons are available:
- Save, Submit and Delete draft: for drafts. Unsaved changes are saved automatically when you click Submit. Only drafts can be deleted; messages that have been sent are kept as a record.
- Save and Submit again: for Rejected and Failed messages, after you’ve corrected the details. See Correcting and Resubmitting a Message.
- Terminal picker and Submit: for messages with the status Awaiting Terminal Selection.
- Retry: for failed messages. Sends the same message again, unchanged.
- Timeline: always available. See Timeline.
Below the header, a strip shows the Source (a link to the declaration or transit, or “Manual”), the Terminal (MID only), and when the message was Submitted and Acknowledged.
While a message waits for an answer from Portbase (Pending, Sent, Awaiting Acknowledgement or Acknowledged), the page checks for updates every 30 seconds. When Portbase accepts or rejects the message, the new status appears by itself; you don’t need to reload the page.
Fields
Fields can be edited while the message is a draft, and again when Portbase has rejected it or it could not be sent (Rejected or Failed). In every other status they’re shown read-only, with the values that were actually sent.
For a MID, Terminal type is shown at the top of the right-hand column, directly above the containers or the transport means identification it switches between.
MID (import notification)
| Field | Description |
|---|---|
| MRN / document number | The MRN or number of the customs document. |
| Document type | The type of customs document; see the table below. A draft from an import declaration starts with IM4, a draft from a transit with MRN (or NT1 when the transit has no MRN). |
| Terminal | The terminal that handles the shipment. In the test environment, only the Portbase test terminal is offered. |
| Terminal type | Container or Ferry. |
| Containers | For terminal type Container: the container numbers, at least one. Use Add container to add a row. Each number is checked; see Checks Before Submitting. |
| Transport means identification | For terminal type Ferry, instead of containers. Max. 17 characters. |
| Submitter | Who the message is sent on behalf of: Your organization, a declarant, or a customer with an EORI number. Search by name or EORI. For a draft linked to a declaration or transit, the declarant of that declaration or transit is pre-selected when it has an EORI number. |
| EORI number | The submitter’s EORI number, filled in when you choose a submitter. You can also enter an EAN code here. |
MID document types
| Code | Meaning |
|---|---|
| IM4 | Import declaration |
| MRN | Transit (MRN) |
| NT1 | Transit without MRN |
| ICT | Intra-Community transaction |
| FWV | Release for removal (fiat wegvoering) |
| IM7 | Storage longer than 45 days at the terminal |
| PIE | IMA arrangement 71.00 for transport |
| NAR | Military shipments |
| ENL | ETT transport |
| RNL | ETT transport |
| BXI | Bonded transit (T1) via the Dutch port |
| IAI | Entry in the declarant’s records: import |
| IAE | Entry in the declarant’s records: customs warehousing |
| REN | Re-export notification, export via the same cargo handling agent |
| ZWX | Re-export notification, export via a different cargo handling agent |
MED (export notification)
| Field | Description |
|---|---|
| MRN / document number | The MRN of the export declaration or transit. |
| Document type | Which types you can choose depends on where the message comes from (see below). |
| Shipment gross weight (kg) | The gross weight of the whole shipment. Pre-filled from the declaration or transit; see Gross Weights of a MED. |
| Container / trailer number | The containers or trailers of the shipment, at least one. Enter a container number (for example CSQU3054383) or, for ferry cargo, a trailer number. Use Add container to add a row. See Checks Before Submitting. |
| Booking number | Per container or trailer: its booking number, as agreed with the shipping line or carrier. Required, up to 35 characters. Never pre-filled, and never taken from the MRN. |
| Gross weight (kg) | Per container or trailer: the gross weight of the goods in it. Pre-filled where Borderbolt can work it out; see Gross Weights of a MED. |
| Message created from | Document types available |
|---|---|
| A declaration | EX (Export declaration) and CO (Export declaration (CO)) |
| A transit | RT1, RT2, TT1, TT2, TEX, TZ1 (see On a Transit Departure) |
| Manual MED | All eight of the above |
Timeline
Click Timeline to see the full history of the message: every status change with the date, time and the user who caused it. Automatic actions, such as sending the message and processing Portbase’s replies, show System as the user, also when you submitted the message yourself. Where Portbase sent a response, the timeline also shows its status code and, for a rejection, the rejection code and reason. When Portbase reports more than one error, all of them are listed. For a failed message, the error is shown with the last failure.
Some replies from Portbase don’t change the status of the message. They appear in the timeline as Reply from Portbase:
- Portbase received the file: Portbase’s confirmation that the file arrived. The final answer (accepted or rejected) follows separately.
- Accepted for processing or processing notices from the terminal for a MID.
- Customs status updates for a MED, for example “Release notification received from customs”. These never change an accepted or rejected message; the latest customs status code is shown with the message.
A message that is corrected and submitted again keeps its history. For example: Sent → Rejected (with the rejection code and reason) → Pending (“Submitted again after: Rejected”) → Sent → Accepted.
Checks Before Submitting
Borderbolt checks the fields while you work on a message:
- A field is checked as soon as you leave it. If it has an error, the message appears below the field, and it disappears as soon as you’ve corrected the value; you don’t need to leave the field again.
- Submit and Submit again stay greyed out as long as something is missing or incorrect. Next to them, a line such as “2 fields need fixing before you can submit” tells you how many. Click that line to show the errors on all fields at once, including fields you haven’t visited yet.
- Save is always available: a draft may be incomplete.
- Borderbolt never changes what you type. A value in the wrong format, for example a weight with a comma, gets an error message; you correct it yourself.
When you click Submit or Submit again, the same checks run once more before anything is sent. Errors appear next to the field they relate to; for containers, next to the container concerned. Most format checks also run when you click Save.
Required fields:
- MID: terminal, MRN / document number, document type, terminal type, at least one container (Container) or the transport means identification (Ferry), and the submitter’s EORI number.
- MED: MRN / document number, document type, shipment gross weight, and at least one container or trailer number, each with a booking number and a gross weight. You can save a MED without these, but you can’t submit it.
A draft linked to a declaration or transit that doesn’t have an MRN yet can’t be sent. Wait until customs has assigned an MRN, or enter the number yourself.
Borderbolt also checks the format of:
| Field | Format | Checked for |
|---|---|---|
| MRN / document number | 18 characters: the year (2 digits), a 2-letter country code, 12 letters or digits, a procedure letter and a check digit, for example 24NL123456789012R0. The check digit must be correct. | MID document types IM4 and MRN, and every MED. Other MID document types, such as FWV and NT1, have their own numbers and only a maximum length of 35 characters. |
| Container numbers | The international container number format: a 3-letter owner code, the letter U, J or Z, 6 digits and a check digit, for example CSQU3054383. The check digit must be correct, and the same container number can’t appear twice. | MID with terminal type Container. |
| Container / trailer numbers | 1 to 17 letters and digits, without spaces or dashes, for example a trailer number such as AB12CD. A number shaped like a container number (3 letters, U, J or Z and 7 digits) must also have a correct check digit, as above. The same number can’t appear twice. | MED. |
| Submitter EORI number | An EORI number (a 2-letter country code followed by up to 15 letters or digits), or a 13-digit EAN code with a valid check digit. | Every MID. |
| Shipment gross weight (kg) | A number above 0, with a point (not a comma) for decimals, at most 3 decimals and 7 digits in total, for example 12500 or 1250.5. | Every MED. |
| Gross weight (kg) per container or trailer | As above, with at most 8 digits in total. | Every MED. |
| Booking number | Any text of up to 35 characters. | Every MED. |
Portbase itself can still reject a message after these checks. A common example is rejection code D02: the submitter is not authorised for that terminal. If you use a declarant as submitter, check that this declarant is registered with Portbase as a sender.
Statuses
| Status | What it means |
|---|---|
| Draft | Not sent yet. Can be edited, submitted or deleted. |
| Awaiting Terminal Selection | A MID that is ready except for the terminal. Pick a terminal on the message page to send it. |
| Pending | Queued to be sent to Portbase. |
| Sent | Delivered to Portbase, waiting for a response. |
| Awaiting Acknowledgement | Portbase has received the message and is processing it. |
| Acknowledged | Portbase has confirmed receipt. |
| Accepted | Processed successfully. The terminal has the documents. No further action needed. |
| Rejected | Portbase declined the message, usually because of missing or incorrect information. The rejection code and reason are shown on the message page and in the Timeline. Correct the details and submit it again. |
| Failed | A technical problem prevented the message from being delivered, or Portbase received the file but could not process it. It can be retried unchanged, or corrected and submitted again. |
Choosing a Terminal Afterwards
When a MID has the status Awaiting Terminal Selection:
- Open the message from the Portbase overview.
- Choose the terminal handling the shipment in the header.
- Click Submit.
The message is sent and its status updates from there. If the selection can’t be accepted (for example because the terminal was deactivated in the meantime), an error is shown and you can pick another terminal.
Correcting and Resubmitting a Message
A message that Portbase rejected, or that could not be sent, doesn’t need to be created again. You correct it on its own message page:
- Open the message from the Portbase overview.
- Read the notice above the fields. For a Rejected message it shows Portbase’s rejection code and reason, for example “Portbase rejected this message (D02: …). Correct the details and submit again.” For a Failed message it shows why the message could not be sent.
- Correct the fields: for a MID the MRN / document number, document type, terminal, terminal type, containers or transport means identification, and submitter with EORI number; for a MED the MRN / document number, document type, shipment gross weight, and container or trailer numbers with their booking numbers and gross weights.
- Click Save to keep your changes, or go straight to Submit again (unsaved changes are saved first).
Submit again runs the same checks as submitting a draft. If everything is correct, Borderbolt sends a completely new notification to Portbase with the corrected details. It stays the same message in Borderbolt: its status goes back to Pending, the rejection disappears from the message page, and the Timeline keeps the full history including the rejection.
Rejected and failed messages can’t be deleted; like every message that has been sent, they’re kept as a record.
Retrying a Failed Message
For a Failed message you can also click Retry. This sends exactly the same message again, without changes. Use it when the failure was temporary, for example a connection problem. A message can be retried at most three times; after that, submit it again with Submit again, or contact your administrator if it keeps failing.
Retry isn’t available for a Rejected message, because Portbase would reject the same content again. Correct it and use Submit again instead.
Billing
Depending on your organization’s rate card, a Portbase message can appear as a separate line on your invoices. Ask your billing administrator whether this applies to your account.
A message is charged when Portbase accepts it, not when it is sent:
- A message that Portbase rejects, or that could not be sent, is not charged.
- A message that is corrected and submitted again, or retried, is charged once, when Portbase accepts it.
- Each message is charged at most once. An invoice line that is already on an invoice is never changed afterwards.
- Only messages linked to a declaration or transit that belongs to a dossier are charged. A manual message without a declaration or transit is not.
For administrators: set this up with a billable item of trigger type Per Portbase Message and trigger event On Portbase Message Accepted. Under Message types, tick MID (import notification), MED (export notification) or both; leave both unticked to charge every Portbase message. See Invoicing.
Troubleshooting
No Portbase Block on a Declaration or Transit
- Check that Portbase is switched on in Settings → Portbase, that the host and username are filled in, and that an SSH key has been generated.
- On a declaration, look in the Container section. On a transit, look in Container & Seals.
- The block doesn’t appear on arrival transits.
No Message Created After Release
- Check that Submit to Portbase is set to Yes on the declaration or transit.
- Check that the matching service (Import Documentation (MID) or Export Documentation (MED)) is switched on in Settings → Portbase.
- For an import pre-declaration, the MID is created on acceptance, not on release.
- For a transit MED, check that a MED Document Type is chosen.
- Look in the Portbase overview for a message with the status Draft. When Submit automatically when valid is off in Settings → Portbase, every automatic message waits there as a draft for someone to submit it. A MED always does, because its booking numbers have to be entered. A message for a shipment without containers, or with a missing or invalid value, is also created as a draft: complete or correct it and submit it.
Message Rejected
- The rejection code and reason are shown above the fields on the message page and in the Timeline.
- For D02 (submitter not authorised for the terminal), check that the submitter is registered with Portbase as a sender for that terminal, or choose a different submitter.
- Correct the values on the message page and click Submit again. See Correcting and Resubmitting a Message.
Message Stuck in “Sent” or “Awaiting Acknowledgement”
- Processing usually takes a few minutes. Borderbolt collects Portbase’s answers every few minutes, and the message page updates itself when the status changes, so there’s no need to refresh it.
- Contact your administrator if the status doesn’t change after a while.
Submit Button Is Greyed Out
- Something is still missing or incorrect. Click the line next to the button (”… fields need fixing before you can submit”) to show all errors, then correct the fields marked in red.
- For a MED, check that every container or trailer has a booking number and a gross weight, and that the shipment gross weight is filled in. Use a point for decimals, not a comma.
Portbase Missing from the Sidebar
- Check that Portbase is switched on in Settings → Portbase, that the host and username are filled in, and that an SSH key has been generated. The sidebar item only appears when Portbase is fully set up.
- You need permission to view declarations.
- Opening a Portbase page through a link or bookmark before Portbase is set up takes you to Settings → Portbase if you may change the settings, or to the dashboard otherwise, with a notice.
Related Documentation
- Portbase Settings: connection details and services
- Declarations: creating and managing declarations
- Transit Declarations: creating and managing transit movements