Installation

This page describes how to install the XiVO CC.

It describes the installation with the debian package of the whole XiVO CC.

Note

As a reference, the manual installation page is here Manual configuration and installation.

Warning

  • If you configure HA on XiVO, you have to re-configure postgres to accept connection of XiVO CC - see PostgreSQL configuration section
  • By default XiVO CC installation will pre-empt network subnets 172.17.0.0/16 and 172.18.0.0/16 If this subnet is already used, some manual steps will be needed to be able to install XiVO CC. These steps are not described here.

Overview

The following components will be installed :

  • XuC : outsourced CTI server providing telephony events, statistics and commands through a WebSocket
  • XuC Management : supervision web pages based on the XuC
  • Pack Reporting : statistic summaries stored in a PostgreSQL database
  • Totem Support : near-real time statistics based on ElasticSearch
  • SpagoBI : BI suite with default statistic reports based on the Pack Reporting
  • Recording Server : web server allowing to search recorded conversations
  • Xuc Rights Management : permission provider used by XuC and Recording Server to manage the user rights

Prerequisites

We will assume your XiVO CC server meets the following requirements:

You MUST have a XiVO PBX server to work with XiVO CC that is:

  • having OpenSSH PermitRootLogin set to yes (you could revert to no after installation of XivoCC);
  • installed in a compatible version (basically the two components XiVO and XiVO CC have to be in the same version).
  • reachable on the network (ping and ssh between XiVO CC and XiVO PBX must be possible).
  • setup (wizard must be passed) with users, queues and agents, you must be able to place and answer calls.

A part of the XiVO CC install aims to reconfigure XiVO PBX. You can start installing XiVO CC without XiVO PBX ready at first (or installing both in parallel). But if you do so you will need to do the reconfiguration part later, once XiVO PBX is properly set up (XiVO CC cannot work without it). See more details below.

For the rest of this page, we will make the following assumptions :

  • the XiVO PBX has the IP 192.168.0.1
  • some data (incoming calls, internal calls etc.) might be available on XiVO (otherwise, you will not see anything in the check-list below).
  • the XiVO CC server has the IP 192.168.0.2

SSH Key configuration

It is mandatory that your XiVO CC can access XiVO PBX through ssh using an ssh key. The ssh key name or type does not matter, use whichever you like. I’ll use xivocc_rsa for this example. On XiVO CC, you can generate it this way :

ssh-keygen -t rsa -P "" -f ~/.ssh/xivocc_rsa

You can then use ssh-copy-id once to configure that key as a way to connect to XiVO PBX.

ssh-copy-id -i ~/.ssh/xivocc_rsa root@192.168.0.1

Note that ssh-copy-id requires the user prompt, PermitRootLogin on the XiVO PBX VM and (obviously) the XiVO PBX root password.

Alternatively, if you do have a ssh key on XiVO PBX, you can manually register XiVO PBX among XiVO CC’s known hosts. This does not requires user prompt. Run on XiVO CC :

ssh-keyscan 192.168.0.1 | grep -P "^192.168.0.1" >> /root/.ssh/known_hosts

You know it’s working well when the following commands executes on XiVO CC with neither errors nor cli prompt :

ssh root@192.168.0.1 'echo "hello $(uname -n)"' | cat

Architecture & Flows

This diagram is very important and shows the architecture between the different components inside XiVO CC and also interactions with XiVO PBX components.

../../../_images/xivocc_architecture.png

XiVO PBX Restrictions and Limitations

XiVO PBX enables a wide range of configuration, XiVO-CC is tested and validated with a number of restriction concerning configurations of XiVO PBX:

General Configuration

  • Do not activate Contexts Separation in xivo-ctid Configuration
  • Users deactivation is not supported

Queue Configuration

  • Queue ringing strategy should not be Ring All
  • Do not use pause on one queue or a subset of queues status, only pause or ready on all queues
  • Do not activate Call a member already on (Asterisk ringinuse) on xivo queue advanced configuration
  • When creating a new queue, this queue will not appear immediately in CCAgent and CCManager until the agent or the manager is not relogged to these applications accordingly.
  • When deleting an existing queue, this queue will still appear in CCAgent and CCManager until the Xuc server is not restarted.

