N2IVR GUI Configuration
Introduction
The N2IVR GUI is largely configured by the Jarvis configuration file for the GUI, however several configuration changes must be made to the database directly. See Database Configuaration for these.
The Jarvis configuration file, located at /etc/jarvis/n2ivr-gui.xml provides several configuration fields
which may be adjusted on installation as required for each deployment. For more information on Jarvis and
general configuration options, see the N-Squared Jarvis page on the
N-Squared documentation website.
Authentication Models
The N2IVR GUI supports OAuth 2.0 and local database-based authentication.
Database Authentication
The N2IVR GUI supports local database authentication for user login. This is the default configuration for a new system installation.
A default administration user admin is created, with the default password
admin. Database authentication is enabled by having the following Jarvis-
based configuration (in n2ivr-gui.xml) uncommented:
<login module="N2::SIP::Login">
<parameter name="expiry_in_seconds" value="1800"/>
</login>
<hook module="N2::SIP::Login"/>
Additionally, the <habitat> should not include an "auth" section in the
JSON stored in the habitat, otherwise the frontend GUI will believe that
public auth should be used.
It is recommended the administrator password be changed immediately on installation. Use the user administration screens or command line tools to make this change.
OAuth 2.0
To enable OAuth 2.0, the following changes to the installed n2ivr-gui.xml
file must be performed. Locate the following section of the configuration file
and add the auth section into the <habitat>:
This section:
<!-- Example Habitat configuration for an Azure Public OAuth authentication mechanism. -->
<!--
<habitat>
<![CDATA[{
"auth": {
"auth_type": "oauth"
, "oauth": {
"response_type" : "code"
, "access_type" : "public"
, "site" : "https://login.microsoftonline.com"
, "authorize_endpoint" : "/<tenant_id>/oauth2/v2.0/authorize"
, "client_id" : "<client_id>"
, "redirect_uri" : "http://<hostname>/n2ivr/complete-oauth-login"
, "token_endpoint" : "/<tenant_id>/oauth2/v2.0/token"
, "send_challenge_code" : true
, "scope" : "api://<application_scope_id>/n2ivr"
}
}
}]]>
</habitat>
-->
should become similar to:
<habitat>
<![CDATA[{
"auth": {
"auth_type": "oauth"
, "oauth": {
"response_type" : "code"
, "access_type" : "public"
, "site" : "https://login.microsoftonline.com"
, "authorize_endpoint" : "/<tenant_id>/oauth2/v2.0/authorize"
, "client_id" : "<client_id>"
, "redirect_uri" : "http://<hostname>/n2ivr/complete-oauth-login"
, "token_endpoint" : "/<tenant_id>/oauth2/v2.0/token"
, "send_challenge_code" : true
, "scope" : "api://<application_scope_id>/n2ivr"
}
}
}]]>
</habitat>
Note that the auth configuration must be configured to use the OAuth provider selected for authentication. For more
information on the Jarvis OAuth configuration, see the Jarvis configuration guide.
In addition to updating the habitat section, the following login module must be uncommented and configured
with the same values used in the <habitat> section:
<login module="Jarvis::Login::OAuth2">
<parameter name="grant_type" value="auth_code"/>
<parameter name="access_type" value="public"/>
<parameter name="site" value="https://login.microsoftonline.com"/>
<parameter name="public_key_path" value="/<tenant_id>/discovery/v2.0/keys"/>
<parameter name="public_key_store" value="/tmp/auth_public_key"/>
<parameter name="public_key_lifetime_seconds" value="60"/>
<parameter name="groups_key" value="groups"/>
<parameter name="username_key" value="unique_name"/>
<parameter name="user_identifier_key" value="oid"/>
<group_mappings>
<group_mapping from="<group_oid>" to="administrator,restricted_user"/>
</group_mappings>
</login>
<hook module="N2::SIP::OAuthLogin"/>
Additional group mappings can be made to associate received OAuth groups with
N2IVR administrator or restricted_user groups.
Finally the following login configuration must be removed (or commented out), to disable local (DB) based authentication:
<!--
<login module="N2::SIP::Login">
<parameter name="expiry_in_seconds" value="1800"/>
</login>
<hook module="N2::SIP::Login"/>
-->
Additional User Configuration
To correctly work with restricted user access, the OAuth authentication
mechanism requires a default restricted_user user to be added to the
database. To create the necessary restricted user setup, run the following
SQL against the n2ivr database schema:
INSERT INTO n2ivr.announcement_id_groups (group_name, min_announcement_id, max_announcement_id) VALUES ('restricted_user', 1, 100000);
INSERT INTO n2ivr.users(user_name, password, enabled, access_level) VALUES ('restricted_user', '13+lROnwRYzjWgtkTfr+a9007a43afc4d3cbde349c7a9efa287ea3e0a07c82400c', TRUE, 10);
INSERT INTO n2ivr.user_announcement_id_groups (user_id, announcement_id_groups_id)
SELECT user_id, (SELECT announcement_id_groups_id FROM n2ivr.announcement_id_groups WHERE group_name = 'restricted_user')
FROM n2ivr.users WHERE user_name = 'restricted_user';
Note that the maximum announcement ID to be used on-platform can be set to a maximum of 2147483647. It can be decreased as low as is appropriate for the deployment.
A value of 100000 is selected as a default.
Note that the admin and restricted_user users stored in the database
are never used for login authentication, only for group (resource ID)
authorization.
Base URL Configuration
The installation of the IVR GUI installs Apache configuration for the
base URL /n2ivr/. If this is changed, the base URL to access the IVR
must be explicitly listed. In the configuration section of the n2ivr-gui.xml
configuration, define this base URL:
<config>
...
<api_base url="/api"/>
</config>
Set the url attribute to the base URL. This base URL can include the
hostname that user’s access the IVR through. The URL must resolve to
the IVR API.
Disk Storage for Files
Regardless of whether file- or database-based storage & replication is used (see next section) the N2IVR system stores a copy of the working set of audio files on disk in a resources directory.
This directory must be configured in the N2IVR GUI configuration section:
<config>
...
<local_audio_storage directory="/var/lib/n2ivr/resources"/>
</config>
Change the local_audio_storage configuration directory as required for
the SMS installation of the N2IVR GUI package.
Database or File Based Replication
The N2IVR GUI supports the configuration of both file-based and database-based replication of audio content and announcement configuration from the GUI (SMS) node to service nodes. By default database replication is enabled and will to be used. However if file-based replication is to be used, change the database configuration to enable file based sync.
Connected to the N2IVR database, run the following update command:
UPDATE n2ivr.config set disk_audio_file_storage = TRUE;
When using file-base replication the live directory on the service nodes must
be configured, and optionally paths to both the local and remote rsync binaries.
These are configured in the config section of the Jarvis file:
<config>
...
<!-- Where we sync files to on remote service nodes -->
<service_node_audio_storage directory="/var/lib/n2ivr/resources/live"/>
<!-- rsync binaries to use when syncing between local and remote systems -->
<rsync logfile="/tmp/n2ivr_disk_synchronisation.log" local="/usr/bin/rsync" remote="/usr/bin/rsync"/>
</config>
The logfile attribute can be optionally defined to log sync information in
more detail to a file on disk. This can help determine issues that might
not be able to be logged to the database due to (for example) database
connectivity issues.
Finally, a database connection must be specified for the connection of the sync process to the database. This connection should be set up to use the same connection details as the main connection used by the GUI to the database:
<database name="filesync" connect="dbi:Pg:dbname=n2in;host=127.0.0.1" username="n2ivr_web" password="n2ivr_web"/>
Audio Encodings
The N2IVR service node on which N2SVCD and its SIP and RTP services are running will support streaming audio in one or more
audio formats. Those audio formats are configured in the <config> section of the Jarvis configuration file:
<config>
<!-- Audio identification module. -->
<audio_identifier binary="/usr/bin/soxi"/>
<!-- Source encoding play flags. Kept separate to avoid special logic in the audio encodings. -->
<source_encoding binary="/usr/bin/sox" play_flags="--magic -q '%s' '%s'"/>
<!-- Configuration for each of our supported file codecs. -->
<audio_encodings>
<audio_encoding key="al" label="A-Law" description="ITU-T REC G.711 u-law, 8000 Hz, 64 kbit/s, mono." type="al" extension=".al" binary="/usr/bin/sox" play_flags="--magic -r 8000 -c 1 -q '%s' '%s'" encode_flags="'%s' -t raw -q -r 8000 -c 1 -e a-law '%s'"/>
<audio_encoding key="ul" label="U-Law" description="ITU-T REC G.711 a-law, 8000 Hz, 64 kbit/s, mono." type="ul" extension=".ul" binary="/usr/bin/sox" play_flags="--magic -r 8000 -c 1 -q '%s' '%s'" encode_flags="'%s' -t raw -q -r 8000 -c 1 -e u-law '%s'"/>
<audio_encoding key="amr" label="AMR-NB" description="3GPP TS 26.073 adaptive multi-rate [narrowband] (AMR-NB), 8000 Hz, mono." type="amr-nb" extension=".amr" binary="/usr/bin/bash" play_flags="-i '%s' -c:a libvorbis -b:a 64k -y '%s'" encode_flags="input_file='%s'; output_file='%s'; audio_files=(); modes=(4750 5150 5900 6700 7400 7950 10200 12200); for mode in "${modes[@]}"; do /usr/bin/ffmpeg -i "$input_file" -f amr -c:a amr_nb -ar 8000 -y -ac 1 -b:a $mode "$output_file.$mode"; audio_files+=("$output_file.$mode"); done; /usr/bin/tar -cf "$output_file" "${audio_files[@]}"; /usr/bin/rm "${audio_files[@]}""/>
<audio_encoding key="awb" label="AMR-WB" description="ITU-T REC G.722.2 adaptive multi-rate wideband (AMR-WB), 16000 Hz, mono." type="amr-wb" extension=".awb" binary="/usr/bin/bash" play_flags="-i '%s' -c:a libvorbis -b:a 64k -y '%s'" encode_flags="input_file='%s'; output_file='%s'; audio_files=(); modes=(6600 8850 12650 14250 15850 18250 19850 23050 23850); for mode in "${modes[@]}"; do /usr/bin/ffmpeg -i "$input_file" -f amr -c:a amr_wb -ar 16000 -y -ac 1 -b:a $mode "$output_file.$mode"; audio_files+=("$output_file.$mode"); done; /usr/bin/tar -cf "$output_file" "${audio_files[@]}"; /usr/bin/rm "${audio_files[@]}""/>
</audio_encodings>
</config>
Supported encodings are currently A-law, U-law, AMR Narrowband, and AMR Wideband. These come preconfigured, but may be disabled by commenting out the
corresponding <audio_encoding> element(s) as required.
Database Configuration
The N2IVR GUI requires several direct database updates to be made before the
GUI can be used. First, connect to the configuration database as n2ivr_owner and apply
the following configuration:
psql -h localhost -U n2ivr_owner n2in -W
Disabling the “Working” Set
By default the N2IVR GUI will require users to make changes to an interim “working” set before changes to the announcement configuration can be synced and made available to the N2IVR AS nodes.
However, if you want to disable the working set, and make all changes immediately available to N2IVR AS nodes (delayed only by database replication and N2IVR AS RPT cache timers), change the configuration in the N2IVR database.
Connected to the N2IVR database, run the following update command:
UPDATE n2ivr.config set enable_working_set = FALSE;
Reload any N2IVR GUI screens open. From the point of the change on, changes can (and must) be made to the active announcement set, not the working set.
Note that if file-based sync is enabled, then the sync is still required to be performed to transfer files from the SMS node to the N2IVR AS nodes.
IVR Language Configuration
To configure the languages available in the N2IVR GUI, add the language
names to the n2ivr.langauge table. Connect to the N2IVR database and
run the following insert command for each language required:
INSERT INTO n2ivr.language (language_name, creation_user) VALUES ('<language>', 'initial creation');
Where <language> is the language name.
Available language are:
- Arabic
- Cantonese
- Dhivehi
- English
- German
- Hindi
- Japanese
- Mandarin
Each language listed above also has an associated language codec. Other language names can be used if a specific language codec is not required.
Audio Codec Configuration
The N2IVR GUI must be configured to support each individual audio codec that may be uploaded or used during RTP playback.
Once connected to the configuration database as n2ivr_owner define each audio codec
that will be supported. Select from the following:
-- These are encodings used by the service during playback. -- This list corresponds with definitions in lib/N2/RTP/Encoding.pm.
INSERT INTO n2ivr.audio_file_encoding (audio_file_encoding_name, file_extension, creation_user) VALUES ('A-Law', 'al', 'initial creation');
INSERT INTO n2ivr.audio_file_encoding (audio_file_encoding_name, file_extension, creation_user) VALUES ('μ-Law', 'ul', 'initial creation');
INSERT INTO n2ivr.audio_file_encoding (audio_file_encoding_name, file_extension, creation_user) VALUES ('AMR-NB', 'amr', 'initial creation');
INSERT INTO n2ivr.audio_file_encoding (audio_file_encoding_name, file_extension, creation_user) VALUES ('AMR-WB', 'awb', 'initial creation');
-- These are valid encodings for source files.
INSERT INTO n2ivr.audio_file_encoding (audio_file_encoding_name, file_extension, creation_user) VALUES ('MP3', 'mp3', 'initial creation');
INSERT INTO n2ivr.audio_file_encoding (audio_file_encoding_name, file_extension, creation_user) VALUES ('OGG', 'ogg', 'initial creation');
INSERT INTO n2ivr.audio_file_encoding (audio_file_encoding_name, file_extension, creation_user) VALUES ('FLAC', 'flac', 'initial creation');
INSERT INTO n2ivr.audio_file_encoding (audio_file_encoding_name, file_extension, creation_user) VALUES ('RAW', 'raw', 'initial creation');
INSERT INTO n2ivr.audio_file_encoding (audio_file_encoding_name, file_extension, creation_user) VALUES ('WAV', 'wav', 'initial creation');