Normalising a stage

One column, three vocabularies#

contacts.stage has carried three sets of words over this product's life and holds all three today. Anything reading that column has to accept all of them, which is why the translation lives in one place instead of at each call site.

Words are compared after being lowered, trimmed and having spaces turned into underscores, so *Not Interested* and not_interested are one word. The empty value, new, lead and contacted all read as the first position — a person grown from an old contact row would otherwise appear to leap out of nowhere at their first real transition.

Strict on write, total on read#

Writing

advance refuses a destination outside the six with unknown_stage and a 422. The vocabulary cannot grow by accident.

Reading

normalise and contact_rank never raise. An unrecognised word comes back as itself and ranks -1, which reads as *before everything*.

Terminal words

closed, lost, not_fit, not_interested, dnc, wrong_person and duplicate carry no position at all. Somebody who was closed and then writes again is starting over.

Mapping direction

Translation is non-decreasing along the engine's progression, so a contact the engine advances never makes the relationship go backwards.

That asymmetry is the design. A closed vocabulary on the way in keeps the meaning of a position stable; a total function on the way out means no reader can be broken by a word written years ago by code that no longer exists.

The failure this replaced#

Before the translation had one home, agent read the column by calling list.index on the engine's nine words. Every other word raised — including new, which is what every contact bridged in from a customer workspace carries, and client, which advance itself writes.

1. A message arrives for a contact whose stage word is new.

   Result The lookup raises rather than returning a position.

2. The engine retries.

   Result It raises again, for the same reason, because nothing about the data has changed.

3. Three attempts pass.

   Result The message is held — and never answered. Nothing on any screen said *this stage word is unreadable*; it read as a message that had simply not been dealt with.

What this means for imports and integrations#

• An import may carry any word. It is read charitably and ranks last, so it never blocks a later move. It is not adopted into the vocabulary.
• Setting a position through the API or the Assistant uses the six. Anything else is refused with unknown_stage rather than stored.
• Casing and spacing do not matter. Comparison is on the normalised word.
• Two screens can show different words for the same relationship while old rows survive — the lifecycle position is the one written by advance, and it is what other behaviour reads.

Questions#

Related#

• Lifecycle stages
• People
• Relationships in Connect
• Moving a relationship through its lifecycle
• Prospecting in Connect
• When a call is answered in silence