User And Agent Configuration

  • All users and queues have to be in the same context
  • Agent and Supervisors profiles should use the same Presence Group
  • Agents and Phones should be in the same context for mobile agents
  • Agents must not have a password in XiVO agent configuration page
  • All users must have the supervision on the XiVO (IPBX-Users-Edit-Services-Enable supervision checked)
  • When and agent is disassociated from its user, xuc server has to be restarted.
  • We strongly advise to not delete any user or agent to keep reporting available for them. Even so when an agent is deleted, xuc server has to be restarted,

Install process overview

Note

If your server needs a proxy to access Internet, configure the proxy for apt, wget and curl as documented in Proxy Configuration.

The install process consists of four parts:

  1. The first part is to manually run the xivocc_install.sh script to install the dependencies (ntp, docker, docker-compose…) and which will trigger the XiVO CC installation : Install from repository
  2. The second part is to execute the after-install steps : After-install steps
  3. The third part is to install the extra package for the chat : Chat Backend
  4. The fourth part is to install the extra package for the recording : Recording

Install from repository

The installation and configuration of XiVO CC (with its XiVO PBX part) is handled by the xivocc-installer package which is available in the repository.

Configuration setup

For regular install

Beforehand, check that you know the following information, as they will be prompted :

  • XiVO PBX’s IP address (XIVO_HOST)
  • XiVO CC DNS name or IP address (the one visible by XiVO PBX) (XUC_HOST)
  • Elasticsearch’s IP address (by default XiVO CC’s IP) (ELASTICSEARCH_HOST)
  • Number of weeks to keep statistics (WEEKS_TO_KEEP)
  • Number of weeks to keep recordings (beware of disk space) (RECORDING_WEEKS_TO_KEEP)

The number of weeks to keep statistics must be higher than the number of weeks to keep recordings. Recording purging is based on the statistic data, so the statistic data must not be removed before purging recordings.

For silent install

You can pass those parameters in the custom.env on your XiVO CC if you don’t want to be prompted :

mkdir -p /etc/docker/compose
echo "XIVO_HOST=<IP ADDRESS OF THE XIVO>
XUC_HOST=<CC FQDN>
ELASTICSEARCH_HOST=<CC FQDN>
CONFIGURE_REPLY=true
WEEKS_TO_KEEP=<Number of weeks to keep>
RECORDING_WEEKS_TO_KEEP=<Number of recording weeks to keep>
RESTART_REPLY=true" > /etc/docker/compose/custom.env

CONFIGURE_REPLY tells whether or not to connect on the XiVO PBX and finish its reconfiguration during the CC install.

RESTART_REPLY tells whether or not to restart the XiVO PBX services after the reconfiguration.

According your XiVO PBX is ready (wizard is passed), set CONFIGURE_REPLY to true. If you’re doing the installations in parallel, set both variables to false and see XiVO CC reconfigures XiVO PBX after the silent install.

Download installer script

Once you have your Debian Bullseye properly installed on your XiVO CC VM, download the XiVO CC installation script and make it executable:

wget http://mirror.xivo.solutions/xivocc_install.sh
chmod +x xivocc_install.sh

Launch installation

./xivocc_install.sh -a 2023.05-latest

Launch installation in silent mode using the flag -s:

./xivocc_install.sh -s -a 2023.05-latest;

If you chose not to configure XiVO PBX during the installation, you have one more step to run here XiVO CC reconfigures XiVO PBX

XiVO CC reconfigures XiVO PBX

If you chose to reconfigure XiVO PBX with XiVO CC later, this is the additional step you have to do. First verify the following points :

You must then run this on XiVO CC :

configure-pbx

After-install steps

Configure ntp server

The XiVO CC server and the XiVO PBX server must be synchronized to the same NTP source.

Recomended configuration : you should configure the NTP server of the XiVO CC server towards the XiVO PBX. In our example it means to add the following line in the file /etc/ntp.conf:

server 192.168.0.1 iburst

Adjust xuc memory

Xuc memory must be increased on these installations:

Condition XUC Xmx
Default Required
> 50 agents or > 500 users 2048m 4096m
  1. Set new variable in the /etc/docker/compose/custom.env file:
JAVA_OPTS_XUC=-Xms512m -Xmx4g
  1. Use the variable in the /etc/docker/compose/docker-compose.yml file:
 xuc:
   ...
   environment:
   - JAVA_OPTS=${JAVA_OPTS_XUC}

