Number states
Numbers travel through a variety of states within Kazoo during their lifecycle.
Let's enumerate those states and then see how they fit together!
Number States#
discovery
#
An internal state used to temporarily hold numbers that are available for users to acquire from the system.
- Populated by API requests to activate numbers for an account that don't yet exist in the system
- Numbers in
discovery
do not participate in number hunting - No number can transition from another state to
discovery
- There are no public fields for
discovery
numbers - Numbers in
discovery
are automatically purged from the database after a configurable timesystem_config/tasks.discovery_expiry_d
: How many days a number in thediscovery
state will remain before being deleted from the database.
port_in
#
When an account initiates a port request via the APIs, the number is created in the port_in
state.
- Numbers in
port_in
will automatically transition toin_service
the first time a call is received from a carrier to that number (the number hunt process) - Only used for internal number hunting within an account; calls to the number from another account will be routed upstream
- No number can transition from another state to
port_in
- Any account can create a
port_in
number if the number does not yet exist in the system - The public fields can be managed by the assigned account or its ancestors.
port_in
numbers can only transition toin_service
(on first call) ordeleted
(if the port is canceled).
available
#
A number that is routing to the cluster but not yet assigned to an account.
- Any account can transition
available
numbers toreserved
orin_service
if the account is in good standing available
numbers participate in number hunts- Non-local numbers can be released into the
available
state but they have to go through anaging
period first - Admin accounts are allowed to create
available
numbers if theirpvt_wnm_allow_additions
flag is set to true
reserved
#
A number assigned to an account but not yet in use (be it a by a callflow, trunkstore, etc).
reserved
numbers do not participate in number hunts- If the number is coming from the
discovery
state, the carrier module associated (knm_local
,knm_bandwidth
, etc) will attempt to acquire the number. reserved
numbers can be putin_service
when:- The requesting account is the same as the number's assigned account
- The requesting account is an ancestor of the number's assigned account
- The requesting account is a descendent of the number's assigned account
- Accounts can reserve a number when:
- The requesting account is an ancestor of the number's assigned account
- The requesting account is a descendent of the number's assigned account
- When a number is
reserved
, the new assignment is added to the number's history of assignments available
numbers can be transitioned into thereserved
state- E911 and other features follow the number into
reserved
but cannot be edited until the number isin_service
- Public fields on the number can be managed by the assigned account or its ancestors
in_service
#
A number assigned to an account and in use by an application such as callflows, trunkstore, etc.
in_service
numbers participate in number hunts- Can transition to
reserved
by the assigned account or an ancestor - E911 and other features follow the number into
in_service
- Public fields on the number can be managed by the assigned account or its ancestors
released
#
A temporary state between reserved
and in_service
before placing the number back into the available
pool.
Deactivated by default: system_config/number_manager.released_state
defaults to available
.
released
does not participate in number hunts- Releasing a
reserved
orin_service
number,- when the reserve history is empty: the number will be disconnected then either returned or marked for deletion (see
system_config/number_manager.should_permanently_delete
)- Note:
knm_local
andknm_mdn
numbers always go to deletion regardless of this config flag's value
- Note:
- when the reserve history is not empty, the number is assigned to the previous account in the history
- when the reserve history is empty: the number will be disconnected then either returned or marked for deletion (see
- E911 and all other number features are stripped off the number
port_out
#
An internal state for releasing numbers.
Works similarly to port_in
except that inbound requests do not move to in_service
.
deleted
#
An old internal state marking the number as hard-deletable. This state is no longer used: numbers are no longer soft-deleted.