☰
Navigation :

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, Active Directory / LDAP 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::InternalLogin">
        <parameter name="expiry_in_seconds" value="1800"/>
    </login>

    <hook module="N2::SIP::InternalLogin"/>

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="<administrator_group_oid>" to="administrator"/>
            <group_mapping from="<restricted_group_oid>"    to="restricted"/>
            <group_mapping from="<read_only_group_oid>"     to="read_only"/>
        </group_mappings>
    </login>

    <hook module="N2::SIP::ExternalLogin"/>

Additional group mappings can be made to associate received OAuth groups with N2IVR administrator, restricted or read_only groups.

Finally the following login configuration must be removed (or commented out), to disable local (DB) based authentication:

    <!--
    <login module="N2::SIP::InternalLogin">
        <parameter name="expiry_in_seconds" value="1800"/>
    </login>

    <hook module="N2::SIP::InternalLogin"/>
    -->

Active Directory / LDAP

To enable Active Directory / LDAP, 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": "ldap"
        }
        }]]>
    </habitat>

Note that the auth configuration must be configured to use the Active Directory / LDAP server for authentication. For more information on the Jarvis Active Directory / LDAP configuration, see the Jarvis configuration guide.

In addition to updating the habitat section a <login> module must be configured. For example:

    <!-- Authentication via OpenLDAP using the ActiveDirectory module. -->
    <login module="Jarvis::Login::ActiveDirectory">
        <parameter name="server"             value="<SERVER>"/>
        <parameter name="port"               value="389"/>
        <parameter name="bind_username"      value="cn=admin,dc=nsquared,dc=nz"/>
        <parameter name="bind_password"      value="<BIND_PASSWORD>"/>
        <parameter name="base_object"        value="dc=nsquared,dc=nz"/>
        <parameter name="search_filter"      value="uid"/>
        <parameter name="use_tls"            value="1"/>
        <parameter name="group_lookup"       value="query"/>
        <parameter name="group_object_class" value="posixGroup"/>
        <parameter name="group_member_class" value="memberUid"/>
        <parameter name="group_member_bind"  value="uid"/>
        <parameter name="group_base"         value="ou=Group,dc=nsquared,dc=nz"/>

        <group_mappings>
            <group_mapping from='N2-IVR-ADMIN'      to='administrator'/>
            <group_mapping from='N2-IVR-RESTRICTED' to='restricted'/>
            <group_mapping from='N2-IVR-RO'         to='read_only'/>
        </group_mappings>
    </login>

    <hook module="N2::SIP::ExternalLogin"/>

Additional group mappings can be made to associate received OAuth groups with N2IVR administrator, restricted or read_only groups.

Finally the following login configuration must be removed (or commented out), to disable local (DB) based authentication:

    <!--
    <login module="N2::SIP::InternalLogin">
        <parameter name="expiry_in_seconds" value="1800"/>
    </login>

    <hook module="N2::SIP::InternalLogin"/>
    -->

Additional User Configuration

To correctly work with restricted user access, the OAuth and Active Directory / LDAP authentication mechanisms require default restricted and read_only users to be added to the database. To create the necessary restricted user setup, run the following SQL against the n2ivr database schema.

Restricted User

INSERT INTO n2ivr.announcement_id_groups (group_name, min_announcement_id, max_announcement_id) VALUES ('restricted', 1, 2147483647);
INSERT INTO n2ivr.users(user_name, password, access_level) VALUES ('restricted', '', 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')
FROM n2ivr.users WHERE user_name = 'restricted';

Read Only User

INSERT INTO n2ivr.announcement_id_groups (group_name, min_announcement_id, max_announcement_id) VALUES ('read_only', 1, 2147483647);
INSERT INTO n2ivr.users(user_name, password, access_level) VALUES ('read_only', '', 100);
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 = 'read_only')
FROM n2ivr.users WHERE user_name = 'read_only';

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 2147483647 is selected as a default.

Note that the admin, restricted and read_only users stored in the database are never used for login authentication, only for group (resource ID) authorization. Passwords are intentionally left empty to disallow authorization attempts.

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

When file-based storage & replication is used (see next section) the N2IVR system stores audio files for the the working set, active set, and snapshots 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.

I18N

The N2IVR GUI supports full I18N translations.