Adjust Elasticsearch memory

By default on XIVO CC elasticsearch is started with 1.5Gb for the JVM. This may need to be adjusted depending on your setup (mostly depending on the number of calls per day).

See Elasticsearch memory management on how to do it.

Launch the services

Note

Please, ensure your server date is correct before starting. If system date differs too much from correct date, you may get an authentication error preventing download of the docker images.

After a successful installation, start docker containers using the installed xivocc-dcomp script:

xivocc-dcomp up -d

To restart XiVO services, on XiVO PBX server run

xivo-service restart all

Reinstallation

To reinstall the package, it is required to run apt-get purge xivocc-installer then apt-get install xivocc-installer. This will re-run the configuration of the package, download the docker compose template and setup XiVO PBX.

Purging the package will also remove the xuc and stats users from the XiVO PBX database.

Known Issues

To avoid uninstallation problems:
  • please use the following command to uninstall apt-get purge xivocc-installer
  • if the process is aborted, it will break the installation. Then run apt-get purge and apt-get install again

Checking Installed Version

Version of the running docker containers can be displayed by typing (see Show containers and images versions for other commands):

xivocc-dcomp version

Component version can also be found in the log files and on the web pages for web components.

Using XivoCC

The various applications are available on the following addresses:

../../../_images/fingerboard.png

Chat Backend

Since Electra version, you MUST install and configure the chat backend to have the Chat feature working properly.

Installation type:

  • UC Addon: the chat backend package must be installed on the XiVO PBX with the UC Addon.
  • CC/UC mono-server: the chat backend package must be installed on your CC/UC server.
  • CC/UC multi-server: the chat backend package must be installed on the server which hosts the xuc. You will be asked to give the IP Address of the server hosting the pgxivocc.

Warning

Installing the Chat backend will configure a linux user on the host with UID 2000. Therefore you should check that no user with UID 2000 (you can do it with command id 2000) is existing on the host before installing the Chat backend.

Warning

XiVO CC containers will be recreated. Therefore you must not install the chat backend before initialization of all databases in pgxivocc was completed. DB replication to the stats database must be also completed before installing the chat backend.

Chat Backend Installation

  1. Install the xivo-chat-backend package on your XIVO CC (on the server hosting the xuc server):

    apt-get install xivo-chat-backend

  2. When done, run the configuration script:

    /var/lib/xivo-chat-backend/scripts/xivo-chat-backend-initconfig.sh

    Note

    This will configure

    • the database
    • the chat backend (currently mattermost server)
    • and the link between xuc and mattermost services

Post Installation

User Configuration

You should configure users and their rights in the Configuration manager http://<XiVO IP Address>/configmgt/ (default user avencall/superpass).

Warning

If you change the cti login username in xivo configuration, user has to be recreated with apropriate rights in configuration manager.

SpagoBI

To configure SpagoBI, go to http://192.168.0.2/SpagoBI (by default login: biadmin, password: biadmin).

Update default language

  1. Go to “⚙ Resources” > “Configuration management”
  2. In the “Select Category” field, chose “LANGUAGE_SUPPORTED”
  3. change value of the label “SPAGOBI.LANGUAGE_SUPPORTED.LANGUAGE.default” in your language : fr,FR , en,US , …

Upload Statistics Reports

  1. Download the sample reports from https://gitlab.com/xivocc/sample_reports/-/raw/master/spagobi/samples_from_borealis_v23.zip For Contact Center reporting
  2. Import zip file in SpagoBI:
  1. Goto “Repository Management” -> “Import/Export”
  2. Click on “Browse/Choose your file” and choose the previous *_vxx.zip downloaded file
  3. Click on “Import” icon
  4. Click next with default options until you are asked to override metadata, set Yes as shown in screen below
../../../_images/reportsoverride.png

You can now browse the sample reports in Document->Rapports->Exemples.

../../../_images/reportsample.png

Use the database status report to check if replication and reporting generation is working :

../../../_images/datastatus.png

Totem Panels

You have to manually import demo dashboards in Kibana, see Totem Panels for required steps.

Post Installation Check List

Warning

Make sure to have few calls made in your XiVO, despite you will not see anything in totem or spagobi.

Recording

This feature needs additional configuration steps on XiVO PBX, see:

  1. Recording,
  2. and (optionally) Recording filtering configuration.