Turn port arrivals into HubSpot tasks for your ship supply desk

Every morning at 06:00, on a cron trigger, turn the ships heading for the ports we cover into real pipeline for our ship chandlery and port agency desk. Keep the port list, the serviceable vessel types and the mobilisation cut off as configurable inputs at the top of the workflow, so the desk can change them without editing logic. Ports are given as MarineTraffic port IDs or UN/LOCODEs.

For each port in the list, call MarineTraffic Expected Port Arrivals to get the vessels that have already declared us as their destination. Then call MarineTraffic Predictive Port Arrivals for the same port to catch vessels that are likely inbound but have not declared a destination yet. Merge the two lists per port, de-duplicate on the vessel identifier, keep the earliest credible ETA, and record whether each candidate came from the declared list or the predictive one. That distinction matters to the desk, so carry it all the way through to the task and the summary.

Enrich every remaining candidate with MarineTraffic Vessel Particulars to pull the vessel type, the size (deadweight or dimensions), and the registered owner or manager. Vessels are addressed by IMO or MMSI, so carry those identifiers through from the arrivals calls. Note that MarineTraffic issues a separate API key per service, so the arrivals calls and the particulars call may need two different keys.

Filter the enriched list twice. First, keep only the vessel types we service. Default that list to bulk carriers, tankers, container ships and general cargo vessels, and expose it as a configurable input. Second, drop any arrival whose ETA is less than 24 hours away, because we cannot mobilise supply in time. Make that 24 hour floor a configurable input as well. Everything else is dropped silently and does not need reporting.

This runs daily against the same ports, so the same vessel will reappear on consecutive runs while it is still inbound. Before raising anything, use HubSpot Search Tasks to look for an open task that already covers that vessel and that voyage, matching on the vessel name and the arrival date carried in the task subject. If one exists, skip the vessel and count it as already covered so it can be reported in the summary. Do not raise a second task for a voyage that is already on the board.

For each vessel that survives, take the registered owner or manager name and look it up in HubSpot with Search Companies. If there is a confident match, use that company and treat the vessel as an existing account. If there is genuinely no match, create the account with HubSpot Create Company using the owner or manager name plus whatever country or address detail the vessel particulars returned, and treat it as a new prospect. Do not create a company when the match is merely plausible; prefer the existing record and note the ambiguity in the task body instead.

In every case, raise a HubSpot task with Create Task, due the day before the vessel's ETA. Put the vessel name, the ETA and the last port in the subject, for example: MV Northern Star, ETA Rotterdam 14 Mar 08:00, last port Hamburg. Associate the task with the company record. In the task body, include the vessel type, size, owner or manager, the port, whether the arrival came from the declared or the predictive list, and any note about an ambiguous company match.

Finish with a single Slack message using Send a Message to the desk channel. Split the day's arrivals into two sections: existing accounts, where we already have a relationship and should be quoting, and new prospects, where the account was just created. For each vessel, show the vessel name, type, port, ETA and the owner or manager. Open with a one line header giving the totals for each section and how many vessels were skipped because a task already existed. Post one message for the whole run, never one message per vessel.