Question about parcel progress animation; out for delivery

[BerserkeR-Git]

Good day @jonisnet,

Just a quick message as a heads up cause I do not have a lot of time at the moment.

I noticed a couple times now with the postNL integration the status is on Bezorger is onderweg or an English equivalent basically the package is out for delivery but the animation at the top of the card doesn't go further than Sorting centre.
I haven't had the time to test what causes it.

[jonisnet]

Thanks for the report, and the screenshot really helped — found it.

Root cause: ha-postnl v4.x reports its status as an UPPERCASE enum (OUT_FOR_DELIVERY, DELIVERED, ...), while DHL/DPD use lowercase. The 4-step tracker matches the status against a fixed list case-sensitively, so OUT_FOR_DELIVERY never matched and the tracker just stayed on the last step that did match (Sorting centre) instead of advancing — exactly what you saw. There was actually already a partial workaround for this in the code, but only for the DELIVERED status specifically, never generalized to the others.

Fixed on main just now: status values are normalized to lowercase once, consistently, so every step (including "out for delivery") is recognized regardless of casing.

Cutting a v1.7.7 release with this fix shortly — will follow up here once it's out. Thanks again for flagging it!

[BerserkeR-Git]

Thanks for digging into that so fast, much appreciated.

I went looking before v1.7.7 lands because something did not quite add up on my side. I cannot find an uppercase status anywhere in ha-postnl. ParcelStatus is a StrEnum with lowercase values (OUT_FOR_DELIVERY = "out_for_delivery"), and that is true in 4.6.2 which I am running, in 4.7.0 on main, and in the commit that first introduced the enum back in June. So I do not think casing was the cause here, which would also mean my parcel still stalls on v1.7.7.

I think it is actually upstream in ha-postnl, in parcels.py. The status is decided purely by substring-matching PostNL's Dutch statusPhase.message against an ordered list, first match wins:

("onderweg naar het bezorgadres", ParcelStatus.OUT_FOR_DELIVERY),
("onderweg naar de bezorger",     ParcelStatus.OUT_FOR_DELIVERY),
...
("onderweg",                      ParcelStatus.IN_TRANSIT),

My message was Bezorger is onderweg. That is a different word order from onderweg naar de bezorger, so it misses both specific patterns, falls through to the generic onderweg, and comes out as in_transit. Which is the sorting centre step, so your tracker was showing exactly what the integration handed it.

The file even knows the phrase already: the observation code map has "J05": ParcelStatus.OUT_FOR_DELIVERY, # bezorger is onderweg. That map only feeds the history milestones though, not the parcel's current status.

The lowercase normalisation is still worth keeping as a safety net, no argument there. The actual fix looks like it belongs in ha-postnl rather than in the card, one extra pattern ahead of the generic one.

Happy to test v1.7.7 once it is out either way.

[jonisnet]

@BerserkeR-Git — you're right, and I should have checked more carefully before claiming victory. I traced it through ha-postnl's actual source: ParcelStatus is confirmed lowercase (StrEnum) in every version, so casing was never the issue. Your read of parcels.py is exactly what's there — the ordered pattern list has "onderweg naar het bezorgadres" and "onderweg naar de bezorger" as the specific OUT_FOR_DELIVERY matches, "Bezorger is onderweg" matches neither (different word order), and falls through to the generic "onderweg" → IN_TRANSIT. Nice catch.

The lowercase normalisation stays in as a harmless safety net, but it doesn't touch your actual bug — that's upstream.

@peternijssen — checked this across the whole org before flagging it to you: ha-postnl is the only one of the 24 carrier integrations that derives status from free-text pattern-matching. Every other one reads a structured numeric/enum code, which can't have this failure mode at all. And ha-postnl already has what it needs to fix this properly: the observationCode-based map ("J05": OUT_FOR_DELIVERY, comment literally says "bezorger is onderweg") — it's just currently only wired to the history timeline, not the live status. Five separate "unrecognised status" issues on this repo (#6, #9, #11, #12, #16) all look like the same underlying pattern: free-text wording drifts, a new substring pattern gets patched in reactively. Using the observation code for the live status too (not just history) looks like it'd close this whole class of bug rather than the next wording variant needing its own patch.

Happy to dig into this further and put together a PR if that'd be useful — just say the word.

[peter-mdf]

Fixed and released: ha-postnl 4.7.2 — status now derives from the observationCode vocabulary first (same one the history timeline already used), falling back to text matching only when there's no observation data.

I don't currently have an active parcel to verify this against a live "out for delivery" tracking session myself, so if either of you hits that case again on 4.7.2, a confirmation would be very welcome.

[peter-mdf]

Thanks for the ping. The current "live status" doesn't have the observationCode. Only the history has those. What I could is rather than using the "live status" as the current status, that I use the last status in history as the live status, as that one contains the observationCode

[jonisnet]

That direction is exactly right, but one implementation detail worth flagging before you build it: build_history() (and therefore anything with an observationCode) currently only runs when the Parcel history option is enabled — coordinator.py:427,539, gated behind self._include_history, which defaults to off. If "live status" starts depending on the last entry of that (opt-in) history list, status derivation would break for everyone who has never turned that option on, likely most installs.

The underlying colli/observations data is already being fetched regardless of that setting though (_extract_observations(colli) just reads off the object you already have), so the fix would be to always compute the observation-code-derived status internally — independent of whether the option to expose the full timeline attribute is on. That option can keep gating the public history attribute, just not the status computation itself.

Worth reusing while you're in there: build_history()'s carry-forward logic for _OBSERVATION_META_CODES (an admin/notification code like "ETA gewijzigd" inherits the last real milestone instead of resetting to null) — the same logic is exactly what you'd want for picking the live status too, so a stray meta code never becomes the answer.