HELP-11566: clarify precedence of call forward vs failover (2600hz#6307)

* HELP-11566: clarify precedence of call forward vs failover

The `call_forward` object handles configuration for both call
forwarding and for failover. In its current implementation, only one
of those features can be "active".

Prior to this change, if `call_forward.failover` was `true` it would
be included on the endpoint object and ecallmgr would treat the
`call_forward` settings as a failover endpoint, regardless of the
`call_forward.enabled` flag's setting.

This change clarifies that if `call_forward.enabled` is `true`, the
settings should only be considered for call forwarding. If the setting
is `false` *and* `call_forward.failover` is `true` then consider the
settings as a failover endpoint.

* fmt

applications/crossbar/doc/devices.md

@@ -251,6 +251,10 @@ Key | Description | Type | Default | Required | Support Level
 
 
 
+### Call forwarding
+
+Currently the `call_forward` object allows you to define call forwarding *or* failover but not both. If `call_forward.enabled` is `true` it will take precedence and settings will be used only for call forwarding. If `call_forward.enabled` is `false` *and* `call_forward.failover` is `true`, failover settings will be used.
+
 ## Fetch
 
 > GET /v2/accounts/{ACCOUNT_ID}/devices

core/kazoo_endpoint/src/kz_endpoint.erl

@@ -53,7 +53,6 @@ get(EndpointId, _Call) -> ?MOD:get(EndpointId, _Call).
 
 
 -ifdef(TEST).
-
 attributes_keys() -> ?MOD:attributes_keys().
 
 -spec merge_attribute(kz_term:ne_binary(), kz_term:api_object(), kz_term:api_object(), kz_term:api_object()) -> kz_json:object().
@@ -116,7 +115,6 @@ maybe_start_metaflow(Call, Endpoint) -> ?MOD:maybe_start_metaflow(Call, Endpoint
           kz_json:object().
 create_sip_endpoint(Endpoint, Properties, Call) -> ?MOD:create_sip_endpoint(Endpoint, Properties, Call).
 
-
 %%------------------------------------------------------------------------------
 %% @doc Creates the Kazoo API endpoint for a bridge call command when
 %% the device (or owner) has forwarded their phone.  This endpoint
@@ -129,7 +127,6 @@ create_sip_endpoint(Endpoint, Properties, Call) -> ?MOD:create_sip_endpoint(Endp
           kz_json:object().
 create_call_fwd_endpoint(Endpoint, Properties, Call) -> ?MOD:create_call_fwd_endpoint(Endpoint, Properties, Call).
 
-
 -spec encryption_method_map(kz_term:api_object(), kz_term:api_binaries() | kz_json:object()) -> kz_term:api_object().
 encryption_method_map(CCVs, Methods) -> ?MOD:encryption_method_map(CCVs, Methods).
 

core/kazoo_endpoint/src/kz_endpoint_v4.erl

@@ -1775,7 +1775,12 @@ maybe_set_call_forward({Endpoint, Call, CallFwd, CCVs}) ->
 
 -spec is_failover(kz_json:object()) -> 'true' | 'undefined'.
 is_failover(CallFwd) ->
-    case kz_json:is_true(<<"failover">>, CallFwd) of
+    IsFailover = kz_json:is_true(<<"failover">>, CallFwd),
+    IsCallFwdEnabled = kz_json:is_true(<<"enabled">>, CallFwd),
+
+    case (not IsCallFwdEnabled)
+        andalso IsFailover
+    of
         'true' -> 'true';
         'false' -> 'undefined'
     end.

core/kazoo_endpoint/src/kz_endpoint_v5.erl

@@ -1715,7 +1715,12 @@ maybe_set_call_forward({Endpoint, Call, CallFwd, CCVs}) ->
 
 -spec is_failover(kz_json:object()) -> 'true' | 'undefined'.
 is_failover(CallFwd) ->
-    case kz_json:is_true(<<"failover">>, CallFwd) of
+    IsFailover = kz_json:is_true(<<"failover">>, CallFwd),
+    IsCallFwdEnabled = kz_json:is_true(<<"enabled">>, CallFwd),
+
+    case (not IsCallFwdEnabled)
+        andalso IsFailover
+    of
         'true' -> 'true';
         'false' -> 'undefined'
     end.