Locales may be configured via the Jarvis <habitat> configuration. Multiple locales may be supplied which will allow users to change languages as desired.

Note: If only one locale is specified no selection will be provided and that language will automatically be activated.

Note: If no locales are defined then English will automatically be activated.

"locales": [
	{ "locale": "en", "label": "English", "flag": "uk" },
	{ "locale": "ar", "label": "Arabic" , "flag": "ae" },
    { "locale": "hi", "label": "Hindi"  , "flag": "in" }
]
Property Description
locale Name of the locale to use. The name of the locale will map directly to the I18N translation JSON file stored on disk. For example en will resolve to the en.json translation file.
label If multiple locales are specified the label displayed when accessing the language drop down menu.
flag If multiple locales are specified the flag to place next to the label when accessing the language drop down menu.

Example translation files are provided as part of the GUI package installation and may be found in:

/usr/share/n2sip/n2ivr-gui/htdocs/locale/en.json

Each translation file groups elements into disparate components, screens and concepts. An excerpt of en.json is as follows:

{
    "N-Squared IVR"         : null,
    "admin"                 : {
        "announcement_id_groups"     : {
            "create_group": null,
            "tab_header"  : null,
            "table"       : {
                "actions_header"            : null,
                "group_name_header"         : null,
                "max_announcement_id_header": null,
                "min_announcement_id_header": null,
                "no_announcement_id_groups" : null
            }
        },
        "database_locking"           : {
            "tab_header": null,
            "table"     : {
                "actions_header"       : null,
                "is_locked_header"     : null,
                "lock_holder_header"   : null,
                "lock_name_header"     : null,
                "lock_timestamp_header": null,
                "no_database_locks"    : null
            }
        },
        "ivr_platform_administration": {
            "title": null
        },
    ...

By default all example translation files will use null for translation values; this causes the N2IVR GUI to fallback to its default English translation values.

It is recommended that any modifications to the translation files should be made outside of the N2IVR installation directory as any future package installations may replace or delete modified translation files.

The high level procedure for using external translation files is as follows:

In this example we will use /var/lib/n2ivr/locale for storage of locale files.

Create the directory:

mkdir -p /var/lib/n2ivr/locale

Set permissions, noting that the target Apache user will differ depending on Linux distribution:

chown -R apache:apache /var/lib/n2ivr

Copy example files to the new target directory; modifying them as required:

cp /usr/share/n2sip/n2ivr-gui/htdocs/locale/*.json /var/lib/n2ivr/locale/

Editing the deployed Apache configuration uncomment the following lines to enable an override route to the newly copied locale files:

# Alias /n2ivr/locale/ /var/lib/n2ivr/locale/

#
# Directory override for locale files not stored in standard installation directories.
#
# <Directory /var/lib/n2ivr/locale>
#     Options -Indexes +FollowSymLinks +MultiViews
#     AllowOverride All
#     Order allow,deny
#     allow from all
#     Require all granted
#     # See Vaulted V-26396.
#     <LimitExcept POST GET PUT DELETE>
#         Deny from all
#     </LimitExcept>
# </Directory>

Auditing

Auditing is available for all N2IVR GUI actions. This is configured in the N2IVR GUI configuration section:

        <config>
            ...
            <auditing is_enabled="1" logfile="/var/log/n2ivr/audit.log"/>
        </config>

To enable auditing, set is_enabled to 1, and use logfile to specify the full path to the audit log file. Note that this directory must be writable by the web server.

To disable auditing, set is_enabled to 0.

Auditing is disabled by default.

Database Connectivity

SQLite

When using SQLite, the SQLite database connectivity must be enabled. To do so, replace the PostgreSQL <database> connection definition with the following SQLite connection definition:

        <database connect="dbi:SQLite:dbname=" username="" password="">
            <dbh_attributes>
                <attribute name="sqlite_string_mode" value="5"/>
            </dbh_attributes>
            <post_connect_commands>
                <command>PRAGMA foreign_keys = ON</command>
                <command>PRAGMA journal_mode = WAL</command>
                <command>ATTACH DATABASE '/var/lib/n2ivr/db/n2ivr.db' AS n2ivr</command>
                <command>ATTACH DATABASE '/var/lib/n2ivr/db/n2ivr_snapshot.db' AS n2ivr_snapshot</command>
            </post_connect_commands>
        </database>

Update the path (/var/lib/n2ivr/db/) to be correct, such that it matches the path where the SQLite .db files are installed.

When using SQLite:

PostgreSQL

When using PostgreSQL, the appropriate DBD driver for postgres must be configured with the correct host, port, username and password:

        <database connect="dbi:Pg:dbname=n2in;host=127.0.0.1" username="n2ivr_web" password="n2ivr_web"/>

Update the DBD connection string, username and password as appropriate.

When using PostgreSQL, database replication is preferred.

Database or File Based Replication

The N2IVR GUI supports audio configuration to service nodes via PostgreSQL database replication, or rsync. By default database replication is enabled and will be used. However if file-based replication should be used (e.g. because SQLite is being used instead of PostgreSQL), 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
                local="/usr/bin/rsync"
                remote="/usr/bin/rsync"
                logfile="/tmp/n2ivr_disk_synchronisation.log"
                ssh_params="-o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null -o LogLevel=ERROR"
            />
        </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.

The ssh_params attribute can be optionally defined to specify additional SSH parameters for connecting to remote systems. These parameters may enable resolving and suppressing connection errors and warnings.

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 &quot;${modes[@]}&quot;; do /usr/bin/ffmpeg -i &quot;$input_file&quot; -f amr -c:a amr_nb -ar 8000 -y -ac 1 -b:a $mode &quot;$output_file.$mode&quot;; audio_files+=(&quot;$output_file.$mode&quot;); done; /usr/bin/tar -cf &quot;$output_file&quot; &quot;${audio_files[@]}&quot;; /usr/bin/rm &quot;${audio_files[@]}&quot;"/>
            <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 &quot;${modes[@]}&quot;; do /usr/bin/ffmpeg -i &quot;$input_file&quot; -f amr -c:a amr_wb -ar 16000 -y -ac 1 -b:a $mode &quot;$output_file.$mode&quot;; audio_files+=(&quot;$output_file.$mode&quot;); done; /usr/bin/tar -cf &quot;$output_file&quot; &quot;${audio_files[@]}&quot;; /usr/bin/rm &quot;${audio_files[@]}&quot;"/>
        </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.

For PostgreSQL installations, connect to the installed n2in database using the n2ivr_owner user:

psql -h localhost -U n2ivr_owner n2in -W

For SQLite installations, as root load the database file:

cd /path/to/n2ivr/db
sqlite3 n2ivr.db

Disabling the “Working” Set

Note that disabling the “working” set is not available when using SQLite or if using file-based sync.

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 RTP 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.

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 language (language_name, creation_user, change_user) VALUES ('<language>', 'initial creation', 'initial creation');

Where <language> is the language name.

Available language are:

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 audio_file_encoding (audio_file_encoding_name, file_extension, creation_user, change_user) VALUES ('A-Law', 'al', 'initial creation', 'initial creation');
INSERT INTO audio_file_encoding (audio_file_encoding_name, file_extension, creation_user, change_user) VALUES ('μ-Law', 'ul', 'initial creation', 'initial creation');
INSERT INTO audio_file_encoding (audio_file_encoding_name, file_extension, creation_user, change_user) VALUES ('AMR-NB', 'amr', 'initial creation', 'initial creation');
INSERT INTO audio_file_encoding (audio_file_encoding_name, file_extension, creation_user, change_user) VALUES ('AMR-WB', 'awb', 'initial creation', 'initial creation');

-- These are valid encodings for source files.
INSERT INTO audio_file_encoding (audio_file_encoding_name, file_extension, creation_user, change_user) VALUES ('MP3', 'mp3', 'initial creation', 'initial creation');
INSERT INTO audio_file_encoding (audio_file_encoding_name, file_extension, creation_user, change_user) VALUES ('OGG', 'ogg', 'initial creation', 'initial creation');
INSERT INTO audio_file_encoding (audio_file_encoding_name, file_extension, creation_user, change_user) VALUES ('FLAC', 'flac', 'initial creation', 'initial creation');
INSERT INTO audio_file_encoding (audio_file_encoding_name, file_extension, creation_user, change_user) VALUES ('RAW', 'raw', 'initial creation', 'initial creation');
INSERT INTO audio_file_encoding (audio_file_encoding_name, file_extension, creation_user, change_user) VALUES ('WAV', 'wav', 'initial creation', 'initial creation');