PISTON-542: add the cf_acdc_wait_time module (#4619)

PISTON-542: move cf_acdc_wait_time module into acdc app

PISTON-542: fixes for master, remove custom KVs code

PISTON-542: make code_checks

PISTON-542: make docs

PISTON-542: add documentation of cf_acdc_wait_time module purpose

PISTON-556: acdc average wait time req custom window

Conflicts:
	applications/acdc/src/acdc_stats.erl
	applications/acdc/src/cf_acdc_wait_time.erl
	applications/callflow/doc/acdc_wait_time.md
	applications/callflow/doc/ref/acdc_wait_time.md
	applications/crossbar/priv/api/swagger.json
	applications/crossbar/priv/couchdb/schemas/callflows.acdc_wait_time.json

address edoc

applications/acdc/src/acdc_stats.erl

@@ -340,7 +340,8 @@ handle_call_query(JObj, _Prop) ->
 -spec handle_average_wait_time_req(kz_json:object(), kz_term:proplist()) -> 'ok'.
 handle_average_wait_time_req(JObj, _Prop) ->
     'true' = kapi_acdc_stats:average_wait_time_req_v(JObj),
-    query_average_wait_time(JObj).
+    Match = average_wait_time_build_match_spec(JObj),
+    query_average_wait_time(Match, JObj).
 
 -spec find_call(kz_term:ne_binary()) -> kz_term:api_object().
 find_call(CallId) ->
@@ -550,6 +551,38 @@ call_match_builder_fold(<<"End-Range">>, End, {CallStat, Contstraints}) ->
     end;
 call_match_builder_fold(_, _, Acc) -> Acc.
 
+-spec average_wait_time_build_match_spec(kz_json:object()) -> ets:match_spec().
+average_wait_time_build_match_spec(JObj) ->
+    AccountId = kz_json:get_ne_binary_value(<<"Account-ID">>, JObj),
+    QueueId = kz_json:get_ne_binary_value(<<"Queue-ID">>, JObj),
+
+    Match = [{#call_stat{account_id=AccountId
+                        ,queue_id=QueueId
+                        ,entered_timestamp='$1'
+                        ,abandoned_timestamp='$2'
+                        ,handled_timestamp='$3'
+                        ,status='$4'
+                        ,_='_'
+                        }
+             ,[{'orelse'
+               ,{'=:=', '$4', {'const', <<"handled">>}}
+               ,{'=:=', '$4', {'const', <<"processed">>}}
+               }]
+             ,[['$1', '$2', '$3']]
+             }],
+
+    Window = kz_json:get_integer_value(<<"Window">>, JObj),
+
+    average_wait_time_build_match_spec(Match, Window).
+
+-spec average_wait_time_build_match_spec(ets:match_spec(), kz_term:api_integer()) ->
+                                                ets:match_spec().
+average_wait_time_build_match_spec(Match, 'undefined') ->
+    Match;
+average_wait_time_build_match_spec([{CallStat, Conditions, Results}], Window) ->
+    Start = kz_time:current_tstamp() - Window,
+    [{CallStat, [{'>=', '$1', {'const', Start}} | Conditions], Results}].
+
 is_valid_call_status(S) ->
     Status = kz_term:to_lower_binary(S),
     case lists:member(Status, ?VALID_STATUSES) of
@@ -592,25 +625,8 @@ query_calls(RespQ, MsgId, Match, _Limit) ->
 %%
 %% @end
 %%------------------------------------------------------------------------------
--spec query_average_wait_time(kz_json:object()) -> 'ok'.
-query_average_wait_time(JObj) ->
-    AccountId = kz_json:get_ne_binary_value(<<"Account-ID">>, JObj),
-    QueueId = kz_json:get_ne_binary_value(<<"Queue-ID">>, JObj),
-    Match = [{#call_stat{account_id=AccountId
-                        ,queue_id=QueueId
-                        ,entered_timestamp='$1'
-                        ,abandoned_timestamp='$2'
-                        ,handled_timestamp='$3'
-                        ,status='$4'
-                        ,_='_'
-                        }
-             ,[{'orelse'
-               ,{'=:=', '$4', {'const', <<"handled">>}}
-               ,{'=:=', '$4', {'const', <<"processed">>}}
-               }]
-             ,[['$1', '$2', '$3']]
-             }],
-
+-spec query_average_wait_time(ets:match_spec(), kz_json:object()) -> 'ok'.
+query_average_wait_time(Match, JObj) ->
     AverageWaitTime = average_wait_time_fold(ets:select(call_table_id(), Match)),
 
     RespQ = kz_json:get_value(<<"Server-ID">>, JObj),

