Port and Terminal Software Problems: The 7 That Cost Real Money, and How to Avoid Them

Why does a terminal software project turn into a TOS replacement?

The complaint that starts the project is specific. Trucks queue at the gate because exceptions are resolved by phone. The yard has no idea what the appointment system sold. Reefer billing is estimated. Somebody retypes documents all day.

Then the scope drifts toward the centre. If we are building the appointment engine anyway, should it not hold the yard. If it holds the yard, should it not plan the vessel. Within a few meetings a layer above the terminal operating system (TOS) has become a replacement for it, and you are now committed to a multi year project with a poor success rate in an operation that never closes.

Navis N4 and Tideworks are genuinely good at core inventory and move execution. That is a hard problem they have spent a long time solving, and rewriting it buys you nothing you do not already have.

The fix is to state the boundary in the statement of work rather than in a conversation. The TOS remains the system of record for inventory and moves. Everything you build reads from it and writes back through defined paths. In Digital Heroes delivery experience a focused first release, meaning one capability done properly such as the appointment and yard slot engine, or the document intake pipeline, or the cross terminal event warehouse, runs $60,000 to $130,000 in 12 to 16 weeks. Not all three. A full platform covering gate, yard, equipment, documents and billing with electronic data interchange (EDI) and customs feeds wired in runs $150,000 to $400,000 phased over 6 to 12 months. Most terminals that believe they need a custom TOS actually need someone to finish the configuration they abandoned three years ago, and being honest about which one you are is the cheapest decision in the project.

What goes wrong when you pull data out of the TOS and try to define a move?

The data problem in this category is definitional rather than technical, and it is the reason cross terminal reporting never ties.

Ask two terminals what counts as a move and you will get two answers. A repositioning within a block may or may not count. A rehandle to dig out a buried box may be counted as one move or as three. A gate transaction that is rejected and re-presented may appear twice. When Terminal A and Terminal B disagree and nobody wrote the definitions down, corporate reporting becomes a weekly argument in a spreadsheet and every number is defensible and none is trusted.

The same applies to the free time clock. When does it start, on discharge, on availability, on customs release, and what stops it. That definition determines demurrage revenue and is frequently held in a billing clerk's head rather than in any system.

Timestamps are the third trap. A move has several candidate times: when the instruction was issued, when the equipment operator confirmed, when the position was updated. Reports built on different ones disagree by minutes that compound into hours.

The fix is a working session before any code is written, with your yard planner, your billing clerk and your operations manager in the room, to write the definitions down and pick the authoritative timestamp for each event. Then a canonical event model that both terminals write into, with a terminal identifier and an agreed definition per event type. Migration of the rows is usually two to three weeks inside a larger build. Agreeing the definitions is what actually takes the time, and skipping it produces a warehouse full of numbers nobody will act on.

Why do the EDI, TOS and telematics integrations break after launch?

Terminal integrations fail on partner behaviour and on version drift, and both are outside your control.

EDI is the biggest surface. Every transaction set you support, the 322, the 315, the 300, the 301, the 304, is real work, and every trading partner has their own dialect of it. The failure that costs you a gate slot is the one described earlier: a booking amended overnight arrives as a 315 that fails validation, lands in an error queue nobody watches, and the drayman is waved to problem resolution at half past six in the morning. The error queue is the problem, not the validation. Failed inbound messages need to page a person with the container and booking attached, not accumulate.

TOS integration breaks on version and licensing. A modern N4 instance with licensed application programming interface and Extensible Markup Language services is straightforward and typically adds two to four weeks. An older Tideworks or legacy instance where you are reading the database directly or scraping reports adds six to ten weeks, because you are reverse engineering a schema and building your own change data capture, and any schema change during an upgrade breaks it silently. Get your TOS version and licensed module list in front of any developer before they quote.

Telematics from Kalmar Insight, Konecranes TRUCONNECT or an aftermarket gateway on older iron drifts on asset mapping. A machine is re-tagged after a repair and the link between the unit in your equipment store and the unit in the vendor feed breaks, so fault codes attach to the wrong machine. Reconcile the asset list on a schedule and alarm on unmatched units rather than ignoring them.

What happens when customs and hazmat obligations are not covered?

Two compliance surfaces in this category have real teeth and both reach into the data model rather than sitting on top of it.

Customs filing paths carry an obligation and an audit expectation. If a number entered your system from a scanned document, you need to be able to show how it got there, which means the source image and the extraction have to be retained and linked to the field, not just the final value. A system that stores the typed result and discards the provenance leaves you explaining a discrepancy from memory.

