KZOO-60: permit conference feature code (2600hz#6425)

* KZOO-60: permit conference feature code

Rather than needing to know the extension to dial for a conference,
allow a feature code to capture the conference ID from the dialed
number. Useful for clients that are provisioned dynamically (like
WebRTC devices) that have full control over the dialed number (as
opposed to typical desk phones which only dial digits).

Makefile

@@ -352,9 +352,7 @@ check_stacktrace:
 ## Adding this format couchdb view target to circleci steps for every app is painful
 ## also this formatting is better to be done before validate-js ci step to make sure
 ## the view is still in correct shape
-apis:
-	@ERL_LIBS=deps:core:applications $(ROOT)/scripts/generate-schemas.escript
-	@$(ROOT)/scripts/format-json.py $(shell find applications core -wholename '*/schemas/*.json')
+apis: schemas
 	@ERL_LIBS=deps:core:applications $(ROOT)/scripts/generate-api-endpoints.escript
 	@$(ROOT)/scripts/generate-doc-schemas.py `egrep -rl '(#+) Schema' core/ applications/ | grep -v '.[h|e]rl'`
 	@$(ROOT)/scripts/format-json.py applications/crossbar/priv/api/swagger.json
@@ -364,8 +362,10 @@ apis:
 	@$(ROOT)/scripts/format-couchdb-views.py $(shell find core/kazoo_apps/priv/couchdb/account -name '*.json')
 	@$(ROOT)/scripts/format-couchdb-views.py $(shell find applications core -wholename '*/couchdb/views/*.json')
 
+.PHONY: schemas
 schemas:
-	@ERL_LIBS=deps:core:applications $(ROOT)/scripts/generate-schemas.escript
+	@ERL_LIBS=deps:core:applications $(ROOT)/scripts/generate-schemas.escript $(CHANGED_ERL)
+	@$(ROOT)/scripts/format-json.py $(shell find applications core -wholename '*/schemas/*.json')
 
 DOCS_ROOT=$(ROOT)/doc/mkdocs
 docs: docs-validate docs-report docs-setup docs-build

applications/callflow/doc/conference_feature.md

@@ -0,0 +1,109 @@
+## Conference Feature
+
+### About Conference Feature
+
+Add ability to dial a conference by ID instead of extension. Useful for clients like WebRTC devices where the dialstring is more easily manipulated.
+
+Combine with a regexp pattern in the callflow to capture the ID:
+
+```json
+{"name":"Straight to the conference"
+ ,"patterns":["(.{32})"]
+ ,"flow":{
+   "module":"conference_feature"
+   ,"data":{normal conference settings, if any}
+ }
+}
+```
+
+#### Schema
+
+Validator for the Conference feature code
+
+
+
+Key | Description | Type | Default | Required | Support Level
+--- | ----------- | ---- | ------- | -------- | -------------
+`config` | Build an ad-hoc conference using the conferences JSON schema | `object()` |   | `false` |  
+`id` | Kazoo ID of the conference | `string(32)` |   | `false` |  
+`moderator` | Is the caller entering the conference as a moderator | `boolean()` |   | `false` |  
+`play_entry_tone` | Should the Entry Tone be played | `boolean() | string()` |   | `false` |  
+`play_exit_tone` | Should the Exit Tone be played | `boolean() | string()` |   | `false` |  
+`skip_module` | When set to true this callflow action is skipped, advancing to the wildcard branch (if any) | `boolean()` |   | `false` |  
+`welcome_prompt.media_id` | Media to play, either Kazoo media ID or URL | `string()` |   | `false` |  
+`welcome_prompt.play` | Should the Welcome Prompt be played | `boolean()` | `true` | `false` |  
+`welcome_prompt` | Describes how the caller is greeted on entering a conference | `object()` |   | `false` |  
+
+### conferences
+
+Schema for conferences
+
+
+Key | Description | Type | Default | Required | Support Level
+--- | ----------- | ---- | ------- | -------- | -------------
+`bridge_password` | the password used for a conference bridge | `string()` |   | `false` |  
+`bridge_username` | the username used for a conference bridge | `string()` |   | `false` |  
+`caller_controls` | caller controls (config settings) | `string()` |   | `false` |  
+`conference_numbers.[]` |   | `string()` |   | `false` |  
+`conference_numbers` | Defines conference numbers that can be used by members or moderators | `array(string())` | `[]` | `false` |  
+`controls` | controls | `object()` |   | `false` |  
+`domain` | domain | `string()` |   | `false` |  
+`flags.[]` |   | `string()` |   | `false` | `supported`
+`flags` | Flags set by external applications | `array(string())` |   | `false` | `supported`
+`focus` | This is a read-only property indicating the media server hosting the conference | `string()` |   | `false` |  
+`language` | Prompt language to play in the conference | `string()` |   | `false` |  
+`max_members_media` | Media to play when the conference is full | `string()` |   | `false` |  
+`max_participants` | The maximum number of participants that can join | `integer()` |   | `false` |  
+`member.join_deaf` | Determines if a member will join deaf | `boolean()` | `false` | `false` | `supported`
+`member.join_muted` | Determines if a member will join muted | `boolean()` | `true` | `false` | `supported`
+`member.numbers.[]` |   | `string()` |   | `false` |  
+`member.numbers` | Defines the conference (call in) number(s) for members | `array(string())` | `[]` | `false` |  
+`member.pins.[]` |   | `string()` |   | `false` |  
+`member.pins` | Defines the pin number(s) for members | `array(string())` | `[]` | `false` |  
+`member.play_entry_prompt` | Whether to play the entry prompt on member join | `boolean()` |   | `false` |  
+`member` | Defines the discovery (call in) properties for a member | `object()` | `{}` | `false` |  
+`moderator.join_deaf` | Determines if a moderator will join deaf | `boolean()` | `false` | `false` |  
+`moderator.join_muted` | Determines if a moderator will join muted | `boolean()` | `false` | `false` |  
+`moderator.numbers.[]` |   | `string()` |   | `false` |  
+`moderator.numbers` | Defines the conference (call in) number(s) for moderators | `array(string())` | `[]` | `false` |  
+`moderator.pins.[]` |   | `string()` |   | `false` |  
+`moderator.pins` | Defines the pin number(s) for moderators | `array(string())` | `[]` | `false` |  
+`moderator` | Defines the discovery (call in) properties for a moderator | `object()` | `{}` | `false` |  
+`moderator_controls` | profile on the switch for controlling the conference as a moderator | `string()` |   | `false` |  
+`name` | A friendly name for the conference | `string(1..128)` |   | `false` | `supported`
+`owner_id` | The user ID who manages this conference | `string(32)` |   | `false` | `supported`
+`play_entry_tone` | Whether to play an entry tone, or the entry tone to play | `boolean() | string()` |   | `false` | `supported`
+`play_exit_tone` | Whether to play an exit tone, or the exit tone to play | `boolean() | string()` |   | `false` | `supported`
+`play_name` | Do we need to announce new conference members? | `boolean()` | `false` | `false` |  
+`play_welcome` | Whether to play the welcome prompt | `boolean()` |   | `false` |  
+`profile` | Profile configuration | `object()` |   | `false` |  
+`profile_name` | conference profile name | `string()` |   | `false` |  
+`require_moderator` | does the conference require a moderator | `boolean()` |   | `false` |  
+`wait_for_moderator` | should members wait for a moderator before joining the conference | `boolean()` |   | `false` |  
+
+### conferences.profile
+
+Schema for conference profiles
+
+
+Key | Description | Type | Default | Required | Support Level
+--- | ----------- | ---- | ------- | -------- | -------------
+`alone-sound` | Audio that plays while you are alone in the conference | `string()` |   | `false` |  
+`announce-count` | Play member count to conference when above this threshold | `integer()` |   | `false` |  
+`caller-controls` | Name of the caller control group | `string()` |   | `false` |  
+`comfort-noise` | The volume level of background white noise | `integer()` |   | `false` |  
+`energy-level` | Energy level required for audio to be sent to other users | `integer()` |   | `false` |  
+`enter-sound` | Audio to play when entering a conference | `string()` |   | `false` |  
+`exit-sound` | Audio to play when exiting a conference | `string()` |   | `false` |  
+`interval` | Milliseconds per frame | `integer()` |   | `false` |  
+`locked-sound` | Audio to play when the conference is locked | `string()` |   | `false` |  
+`max-members` | Set the maximum number of members in the conference | `integer()` |   | `false` |  
+`max-members-sound` | If max-members has been reached, audio to play to caller instead of joining the conference | `string()` |   | `false` |  
+`moderator-controls` | Name of the moderator control group to use | `string()` |   | `false` |  
+`moh-sound` | Audio to play, on a loop, while participant count is 1 | `string()` |   | `false` |  
+`muted-sound` | Audio to play when muted | `string()` |   | `false` |  
+`rate` | Audio sample rate | `integer()` |   | `false` |  
+`unmuted-sound` | Audio to play when unmuted | `string()` |   | `false` |  
+
+
+

applications/callflow/doc/ref/conference_feature.md

@@ -0,0 +1,95 @@
+## Conference Feature
+
+### About Conference Feature
+
+#### Schema
+
+Validator for the Conference feature code
+
+
+
+Key | Description | Type | Default | Required | Support Level
+--- | ----------- | ---- | ------- | -------- | -------------
+`config` | Build an ad-hoc conference using the conferences JSON schema | `object()` |   | `false` |  
+`id` | Kazoo ID of the conference | `string(32)` |   | `false` |  
+`moderator` | Is the caller entering the conference as a moderator | `boolean()` |   | `false` |  
+`play_entry_tone` | Should the Entry Tone be played | `boolean() | string()` |   | `false` |  
+`play_exit_tone` | Should the Exit Tone be played | `boolean() | string()` |   | `false` |  
+`skip_module` | When set to true this callflow action is skipped, advancing to the wildcard branch (if any) | `boolean()` |   | `false` |  
+`welcome_prompt.media_id` | Media to play, either Kazoo media ID or URL | `string()` |   | `false` |  
+`welcome_prompt.play` | Should the Welcome Prompt be played | `boolean()` | `true` | `false` |  
+`welcome_prompt` | Describes how the caller is greeted on entering a conference | `object()` |   | `false` |  
+
+### conferences
+
+Schema for conferences
+
+
+Key | Description | Type | Default | Required | Support Level
+--- | ----------- | ---- | ------- | -------- | -------------
+`bridge_password` | the password used for a conference bridge | `string()` |   | `false` |  
+`bridge_username` | the username used for a conference bridge | `string()` |   | `false` |  
+`caller_controls` | caller controls (config settings) | `string()` |   | `false` |  
+`conference_numbers.[]` |   | `string()` |   | `false` |  
+`conference_numbers` | Defines conference numbers that can be used by members or moderators | `array(string())` | `[]` | `false` |  
+`controls` | controls | `object()` |   | `false` |  
+`domain` | domain | `string()` |   | `false` |  
+`flags.[]` |   | `string()` |   | `false` | `supported`
+`flags` | Flags set by external applications | `array(string())` |   | `false` | `supported`
+`focus` | This is a read-only property indicating the media server hosting the conference | `string()` |   | `false` |  
+`language` | Prompt language to play in the conference | `string()` |   | `false` |  
+`max_members_media` | Media to play when the conference is full | `string()` |   | `false` |  
+`max_participants` | The maximum number of participants that can join | `integer()` |   | `false` |  
+`member.join_deaf` | Determines if a member will join deaf | `boolean()` | `false` | `false` | `supported`
+`member.join_muted` | Determines if a member will join muted | `boolean()` | `true` | `false` | `supported`
+`member.numbers.[]` |   | `string()` |   | `false` |  
+`member.numbers` | Defines the conference (call in) number(s) for members | `array(string())` | `[]` | `false` |  
+`member.pins.[]` |   | `string()` |   | `false` |  
+`member.pins` | Defines the pin number(s) for members | `array(string())` | `[]` | `false` |  
+`member.play_entry_prompt` | Whether to play the entry prompt on member join | `boolean()` |   | `false` |  
+`member` | Defines the discovery (call in) properties for a member | `object()` | `{}` | `false` |  
+`moderator.join_deaf` | Determines if a moderator will join deaf | `boolean()` | `false` | `false` |  
+`moderator.join_muted` | Determines if a moderator will join muted | `boolean()` | `false` | `false` |  
+`moderator.numbers.[]` |   | `string()` |   | `false` |  
+`moderator.numbers` | Defines the conference (call in) number(s) for moderators | `array(string())` | `[]` | `false` |  
+`moderator.pins.[]` |   | `string()` |   | `false` |  
+`moderator.pins` | Defines the pin number(s) for moderators | `array(string())` | `[]` | `false` |  
+`moderator` | Defines the discovery (call in) properties for a moderator | `object()` | `{}` | `false` |  
+`moderator_controls` | profile on the switch for controlling the conference as a moderator | `string()` |   | `false` |  
+`name` | A friendly name for the conference | `string(1..128)` |   | `false` | `supported`
+`owner_id` | The user ID who manages this conference | `string(32)` |   | `false` | `supported`
+`play_entry_tone` | Whether to play an entry tone, or the entry tone to play | `boolean() | string()` |   | `false` | `supported`
+`play_exit_tone` | Whether to play an exit tone, or the exit tone to play | `boolean() | string()` |   | `false` | `supported`
+`play_name` | Do we need to announce new conference members? | `boolean()` | `false` | `false` |  
+`play_welcome` | Whether to play the welcome prompt | `boolean()` |   | `false` |  
+`profile` | Profile configuration | `object()` |   | `false` |  
+`profile_name` | conference profile name | `string()` |   | `false` |  
+`require_moderator` | does the conference require a moderator | `boolean()` |   | `false` |  
+`wait_for_moderator` | should members wait for a moderator before joining the conference | `boolean()` |   | `false` |  
+
+### conferences.profile
+
+Schema for conference profiles
+
+
+Key | Description | Type | Default | Required | Support Level
+--- | ----------- | ---- | ------- | -------- | -------------
+`alone-sound` | Audio that plays while you are alone in the conference | `string()` |   | `false` |  
+`announce-count` | Play member count to conference when above this threshold | `integer()` |   | `false` |  
+`caller-controls` | Name of the caller control group | `string()` |   | `false` |  
+`comfort-noise` | The volume level of background white noise | `integer()` |   | `false` |  
+`energy-level` | Energy level required for audio to be sent to other users | `integer()` |   | `false` |  
+`enter-sound` | Audio to play when entering a conference | `string()` |   | `false` |  
+`exit-sound` | Audio to play when exiting a conference | `string()` |   | `false` |  
+`interval` | Milliseconds per frame | `integer()` |   | `false` |  
+`locked-sound` | Audio to play when the conference is locked | `string()` |   | `false` |  
+`max-members` | Set the maximum number of members in the conference | `integer()` |   | `false` |  
+`max-members-sound` | If max-members has been reached, audio to play to caller instead of joining the conference | `string()` |   | `false` |  
+`moderator-controls` | Name of the moderator control group to use | `string()` |   | `false` |  
+`moh-sound` | Audio to play, on a loop, while participant count is 1 | `string()` |   | `false` |  
+`muted-sound` | Audio to play when muted | `string()` |   | `false` |  
+`rate` | Audio sample rate | `integer()` |   | `false` |  
+`unmuted-sound` | Audio to play when unmuted | `string()` |   | `false` |  
+
+
+

applications/callflow/src/module/cf_conference.erl

@@ -28,7 +28,7 @@ handle(Data, Call) ->
     Command =
         props:filter_undefined(
           [{<<"Call">>, kapps_call:to_json(Call)}
-          ,{<<"Conference-ID">>, kz_json:get_ne_binary_value(<<"id">>, Data)}
+          ,{<<"Conference-ID">>, kz_doc:id(Data)}
           ,{<<"Moderator">>, kz_json:get_binary_boolean(<<"moderator">>, Data)}
           ,{<<"Play-Welcome">>, kz_json:is_true([<<"welcome_prompt">>, <<"play">>], Data, 'true')}
           ,{<<"Play-Welcome-Media">>, kz_json:get_ne_value([<<"welcome_prompt">>, <<"media_id">>], Data)}

applications/callflow/src/module/cf_conference_feature.erl

@@ -0,0 +1,27 @@
+%%%-----------------------------------------------------------------------------
+%%% @copyright (C) 2013-2020, 2600Hz
+%%% @doc Get conference ID from capture group and put caller into conference
+%%% This Source Code Form is subject to the terms of the Mozilla Public
+%%% License, v. 2.0. If a copy of the MPL was not distributed with this
+%%% file, You can obtain one at https://mozilla.org/MPL/2.0/.
+%%%
+%%% @end
+%%%-----------------------------------------------------------------------------
+-module(cf_conference_feature).
+
+-behaviour(gen_cf_action).
+
+-include("callflow.hrl").
+
+-export([handle/2]).
+
+%%------------------------------------------------------------------------------
+%% @doc Entry point for this module, creates the parameters and branches
+%% to cf_group_pickup.
+%% @end
+%%------------------------------------------------------------------------------
+-spec handle(kz_json:object(), kapps_call:call()) -> 'ok'.
+handle(Data, Call) ->
+    Id = kapps_call:kvs_fetch('cf_capture_group', Call),
+    lager:info("routing to captured conference ~s", [Id]),
+    cf_conference:handle(kz_doc:set_id(Data, Id), Call).

applications/crossbar/priv/api/swagger.json

@@ -2128,6 +2128,68 @@
             },
             "type": "object"
         },
+        "callflows.conference_feature": {
+            "description": "Validator for the Conference feature code",
+            "properties": {
+                "config": {
+                    "$ref": "#/definitions/conferences",
+                    "description": "Build an ad-hoc conference using the conferences JSON schema",
+                    "type": "object"
+                },
+                "id": {
+                    "description": "Kazoo ID of the conference",
+                    "maxLength": 32,
+                    "minLength": 32,
+                    "type": "string"
+                },
+                "moderator": {
+                    "description": "Is the caller entering the conference as a moderator",
+                    "type": "boolean"
+                },
+                "play_entry_tone": {
+                    "description": "Should the Entry Tone be played",
+                    "oneOf": [
+                        {
+                            "type": "boolean"
+                        },
+                        {
+                            "type": "string"
+                        }
+                    ]
+                },
+                "play_exit_tone": {
+                    "description": "Should the Exit Tone be played",
+                    "oneOf": [
+                        {
+                            "type": "boolean"
+                        },
+                        {
+                            "type": "string"
+                        }
+                    ]
+                },
+                "skip_module": {
+                    "description": "When set to true this callflow action is skipped, advancing to the wildcard branch (if any)",
+                    "type": "boolean"
+                },
+                "welcome_prompt": {
+                    "description": "Describes how the caller is greeted on entering a conference",
+                    "properties": {
+                        "media_id": {
+                            "description": "Media to play, either Kazoo media ID or URL",
+                            "type": "string"
+                        },
+                        "play": {
+                            "default": true,
+                            "description": "Should the Welcome Prompt be played",
+                            "type": "boolean"
+                        }
+                    },
+                    "type": "object"
+                }
+            },
+            "type": "object"
+        },
         "callflows.dead_air": {
             "description": "Validator for the dead_air callflow data object",
             "properties": {