applications/acdc/src/cf_acdc_wait_time.erl

@@ -0,0 +1,79 @@
+%%%-----------------------------------------------------------------------------
+%%% @copyright (C) 2018-, Voxter Communications Inc
+%%% @doc Handles branching the callflow based on the current average wait time
+%%% of a queue
+%%% Data: {
+%%%   "id":"queue id",
+%%%   "window":900 // Window over which average wait time is calc'd
+%%% }
+%%%
+%%%
+%%% @author Daniel Finke
+%%% @end
+%%%-----------------------------------------------------------------------------
+-module(cf_acdc_wait_time).
+
+-export([handle/2]).
+
+-include_lib("callflow/src/callflow.hrl").
+
+%%------------------------------------------------------------------------------
+%% @doc Handle execution of this callflow module
+%% @end
+%%------------------------------------------------------------------------------
+-spec handle(kz_json:object(), kapps_call:call()) -> 'ok'.
+handle(Data, Call) ->
+    AccountId = kapps_call:account_id(Call),
+    QueueId = kz_json:get_ne_binary_value(<<"id">>, Data),
+    Window = kz_json:get_integer_value(<<"window">>, Data),
+
+    case Window of
+        'undefined' -> 'ok';
+        _ -> lager:info("evaluating average wait time over last ~b seconds", [Window])
+    end,
+
+    Req = props:filter_undefined(
+            [{<<"Account-ID">>, AccountId}
+            ,{<<"Queue-ID">>, QueueId}
+            ,{<<"Window">>, Window}
+             | kz_api:default_headers(?APP_NAME, ?APP_VERSION)
+            ]),
+    case kapps_util:amqp_pool_request(Req
+                                     ,fun kapi_acdc_stats:publish_average_wait_time_req/1
+                                     ,fun kapi_acdc_stats:average_wait_time_resp_v/1
+                                     )
+    of
+        {'ok', Resp} ->
+            AverageWaitTime = kz_json:get_integer_value(<<"Average-Wait-Time">>, Resp, 0),
+            lager:info("average wait time for account ~s queue ~s is ~B seconds", [AccountId, QueueId, AverageWaitTime]),
+            {'branch_keys', BranchKeys} = cf_exe:get_branch_keys(Call),
+            evaluate_average_wait_time(AverageWaitTime, BranchKeys, Call);
+        {'error', E} ->
+            lager:error("could not fetch average wait time for account ~s queue ~s: ~p", [AccountId, QueueId, E]),
+            cf_exe:continue(Call)
+    end.
+
+%%------------------------------------------------------------------------------
+%% @doc Continue to the branch of the callflow with the highest exceeded
+%% threshold
+%% @end
+%%------------------------------------------------------------------------------
+-spec evaluate_average_wait_time(non_neg_integer(), kz_json:path(), kapps_call:call()) -> 'ok'.
+evaluate_average_wait_time(AverageWaitTime, Keys, Call) ->
+    Keys1 = lists:sort(fun(Key1, Key2) ->
+                               kz_term:to_integer(Key1) >= kz_term:to_integer(Key2)
+                       end, Keys),
+    evaluate_average_wait_time2(AverageWaitTime, Keys1, Call).
+
+-spec evaluate_average_wait_time2(non_neg_integer(), kz_json:path(), kapps_call:call()) -> 'ok'.
+evaluate_average_wait_time2(_, [], Call) ->
+    cf_exe:continue(Call);
+evaluate_average_wait_time2(AverageWaitTime, [Key|Keys], Call) ->
+    Threshold = kz_term:to_integer(Key),
+    case AverageWaitTime >= Threshold of
+        'true' ->
+            lager:info("average wait time exceeded threshold ~B", [Threshold]),
+            cf_exe:continue(Key, Call);
+        'false' ->
+            evaluate_average_wait_time2(AverageWaitTime, Keys, Call)
+    end.

applications/acdc/src/kapi_acdc_stats.erl

@@ -291,12 +291,13 @@ current_calls_resp_v(JObj) ->
     current_calls_resp_v(kz_json:to_proplist(JObj)).
 
 -define(AVERAGE_WAIT_TIME_REQ_HEADERS, [<<"Account-ID">>, <<"Queue-ID">>]).