Hazmat is the sharper one. A wrong number on a dangerous goods declaration is a different class of defect from a wrong shipping address, and generic document tools have no idea what a valid entry looks like. Extraction alone is not enough. The declared identifier has to be validated against the reference table and against what the booking said, and a mismatch has to stop the transaction rather than warn about it. The same principle applies to container numbers, where check digit arithmetic under the ISO 6346 standard lets the system self correct or reject rather than accepting a plausible looking typo.

Verified gross mass declarations and access control for restricted areas are the other two that turn up in scope late and carry design constraints. None of these makes a build impossible, but each adds audit trail requirements, and together they are a meaningful part of why a full platform lands at the upper end of the band. Ask any developer to name a project where they shipped a customs or hazmat integration, not a category they are comfortable with.

Should you build custom or finish configuring the TOS you already own?

For a real share of terminals the right answer is do not build, and we say so regularly.

If you run a single facility below roughly 150,000 twenty foot equivalent units a year, with simple stack rules and a stable customer mix, Navis N4 or Tideworks configured properly will serve you. Spend the money finishing the configuration rather than rewriting it. The reefer module that nobody configured is a configuration project, not a software project, and the same is true of a surprising share of the workarounds in most terminals.

The honest test is whether your pain is a missing capability or an abandoned implementation. A shared spreadsheet where the yard planner tracks reefer plug assignments usually means the reefer module was never set up. A group chat where the gate supervisor and the yard boss reconcile mismatched container numbers usually means an EDI error queue nobody owns. Both of those are cheaper to fix inside what you have.

Where configuration genuinely runs out is at the joins. The appointment system and the yard do not know about each other, and no vendor owns that join. Equipment telemetry is not in the TOS data model. Cross terminal reporting across two different vendors is nobody's product. Billing evidence for events the TOS does not capture cannot be configured into existence.

So the position is consistent: do not replace the TOS. Build the layer above it and the layers around it, where off the shelf has nothing to sell you and where the money is actually leaking.

How do hidden costs get into the quote?

Six things drive a terminal software quote and the first two are usually the only ones discussed.

The number and stubbornness of your TOS integrations, where a modern licensed instance and a fifteen year old one where you read the database directly are different projects. EDI coverage depth, since every additional transaction set and every additional trading partner dialect is real work. Customs integration, which carries compliance burden. Gate camera and optical character recognition hardware if you do not already have it. Access control integration if it is in scope. And round the clock uptime requirements, which change your architecture and your on call cost from day one, because a terminal that never closes cannot take a maintenance window and designing for that is not free.

Then the ones that never appear on a proposal. The definitional working sessions described earlier, which are your people's time and are the actual migration risk. Parallel running at the gate, because you will run both paths for a period and that costs hours. Out of hours cutover, since there is no quiet time. And the ongoing cost of EDI partner onboarding, which continues forever as customers change.

Ask for exclusions in writing and ask specifically what the quote assumes about your TOS version and licensed modules.

What separates a build that works from one that fails here?

Make them draw your data model on a whiteboard before anything is signed. Container, booking, move, unit, equipment, visit, yard position. If they model a container as the primary entity rather than the unit visit or the move, they have not built this before and you will pay for their education, because a container is a physical object with a life across many visits while a unit visit is what your yard actually manages.

Ask them to explain a stow plan file and a container discharge message without looking them up. It is not trivia. A team that has never touched the EDIFACT or X12 sets will underestimate the integration work substantially, and integration is most of this project.

Ask what happens when the TOS goes down at two in the morning during a vessel operation. The answer you want involves queued writes, an offline gate mode and a defined reconciliation path when it comes back. The answer you do not want is a promise about uptime. Terminals do not stop.

The builds that work are honest about where automation ends. On documents, the win is validation rather than extraction: pull the fields, then check the container number against check digit arithmetic and against expected inventory, check the dangerous goods identifier against the reference table and the booking, check the declared mass against a plausible range for that box type. In our deployments roughly three quarters of documents pass every check and post straight through, and the rest route to a clerk with the failing field flagged and the source image cropped to it. That turns a documentation team from typists into exception handlers and gives you provenance on every field.

Settle ownership before kickoff. Source in your own repository from week one, and a named person on the developer's side who understands that a wrong dangerous goods identifier is a different class of bug from a wrong shipping address.