--define(OPTIONAL_AVERAGE_WAIT_TIME_REQ_HEADERS, []).
+-define(OPTIONAL_AVERAGE_WAIT_TIME_REQ_HEADERS, [<<"Window">>]).
 -define(AVERAGE_WAIT_TIME_REQ_VALUES, [{<<"Event-Category">>, <<"acdc_stat">>}
                                       ,{<<"Event-Name">>, <<"average_wait_time_req">>}
                                       ]).
 -define(AVERAGE_WAIT_TIME_REQ_TYPES, [{<<"Account-ID">>, fun kz_term:is_ne_binary/1}
                                      ,{<<"Queue-ID">>, fun kz_term:is_ne_binary/1}
+                                     ,{<<"Window">>, fun is_integer/1}
                                      ]).
 
 -spec average_wait_time_req(kz_term:api_terms()) ->

applications/callflow/doc/acdc_wait_time.md

@@ -0,0 +1,20 @@
+## Acdc Wait Time
+
+### About Acdc Wait Time
+
+Handles branching the callflow based on the current average wait time of a queue.
+Branch keys are integer-convertible binaries (e.g. `<<"60">>`) that represent wait time thresholds in seconds. The default branch is represented by the `_` key. The branch with the highest threshold which the queue's current average wait time exceeds is the branch followed in the callflow's execution. If none are exceeded, the default branch is followed.
+
+#### Schema
+
+Validator for the acdc_wait_time callflow's data object
+
+
+
+Key | Description | Type | Default | Required
+--- | ----------- | ---- | ------- | --------
+`id` | Queue ID | `string()` |   | `false`
+`window` | Window over which average wait time is calculated (in seconds) | `integer()` |   | `false`
+
+
+

applications/callflow/doc/ref/acdc_wait_time.md

@@ -0,0 +1,17 @@
+## Acdc Wait Time
+
+### About Acdc Wait Time
+
+#### Schema
+
+Validator for the acdc_wait_time callflow's data object
+
+
+
+Key | Description | Type | Default | Required
+--- | ----------- | ---- | ------- | --------
+`id` | Queue ID | `string()` |   | `false`
+`window` | Window over which average wait time is calculated (in seconds) | `integer()` |   | `false`
+
+
+

applications/crossbar/priv/api/swagger.json

@@ -1357,6 +1357,20 @@
             },
             "type": "object"
         },
+        "callflows.acdc_wait_time": {
+            "description": "Validator for the acdc_wait_time callflow's data object",
+            "properties": {
+                "id": {
+                    "description": "Queue ID",
+                    "type": "string"
+                },
+                "window": {
+                    "description": "Window over which average wait time is calculated (in seconds)",
+                    "type": "integer"
+                }
+            },
+            "type": "object"
+        },
         "callflows.action": {
             "description": "Call flows describe steps to take in order to process a phone call. They are trees of information related to a phone call such as \"answer, play file, record file\" etc. that are logically grouped together and ordered.",
             "properties": {
@@ -6684,6 +6698,9 @@
                 "Queue-ID": {
                     "minLength": 1,
                     "type": "string"
+                },
+                "Window": {
+                    "type": "integer"
                 }
             },
             "required": [

applications/crossbar/priv/couchdb/schemas/callflows.acdc_wait_time.json

@@ -0,0 +1,16 @@
+{
+    "$schema": "http://json-schema.org/draft-04/schema#",
+    "_id": "callflows.acdc_wait_time",
+    "description": "Validator for the acdc_wait_time callflow's data object",
+    "properties": {
+        "id": {
+            "description": "Queue ID",
+            "type": "string"
+        },
+        "window": {
+            "description": "Window over which average wait time is calculated (in seconds)",
+            "type": "integer"
+        }
+    },
+    "type": "object"
+}

applications/crossbar/priv/couchdb/schemas/kapi.acdc_stats.average_wait_time_req.json

@@ -22,6 +22,9 @@
         "Queue-ID": {
             "minLength": 1,
             "type": "string"
+        },
+        "Window": {
+            "type": "integer"
         }
     },
     "required": [

doc/mkdocs/mkdocs.yml

@@ -245,6 +245,7 @@ pages:
         - 'Agents': 'applications/callflow/doc/acdc_agent.md'
         - 'Queue Login': 'applications/callflow/doc/acdc_queue.md'
         - 'Member Entry': 'applications/callflow/doc/acdc_member.md'
+        - 'Average Wait Time': 'applications/callflow/doc/acdc_wait_time.md'
     - 'Menu (IVR)': 'applications/callflow/doc/menu.md'
     - 'Custom Webhook': 'applications/callflow/doc/webhook.md'
     - 'Channel Move': 'applications/callflow/doc/move.md'