UC Assistant: Real time status for internal users is now displayed in the call history
Switchboard in Desktop Application: Switchboard application is now available with the Desktop Application
Unique Account: Unique Account users are now compatible with:
call groups,
group pickups,
and boss/secretary filters
Directory Research: Enhancements to have more relevant results ordering
Web Interface: Improve labels with filtering and better display for long lists
Mobile Application: Improvements on the integration in the workflow
See Jabbah page for the complete list of New Features and Behavior Changes.
Deprecations
End of Support for LTS Deneb (2019.12).
Asterisk:
chan_sip is deprecated and will be removed in next LTS
chan_sccp is deprectaed and will be removed in next LTS
XiVO solutions developed by Wisper group is a suite of PBX applications based on several free existing components including Asterisk
and our own developments. This powerful and scalable solution offers a set of features for corporate telephony and call centers to power their business.
You may also have a look at our development blog for technical news about the solution
XiVO solutions is a suite of PBX applications developed by Wisper group, based on several free existing components
including AsteriskPlayAkka and Scala. It provides a solution for enterprises who wish use modern communication services
(IPBX, Unified Messaging, …) api and application to businesses.
It gives especially access to outsourced statistics, real-time supervision screens,
third-party CTI integration and recording facilities.
XiVO solutions is free software. Most of its distinctive components, and XiVO solutions as a whole, are distributed
under the GPLv3 license and or the LGPLv3 license..
XiVO solutions documentation is also available as a downloadable HTML, EPUB or PDF file.
See the downloads page
for a list of available files or use the menu on the lower right.
XiVO was created in 2005 by Sylvain Boily (Proformatique SARL).
The XiVO mark was owned by Avencall SAS after a merge between Proformatique SARL and Avencall SARL
in 2010.
Since 2020, Avencall has been acquired by Wisper group.
The XiVO core team now works for Wisper in Lyon (France) and Prague (Czech Republic)
XiVO 1.2 was released on February 3, 2012.
XiVO 13.07 was the last version with Asterisk 1.8.21.0
XiVO 13.08 includes Asterisk 11.3.0 in May 2013
XiVO 13.25 is running under Wheezy in December 2013
XiVO 14.02 is now called XiVO Five to celebrate the editor 5th year
XiVO 15.13 runs Asterisk 13 in July 2015
XiVO 15.20 is running under Jessie in January 2016
XiVO 2016.02 starts the new versioning system including XiVO-CC and XiVO-UC modules in October 2016
XiVO solutions 2016.04 includes new XiVO assistant, web edition, mobile edition and Desktop edition in December 2016
XiVO solutions 2017.03 in April 2017 is the first Long Term Support version known as Five.The main goal is to offer a stable version every 6 months even if the team is still doing small and agile iterations of 3 weeks.
XiVO solutions 2017.11 in October 2017, second LTS release known as Polaris
XiVO solutions 2018.05 in April 2018, third LTS release known as Aldebaran,
XiVO solutions 2019.16 in October 2018, 4th LTS release known as Borealis,
XiVO solutions 2019.05 in April 2019, 5th LTS release known as Callisto,
XiVO solutions 2019.12 in October 2019, 6th LTS release known as Deneb,
XiVO solutions 2020.07 in April 2020, 7th LTS release known as Electra that set Five version as out of support,
XiVO solutions 2020.18 in October 2020, 8th LTS release known as Freya that set Polaris version as out of support,
XiVO solutions 2021.07 in April 2021, 9th LTS release known as Gaia running on Asterisk 18 that set Aldebaran version as out of support,
XiVO solutions 2021.15 in October 2021, 10th LTS release known as Helios that set Borealis version as out of support,
XiVO solutions 2022.05 in April 2022, 11th LTS release Known as Izar that set Callisto version as out of support,
XiVO solutions 2022.10 in October 2022, 12th LTS release Known as Jabbah that set Deneb version as out of support,
Next release is on the way, will be called XiVO K… and will be available in April 2023.
XiVO architecture was redesigned to be GDPR compliant by being “privacy by design”, which is the GDPR DNA.
We have in this respect refined all the features since Polaris to be 100% compliant.
This section will show you how to create a user with a SIP line. This simple use case covers what a lot of people need to start using a phone.
You can use these steps for configuring a phone (e.g a softphone, an Analog-to-Digital switch or a SIP phone).
When logged in, you will see a page with all the status information about your system.
This page helps you monitor the health of your system and gives you information about your network. Please note the IP address of your server,
you will need this information later on when you will configure your device (e.g. phone)
We now have the form that will allow us to create a new user. The three most important fields are ‘First name’, ‘Last name’ and ‘Language’.
Fill in the fields and click on Save at the bottom. For our example, we will create a used called ‘Alice Wonderland’.
Please refer to the section Troubleshooting if ever you have errors during the installation.
There are two official ways to install XiVO:
using the official ISO image
using a minimal Debian installation and the XiVO installation script
XiVO can be installed on both virtual (QEMU/KVM, VirtualBox, …) and physical machines. That said, since
Asterisk is sensitive to timing issues, you might get better results by installing XiVO on real
hardware.
Warning
By default XiVO installation will pre-empt network subnets 172.17.0.0/16 and 172.18.1.0/24.
If these subnets are already used, some manual steps will be needed to be able to install XiVO.
These steps are not described here.
Boot from the ISO image, select Install and follow the instructions. You must select locale
en_US.UTF-8.
At the end of the installation, you can continue by running the configuration
wizard.
During the installation of Debian, only a proxy that supports proxying http/https requests may eventually be entered.
Otherwise GPG key of XiVO repository will not be installed and must be added manually:
XiVO can be installed directly over a 64-bitDebian 11 (Bullseye). When doing so, you are strongly
advised to start with a clean and minimal installation of Debian Bullseye.
The installation script can also be used to install an archive version of
XiVO (14.18 or later only). For example, if you want to install XiVO 2020.18-latest:
./xivo_install.sh-a2020.18-latest
When installing an archive version, note that:
versions 14.18 to 15.19 of XiVO can only be installed on a Debian 7 (wheezy) system
the 64-bit versions of XiVO are only available starting from 15.16
You may also install development versions of XiVO with this script. These versions may be unstable
and should not be used on a production server. Please refer to the usage of the script:
After the system installation, you must go through the wizard before being able to use your XiVO.
Open your browser and enter your server’s IP address in the navigation bar. (For example:
http://192.168.1.10)
Finally, you can validate your configuration by clicking on the Validate button.
Note that if you want to change one of the settings you can go backwards in the wizard by clicking
on the Previous button.
Warning
This is the last time the root password will be displayed. Take care to note it.
Congratulations, you now have a fully functional XiVO server.
During the wizard you can choose to apply a default configuration for France : see Wizard configuration step.
This option introduce a set of default parameters that will be useful particularly for a XiVO PBX installed in France.
The default parameters configured are listed in the sections below.
A set of default outgoing call rules according to the French numbering plan is set up by default.
In Services ‣ IPBX ‣ Call management ‣ Outgoing calls two outgoing call rules are defined:
sortants-france: pattern for french numbering plan numbers,
urgences-france: pattern for french emergency numbers.
Note
For these outgoing call rules, a ‘void’ cutomized trunk named ‘Local/template_a_changer’ is defined. This one must be deleted or modified according to your configuration.
Also, a set of right call is predefined according to the set of outgoing call rules.
In Services ‣ IPBX ‣ Call management ‣ Call permissions you will find the following preconfigured right call
group:
Configured by default if you checked the Apply default onfiguration for France at the wizard time
(see Wizard configuration step).
When you call internally another phone of the system you would like your phone to display the name
of the called person (instead of the dialed number only).
To achieve this you must change the following SIP options:
Configured by default if you checked the Apply default onfiguration for France at the wizard time
(see Wizard configuration step).
You should also select default codecs. It obviously depends on the telco links, the country, the phones, the usage, etc.
Here is a typical example for Europe (the main goal in this example is to select only G.711 A-Law instead of both G.711 A-Law and G.711 µ-Law by default):
For your Digium card to work properly you must load the appropriate DAHDI kernel module.
This is done via the file /etc/dahdi/modules and this page will guide you through its configuration.
This command gives the card name detected and, more importantly, the DAHDI kernel module
needed for this card. In the above example you can see that two cards are detected in the system:
a Digium B410P which needs the wcb4xxp module
and a Digium TE205P which needs the wct4xxp module
Now that we know the modules we need, we can create our configuration file:
Create the file /etc/dahdi/modules:
touch /etc/dahdi/modules
Fill it with the modules name you found with the dahdi_hardware command (one module name per line).
In our example, your /etc/dahdi/modules file should contain the following lines:
wcb4xxp
wct4xxp
Note
In the /usr/share/dahdi/modules.sample file you can find all the modules supported in your
XiVO version.
If you have an hardware echo-canceller module you have to install its firmware.
You first need to know which firmware you have to install.
The simplest way is to restart dahdi and then to lookup in the dmesg which
firmware does DAHDI request at startup:
xivo-service restart
dmesg |grep firmware
[5461540.738209] wct4xxp 0000:01:0e.0: firmware: agent aborted loading dahdi-fw-oct6114-064.bin (not found?)
[5461540.738310] wct4xxp 0000:01:0e.0: VPM450: firmware dahdi-fw-oct6114-064.bin not available from userspace
In the example above you can see that the module wct4xxp requested the dahdi-fw-oct6114-064.bin
firmware file but did not found it.
But you now know that you need the dahdi-fw-oct6114-064.bin firmware.
When you know which firmware you need you can install it with xivo-fetchfw utility.
Use xivo-fetchfw to find the name of the package. You can search for digium
occurrences in the available packages:
xivo-fetchfwsearchdigium
Find the package name which matches the firmware file you need. In our example, we need the
dahdi-fw-oct6114-064.bin file which is supplied by the package named digium-oct6114-064:
You will find below 3 configurations that we recommend for BRI lines.
These configurations were tested on different type of french BRI lines with success.
XiVO does not support hardware echocanceller on the TDM400 card. Users of TDM400 card willing to
setup an echocanceller will have to use a software echocanceller like OSLEC.
Depending on the codec you want to transcode, you can modify the mode parameter which can take the following value:
mode = mixed : this the default value which activates transcoding for 92 channels
in G.729a or G.723.1 (5.3 Kbit and 6.3 Kbit)
mode = g729 : this option activates transcoding for 120 channels in G.729a
mode = g723 : this option activates transcoding for 92 channels in G.723.1 (5.3 Kbit et 6.3 Kbit)
Create the file /etc/modprobe.d/xivo-transcode.conf:
touch/etc/modprobe.d/xivo-transcode.conf
And insert the following lines:
optionswctc4xxpmode=g729
Apply the configuration by restarting the services:
xivo-servicerestart
Verify that the card is correctly seen by asterisk with the transcodershow CLI command
- this command should show the encoders/decoders registered by the TC400 card:
spannum : corresponds to the span number. It starts to 1 and has to be incremented by 1 at each new span.
This number MUST be unique.
timing : describes the how this span will be considered regarding the synchronization :
0 : do not use this span as a synchronization source,
1 : use this span as the primary synchronization source,
2 : use this span as the secondary synchronization source etc.
LBO : 0 (not used)
framing : correct values are ccs or cas.
For ISDN lines, ccs is used.
coding : correct values are hdb3 or ami.
For example, hdb3 is used for an E1 (PRI) link, whereas ami is used for T0 (french BRI) link.
crc4 : this is a framing option for PRI lines.
For example it is rarely use in France.
Note that the dahdi_genconf command should usually give you the correct parameters (if you correctly set the cards
jumper). All these information should be checked with your operator.
This page describes how to install XiVO UC on the XiVO PBX server and how to use it.
By XiVO UC we mean a subset of XiVO CC application, namely the Web and Desktop Assistant.
Your XiVO PBX server MUST meet the following requirements:
OS : Debian 11 (Bullseye), 64 bits
4 GB of RAM
4-core CPU
20 GB of free disk space
you have a XiVO PBX installed in a compatible version (basically the two components XiVO and XiVO UC have to be
in the same version).
the XiVO PBXis setup (wizard must be passed) with users, queues and agents, you must be able to place and answer calls.
Warning
By default XiVO-UC installation will pre-empt network subnets 172.17.0.0/16 and 172.18.0.0/24.
If these subnets are already used, some manual steps will be needed to be able to install XiVO-UC.
These steps are not described here.
After installing the XiVO UC the XiVO PBX Administration will be only available at https://XiVO_PBX_IP/admin
The installation and configuration of XiVO UC is handled by the xivouc-installer script provided with XiVO.
You will be asked few questions during the process:
the XiVO PBX IP address,
and whether or not you want to restart XiVO PBX by the installer or later
The xivouc-installer script will install packages xivouc and xivocc-docker-components.
These packages contain these docker compose files:
/etc/docker/compose/docker-xivocc.yml adds UC components which are managed by xivocc-dcomp script
/etc/docker/xivo/docker-xivo.override.yml adds DB Replic to XiVO services
/etc/docker/xivo/docker-xivo-uc.override.yml which adds the UC env variable to nginx container so it is started in UC-mode.
If you choose to restart XiVO PBX later, please do so as soon as possible to apply the modifications made by the installer.
Until then, the XiVO UC will not be able to connect correctly to the database.
To restart XiVO services manually, run
xivo-servicerestartall
XiVO will start with DB Replic and Nginx container configured for XiVO UC.
After a successful installation, start docker containers using the installed xivocc-dcomp script:
xivocc-dcompup-d
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.
Switch the sources to the new XiVO PBX LTS version with xivo-dist, for example, to switch to Gaia LTS version:
xivo-distxivo-gaia
Read carefully theRelease Notes starting from your current version to the version you target (read even more
carefully the New features and Behavior changes between LTS)
Check the specific instructions and manual steps from your current LTS to your targetted LTS and all intermediate LTS: see Manual steps for LTS upgrade
Upgrade to latest Bugfix release of an LTS version
After the release of an LTSversion (e.g. Freya) we may backport some bugfixes in this version.
We will then create a subversion (e.g. Freya .04) shipping these bugfixes.
These bugfix version does not contain any behavior change.
To upgrade to the latest subversion of your current installed version you need to:
Read carefully theRelease Notes starting from your installed version (e.g. Freya.00) to the latest bugfix release (e.g. Freya.04).
Verify that the debian sources list corresponds to your installed LTS or refix it, for example for Freya:
Before starting the services after restoring the backup on the XiVO amd64, you should ensure
that there won’t be a conflict between the two machines, e.g. two DHCP servers on the same broadcast
domain, or both XiVO fighting over the same SIP trunk register. You can disable the XiVO i386 by
running:
xivo-servicestop
But be aware the XiVO i386 will be enabled again after you reboot it.
Before integrating a new version of asterisk in XiVO PBX, we first build it and deliver it in the xivo-VERSION-candidate distribution of our
repository.
The goal is to make it available for specific cases (e.g. urgent bugfixes) before shipping it as the default version.
This page explains how to upgrade/downgrade to/from this candidate version.
Warning
This is a specific procedure. You should know what you are doing.
And downgrade the version by giving the version in the oldstable distribution of the repository.
With the example below (do the same with asterisk-dbg if applicable):
Since 2017.03.02, xivo-recording and call-recording-filtering packages are deprecated and are replaced by package xivocc-recording. This page describe the upgrade procedure
(for feature description, see here).
xivo-recording and call-recording-filtering packages are deprecated and they were uninstalled, but not purged from your XiVO PBX during the upgrade.
You now have to follow this manual procedure:
Note
This has to be done on XiVO PBX
Configure xivocc-recording package (when ask, take care to enter same IP for Recording server and same XiVO PBX name as in previous configuration):
xivocc-recording-config
Update all the different locations where the old xivo-incall-recording or xivo-outcall-recording subroutines
were called.
If you made specific recording subroutines you should also compare files /etc/asterisk/extensions_extra.d/xivo-recording.conf and
/etc/asterisk/extensions_extra.d/xivocc-recording.conf and transfer all custom changes to the new xivocc-recording.conf.
If there are some audio files in the failed directory of previous installation you should move them:
When you’re done, test that recording still works. Test that files are recorded, correctly sent to Recording server (see
/var/log/xivocc-recording/replication.log), correctly displayed in the Recording server interface,
If it works correctly, you should purge deprecated packages with (take care, it will remove the package and all associated
configuration files):
Debian was upgraded to Debian 9 (stretch) in XiVO 2018.14 release.
Warning
Upgrade from versions XiVO 15.19 or earlier are not supported.
You MUST first upgrade to at least XiVO 15.20 or, more recommended, to XiVO Five
before upgrading to XiVO Borealis.
Warning
Docker storage driver changed from aufs to overlay2. To not suffer data loss you must follow a
manual procedure which is not documented yet. Therefore:
XiVO PBX / UC / CC is not installable or upgradable on XFS partition created withoutftype=1option.
If the partition is XFS, you MUST check if the option is enabled with the xfs_info command.
Upgrade for XiVO CC to Debian 9 is currently not supported.
It is not possible to upgrade from XiVO 15.19 or earlier. You first need to upgrade to XiVO Five.
Make sure you have sufficient space for the upgrade. You should have more than 2GiB available in the filesystem that holds the /var and / directories.
Note that the upgrade will take longer than usual because of all the system upgrade.
You MUST deactivate all non-xivo apt sources list:
in directory /etc/apt/sources.list.d/ you should only have the files xivo-dist.list and (from Aldebaran) docker.list.
you MUST suffix all other files with .save to deactivate them.
You MUST check the Debian sources list are correct: the file /etc/apt/sources.list must contain the following and only the following:
debhttp://ftp.fr.debian.org/debian/jessiemaindeb-srchttp://ftp.fr.debian.org/debian/jessiemaindebhttp://security.debian.org/jessie/updatesmaindeb-srchttp://security.debian.org/jessie/updatesmain# jessie-updates, previously known as 'volatile'debhttp://ftp.fr.debian.org/debian/jessie-updatesmaindeb-srchttp://ftp.fr.debian.org/debian/jessie-updatesmain
You may want to clean your system before upgrading:
Remove package that were automatically installed and are not needed anymore:
apt-getautoremove--purge
Purge removed packages. You can see the list of packages in this state by running dpkg-l|awk'/^rc/{print$2}' and purge all of them with:
After having check your network configuration and the grub configuration, you MUSTreboot your system. It is necessary for the upgrade to the Linux kernel to be effective.
Check that customization to your configuration files is still effective.
During the upgrade, new version of configuration files are going to be installed, and these might
override your local customization. For example, the vim package provides a new /etc/vim/vimrc
file. If you have customized this file, after the upgrade you’ll have both a /etc/vim/vimrc and
/etc/vim/vimrc.dpkg-old file, the former containing the new version of the file shipped by the vim
package while the later is your customized version. You should merge back your customization into
the new file, then delete the .dpkg-old file.
You can see a list of affected files by running find/etc-name'*.dpkg-old'. If some files
shows up that you didn’t modify by yourself, you can ignore them.
Purge removed packages. You can see the list of packages in this state by running dpkg-l|awk'/^rc/{print$2}' and purge all of them with:
Here’s a non-exhaustive list of changes that comes with XiVO on Debian 9:
Network utility: the tools from the net-tools package are no longer part of new installations by default. They are replaced by the iproute2 toolset.
For a complete summary of the net-tools commands with their iproute2 equivalent
see the Official Debian 9 Release notes related chapter.
Here are 4 examples:
Instead of arp, use ipn (short for ipneighbor)
Instead of ifconfig, use ipa (short for ipaddr)
Instead of netstat, use ss
Instead of route, use ipr (short for iproute)
Docker recommended storage driver is overlay2 and the usage of aufs storage driver was deprecated in Debian 9 (stretch).
Thus we recommend to use overlay2 as storage driver and our upgrade procedure will try to stick to this choice if possible.
(Note that, via a manual procedure and installation of extra packages, it is still possible to use aufs storage driver but we do not recommend it).
Debian was upgraded to Debian 10 (Buster) in XiVO 2020.10 release.
Warning
Upgrade from versions earlier than XiVO Boréalis (2018.16) are not supported.
You MUST first upgrade to at least XiVO Boréalis (2018.16) or more before upgrading to XiVO Freya.
Make sure you have sufficient space for the upgrade.
You should have more than 2GiB available in the filesystem that holds the /var and / directories.
It is not possible to upgrade from XiVO below Boréalis (2018.16) version. You first need to upgrade to XiVO Boréalis.
Note that the upgrade will take longer than usual because of all the system upgrade.
You MUST deactivate all non-xivo apt sources list:
in directory /etc/apt/sources.list.d/ you should only have the files xivo-dist.list and (from Aldebaran) docker.listpgdg.list.
you MUST suffix all other files with .save to deactivate them.
You MUST check the Debian sources list are correct: the file /etc/apt/sources.list must contain the following and only the following:
debhttp://ftp.fr.debian.org/debian/stretchmaindeb-srchttp://ftp.fr.debian.org/debian/stretchmaindebhttp://security.debian.org/stretch/updatesmaindeb-srchttp://security.debian.org/stretch/updatesmain# stretch-updates, previously known as 'volatile'debhttp://ftp.fr.debian.org/debian/stretch-updatesmaindeb-srchttp://ftp.fr.debian.org/debian/stretch-updatesmain
You may want to clean your system before upgrading:
Remove package that were automatically installed and are not needed anymore:
apt-getautoremove--purge
Purge removed packages. You can see the list of packages in this state by running dpkg-l|awk'/^rc/{print$2}' and purge all of them with:
After having check your network configuration and the grub configuration, you MUSTreboot your system. It is necessary for the upgrade to the Linux kernel to be effective.
Check that customization to your configuration files is still effective.
During the upgrade, new version of configuration files are going to be installed, and these might
override your local customization. For example, the vim package provides a new /etc/vim/vimrc
file. If you have customized this file, after the upgrade you’ll have both a /etc/vim/vimrc and
/etc/vim/vimrc.dpkg-old file, the former containing the new version of the file shipped by the vim
package while the later is your customized version. You should merge back your customization into
the new file, then delete the .dpkg-old file.
If collectd is installed, you will need to do the same with the /etc/collectd/collectd.conf file.
You can see a list of affected files by running find/etc-name'*.dpkg-old'. If some files
shows up that you didn’t modify by yourself, you can ignore them.
Purge removed packages. You can see the list of packages in this state by running dpkg-l|awk'/^rc/{print$2}' and purge all of them with:
Debian was upgraded to Debian 11 (Bullseye) in XiVO 2022.XX release.
Warning
Upgrade from versions earlier than XiVO Freya (2020.18) are not supported.
You MUST first upgrade to at least XiVO Freya (2020.18) or more before upgrading to XiVO Izar.
Make sure you have sufficient space for the upgrade.
You should have more than 2GiB available in the filesystem that holds the /var and / directories.
It is not possible to upgrade from XiVO below Freya (2020.18) version. You first need to upgrade to XiVO Freya.
Note that the upgrade will take longer than usual because of all the system upgrade.
You MUST deactivate all non-xivo apt sources list:
in directory /etc/apt/sources.list.d/ you should only have the files xivo-dist.list and (from Aldebaran) docker.listpgdg.list.
you MUST suffix all other files with .save to deactivate them.
You MUST check the Debian sources list are correct: the file /etc/apt/sources.list must contain the following and only the following:
debhttp://ftp.fr.debian.org/debian/bullseyemaindeb-srchttp://ftp.fr.debian.org/debian/bullseyemaindebhttp://security.debian.org/bullseye-security/updatesmaindeb-srchttp://security.debian.org/bullseye-security/updatesmain# stretch-updates, previously known as 'volatile'debhttp://ftp.fr.debian.org/debian/bullseye-updatesmaindeb-srchttp://ftp.fr.debian.org/debian/bullseye-updatesmain
You may want to clean your system before upgrading:
Remove package that were automatically installed and are not needed anymore:
apt-getautoremove--purge
Purge removed packages. You can see the list of packages in this state by running dpkg-l|awk'/^rc/{print$2}' and purge all of them with:
With Deneb, new version of the ELK stack is included. The old Kibana panels are disabled, but you can still reactive
them manually while loosing access to the new one. To do so, you have to rename the docker compose override file
on the XiVO CC server and recreate services:
While using the previous version of Totem Panels, these are not accessible from the fingerboard, only through
the http://XIVOCC_SERVER_ADDRESS/prevKibana link.
If you’re not going to use the previous version of the Elasticsearch or if you’re done creating the Dashboard in the new Kibana, please delete the folder with backuped data (on XiVO CC):
and dialplan function SIP_HEADER to read SIP headers
If you use one of them in one of your custom dialplan you have to change them to use the dialplan function PJSIP_HEADER (please read carefully the PJSIP_HEADER documentation).
PJSIP_HEADER dialplan function comes with the major difference (compared to SIPAddHeader or SIPRemoveHeader) to operate on the
current channel (i.e. the caller’s channel). See detail below.
The major difference between SIPAddHeader or SIPRemoveHeader and PJSIP_HEADER is that PJSIP_HEADER operates on the current channel (i.e. caller’s incoming channel): PJSIP_HEADER(add,X-My-Hdr,2) will add the header X-My-Hdr on the caller’s channel.
If you want to add a header on the (still to be created) callee’s outgoing channel, you must use pre-dial handler. See example in PJSIP_HEADER documentation.
The module is named xivo_header_mgr and is available anywhere in the dialplan.
You can call it anywhere in your dialplan to add your headers except in predial handler options b().
It works with any SIP channel driver. It will store the modifications and apply then inside a predial handler already set in the default dialplan.
Warning
Important limitation: Since the predial handler was added by default in every Dial application calls, calling a predial handler in your
preprocess subroutines will have the priority over the default one and will most likely break the header manager. You will need to call gosub set_header_on_channel
in your predial handler to make it work.
If you need to add a piece of dialplan ending with your own call to the Dial
application, don’t forget to add the call to the header manager in the b() predial handler,
even if you did not add any header during your custom subroutine.
When upgrading from XiVO 13.24 or earlier, you must do the following, before the normal upgrade:
Ensure that the file /etc/apt/sources.list is not configured on archive.debian.org.
Instead, it must be configured with a non-archive mirror, but still on the squeeze
distribution, even if it is not present on this mirror. For example:
Using archive versions enable you to upgrade your XiVO to a specific version, in case you don’t want
to upgrade to the latest (which is not recommended, but sometimes necessary). You will then be able
to upgrade your newer archive version to the latest version or to an even newer archive version.
These procedures are complementary to the upgrade procedure listed in
Version-specific upgrade procedures. You must follow the version-specific procedure
before running the following procedures.
The XiVO-CC software suite is made of several independent components. Depending on your system size,
they can be installed on separate virtual or physical machines. In this section, we will explain how to
install these components on a single machine.
XiVO PBX will be reconfigured during the installation and must be restarted.
You may accept the automatic restart during the installation or you need to restart
it manually later before starting the docker containers.
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.
This diagram is very important and shows the architecture between the different components inside XiVO CC and also interactions
with XiVO PBX components.
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.
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,
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.
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 three parts:
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.
The second part is to install the extra package for the chat.
The third part is to install the extra package for the recording.
The installation is automatic and you will be asked few questions during the process:
Before copying the authentication keys, you will be prompted for the XiVO PBX root password.
Enter IP addresses of XiVO PBX and XiVO CC.
XiVO PBX must restart, the question will prompt you to restart during the process or to restart later.
Running the script will install the XiVO CC components via the xivocc-installer package. It is required to restart XiVO PBX during or after the setup process.
The installer will ask whether you wish to restart XiVO PBX later.
Warning
Wizard MUST be passed on the XiVO PBX.
XiVO PBX services will need to be restarted.
The installer will ask whether you wish to restart XiVO PBX during or after the setup process.
Also, check that you have following information:
XiVO PBX root password;
OpenSSH PermitRootLogin set to yes (you could revert to no after installation of XivoCC);
XiVO PBX’s IP address;
XiVO CC DNS name or IP address (the one visible byXiVO PBX);
Number of weeks to keep statistics;
Number of weeks to keep recordings (beware of disk space);
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.
Launch installation:
./xivocc_install.sh-a2022.10-latest
Silent installation:
if it’s not already existing, set up the xivocc_rsa ssh key and upload it on the xivo:
Also, you MUST pass the variable via the /etc/docker/compose/custom.env.
Warning
Even if you’re installing an edge, XUC_HOST must be the XIVOCC IP at installation time. You’ll have to change it to the edge’s FQDN later
mkdir-p/etc/docker/compose
echo"XIVO_HOST=<IP ADDRESS OF THE XIVO>XUC_HOST=<CC IP>CONFIGURE_REPLY=trueWEEKS_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
Launch installation in Silent mode using the flag -s:
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:
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).
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:
To reinstall the package, it is required to run apt-getpurgexivocc-installer then apt-getinstallxivocc-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.
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 id2000)
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.
XiVO CC system configuration is stored in the /etc/docker/compose directory. All files are configured by the xivocc-installer
and don’t need to be edited. The directory contains these files:
docker-xivocc.yml, called compose file, defines XiVO CC components and their configuration. It uses variables
defined in the .env file.
.env file assigns values to variables used in the compose file. But this file is being generated by xivocc-dcomp
script and MUST NOT be edited directly.
factory.env file stores XiVO CC version number and distribution and should not be edited.
custom.env file may be used for component customization and multi-server installation.
Variable in the environment section without assignment is replaced by the same variable from .env file.
If it’s not defined or assigned in the .env file, it doesn’t appear in the container system.
Variable in the environment section with assigned value overrides value defined in the .env file.
Variable defined in the links section can be assigned to variable in the environment section.
Variable inside ${} block is replaced by value defined in .env file and can be used anywhere.
JAVA_OPTS - allocates Java memory and sets other Java options. If you want to use different values for containers,
they must be assigned inside compose file. Or you can define new variable for this purpose - e.g.: JAVA_OPTS=${JAVA_OPTS_XUC}
and set the value in the custom.env file.
XUC based web applications like agent interface or UC Assistant integrates buttons for phone control. This section
details necessary configuration, supported phones and limitations.
Note
The VoIP VLAN network have to be accessible by the xivocc xuc server
If you changed, via the XiVO PBX Web Interface in Configuration ‣ Provisioning‣ Template Device,
the phone administrator username or administrator password, you need to customize the xuc server configuration.
For this you need to:
Include the a specific configuration file for the xucserver onment variable to specify the alternate config file location
If the second call was initiated from Agent / Assistant and the called user rejected the call, the first call will stay hold until it is manually resumed
If the second call was initiated from the phone, the transfer must be also completed from the phone. It can’t be completed from Agent / Assistant.
You cannot complete a transfer initiated from the Agent / Assistant by hanging up.
A file /etc/logrotate.hourly/docker-container must be present which should log rotate files
/var/lib/docker/containers/*/*.log
You can test it with logrotate-fv/etc/logrotate.hourly/docker-container.
You should get some output and a new log file with suffix [CONTAINER ID]-json.log.1 should be created.
This file is compressed in next rotation cycle.
No alias for docker-compose should be defined. The following command should return “OK”:
alias|grep-E'docker-compose|dcomp'||echo"OK"
The version of the docker images in the file /etc/docker/compose/docker-xivocc.yml must be in the form ${XIVOCC_TAG}.${XIVOCC_DIST}
and these variables must be set in the /etc/docker/compose/factory.env file:
This section describes the manual installation of the XiVO CC components.
In most cases you SHOULD NOT follow this page, and install the XiVO CC components via the xivocc-installer package (see
Installation).
Important
You SHOULD NOT follow this page to install XiVO CC. We leave this page here :
to document how to install only a subset of the XiVO CC components (since it is not currently possible
via the xivocc-installer package).
to help with reconfiguring XiVO for XiVO CC after it has been restored from backup
as a reference
Note
Since XiVO PBX 2017.06 some parts of the installation were moved from xivocc-installer to installation of XiVO PBX.
Docker container log output to /dev/stdout and /dev/stderr.
The Docker container log file is saved in /var/lib/docker/containers/[CONTAINER ID]/[CONTAINER_ID]-json.log.
Create a new Logrotate config file for your Docker containers in the Logrotate folder /etc/logrotate.d/docker-container.
You can test it with logrotate -fv /etc/logrotate.d/docker-container.
You should get some output and a new log file with suffix [CONTAINER ID]-json.log.1 should be created.
This file is compressed in next rotation cycle.
the number of weeks to keep for the recording files
the external IP of the machine (i.e. the adress used afterwards for http URLs)
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.
Switch the sources to the new XiVO CC LTS version with xivo-dist, for example, to switch to Gaia LTS version:
xivo-distxivo-gaia
Read carefully theRelease Notes starting from your current version to the version you target (read even more
carefully the New features and Behavior changes between LTS)
Check the specific instructions and manual steps from your current LTS to your targetted LTS and all intermediate LTS: see Manual steps for LTS upgrade
Check also if you are in a specific setup that requires a specific procedure
After the release of a version (e.g. Freya (2020.18)) we may backport some bugfixes in this version.
We will then create a subversion (e.g. Freya .04 (2020.18 .04)) shipping these bugfixes.
These bugfix version does not contain any behavior change.
To upgrade to the latest subversion of your current installed version you need to:
Read carefully theRelease Notes starting from your installed version (e.g. Freya.00) to the latest bugfix release (e.g. Freya.04).
Verify that the debian sources list corresponds to your installed LTS or refix it, for example for Freya:
xivo-distxivo-freya
Verify that the /etc/docker/compose/factory.env file has
XIVOCC_TAG=VERSION (where VERSION is your current installed version - e.g. 2020.18)
If there is any change, you should accept the new docker-compose.yml file. Then compare it with the old docker-compose.yml.dpkg-old file and report in the new any specific configuration.
Then download the new docker images:
xivocc-dcomppull
And run the new containers (Corresponding XiVO CC services will be restarted):
xivocc-dcompup-d--remove-orphans
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.
These notes include upgrade procedures for old versions of the Pack reporting, before XivoCC starts and before it was packaged with Docker.
In those cases, run the following command to find the installed version of the pack reporting:
data retention time will be lost during upgrade : save it and write it back in /etc/xivo-reporting-db.conf
the upgrade is likely to be long if there is a lot of data in queue_log. Purge old data out of this table if possible
in order to accelerate the upgrade
at the end of the upgrade, run apt-get autoremove (deletion of xivo-stat, xivo-libdao and xivo-lib-python)
if it is required, the upgrade of the XiVO must be done before the upgrade of the pack reporting,
and no call must be performed between the two upgrades
From a version using Debian packaging to a version using Docker
Beware: this will require a migration of the original PostgreSQL database to the Dockerised one. For this you need to have free disk space :
the amount of free disk space must equal the size of /var/lib/postgresql. This check must be performed after docker images have been pulled.
dockerexec-ticompose_pgxivocc_1psql-Upostgres-c'CREATE EXTENSION IF NOT EXISTS "uuid-ossp"'xivo_stats
dockerexec-ticompose_pgxivocc_1psql-Upostgres-c'CREATE EXTENSION IF NOT EXISTS "uuid-ossp"'xuc_rights
This page describes what to do to upgrade your XiVO UC/CC to Debian 9 (Stretch).
Important
Upgrade your XiVO UC/CC to Debian 9 (Stretch) is a mandatory step when upgrading to Electra because system freezes
were detected during test of Electra version with kernel 3.16. Problem was solved with
kernel 4.9 and higher.
Warning
In Debian 9 (Stretch) docker storage driver changed from aufs to overlay2.
Therefore all containers and images need to be recreated.
Note that overlay2 is incompatible with XFS partition created withoutftype=1option.
If the partition is XFS, you MUST check if the option is enabled with the xfs_info command.
What to check before upgrading to Debian 9 (Stretch):
your XiVO UC/CC MUST be in Deneb version otherwise all the database data will be lost !
the partition where docker data is stored must not be using XFS file system with ftype different from 1.
You can use e.g. this command to check file system:
dockerinfo2>/dev/null|grep"Backing Filesystem"
If it is XFS, you can check ftype with the following command (assuming that docker data dir is /var/lib/docker):
After having backup your configuration you’re ready to upgrade the host to Debian 9 (Stretch).
We don’t cover the Debian upgrade procedure itself here, this can be found on Debian 9 release notes.
Here we’ll only give the main steps and where specific actions are to be performed in a XiVO UC/CC context.
The upgrade consist of:
Updating the host to latest Debian 8 (Jessie) version
Switching the sources list to Debian 9 (Stretch). Specifically on a XiVO UC/CC you must
also update the sources list of the docker repo:
Once a media server is defined in webi, the xucserver from UC/CC Server will
immediately start to use the VoIP interface for AMI connection to all media servers and also to XiVO.
Therefore we must ensure that UC/CC Server is able to connect to XiVO AMI via its VoIP interface.
Warning
If a XiVO UC/CC is already installed, you MUST do the following steps BEFORE adding media server.
Otherwise you can first define media servers and do these steps right after XiVO CC installation,
but before starting it to prevent problems with fail2ban.
Edit existing file /etc/asterisk/manager.d/02-xivocc.conf to add permission for xucserver* of UC/CC Server (CTI Server):
permit to authorize the VoIP IP of the UC/CC Server (CTI Server). E.g.:
Here we define our Media Servers (MDS) names and VoIP IP address.
In XiVO webi,
Go to Configuration ‣ Management ‣ Media Servers
Add a line per Media Server (MDS) (below an example for mds1):
Name: mdsX (e.g. mds1)
Displayed Name: Media Server X (e.g. Media Server 1)
IP VoIP: <VoIP IP of mdsX> (e.g. 10.32.5.101) - note: the VoIP streams between XiVO and mdsX will go through this IP
Once you define a media server, you will be able to create local SIP trunks that exist only there.
The location can be set in tab General ‣ Media server in the SIP trunk configuration.
In file /var/lib/postgresql/11/main/pg_hba.conf add an authorization per mds to connect to the db. Here you will probably want to use the Data IP of mdsX:
You need to do this manual step on XiVO Main for the file sync to take place. See File Synchronization page for the feature description.
Rename files in synced dir (and mainly custom dialplans in /etc/asterisk/extensions_extra.d/) which should not be synchronized to be prefixed with xds_override.
All files named with this prefix will be excluded from synchronization.
Initialize synchronization of dialplans by running the command:
xivo-xds-sync-i
Note
The initialization will:
generate a ssh key pair: ~/.ssh/rsync_xds and ~/.ssh/rsync_xds.pub
copy the public key to /usr/share/xivo-certs/
make the public key available at https://XIVO_HOST/ssh-key
create cron job /etc/cron.d/xivo-xds-sync to schedule the synchronization
If an edge is already configured and you are switching from a normal setup to an XDS one,
do not forget to do the following configuration on the edge side.
For edge 3 VM, see SIP Proxy.
For edge on a single VM, see Web Proxy, SIP Proxy and TURN Server.
The install script installs and configures postfix:
to relay mails towards the XiVO Main - see relayhost parameter in /etc/postfix/main.cf file,
and use the content of /etc/mailname file as the domain part of the from address - see myorigin parameter in /etc/postfix/main.cf.
Note
Note that the content of /etc/mailname file is taken during installation from the domain if set or the hostname.
Therefore if mail sent from the MDS are not correctly relayed by the XiVO Main, you should check and play with the value
of the /etc/mailname file. And then reload the postfix if needed servicepostfixreload.
Add on the XiVO the trunk towards your provider (it can be an ISDN or SIP trunk).
When creating the trunk, select the Media Server on which it will be located.
Restarting XUC server with active calls in XDS environment will result in having some agents in incorrect state.
Please see the note in restarting XUC server with active calls.
XiVO includes a DHCP server used for assisting in the provisioning of phones and other devices. (See
Basic Configuration for the basic setup). This section contains additional
notes on how to configure more advanced options that may be helpful when integrating the server with
different VOIP subnets.
By default, it will only answer to DHCP requests coming from the VoIP subnet (defined in the
Configuration ‣ Network ‣ Interfaces section). If you need to activate DHCP on
an other interface, you have to fill in the Extra network interfaces field with the interface name
, for example : eth0
After saving your modifications, click on Apply system configuration so that the new settings can
take effect.
If your telephony devices aren’t located on the same site and the same broadcast domain as the XiVO
DHCP server, you will have to add the option DHCP Relay to the site’s router. This parameter will
allow the DHCP requests from distant devices to be transmitted to the IP address you specify as DHCP
Relay.
Warning
Please make sure that the IP address used as DHCP Relay is the same as one of XiVO’s
interfaces, and that this interface is configured to listen to DHCP requests (as decribed in
previous part). Also verify that routing is configured between the distant router and the choosen
interface, otherwise DHCP requests will never reach the XiVO server.
This section describes how to configure XiVO to serve other subnets that the VOIP subnet. As you
can’t use the Web Interface to declare other subnets (for example to address DATA subnet, or a VOIP
subnet that isn’t on the same site that XiVO server), you’ll have to do the following configuration
on the Command Line Interface.
In this case we’ll create 2 files for 2 differents subnets. You can change the name of the files,
and create as many files as you want in the folder /etc/dhcp/dhcpd_sites/. Just adapt
this procedure by changing the name of the file in the different links.
After creating one or several files in /etc/dhcp/dhcpd_sites/, you have to edit the file
/etc/dhcp/dhcpd_extra.conf and add the according include statement like:
Once you have created the subnet in the DHCP server, you must edit each configuration file (the
files in /etc/dhcp/dhcpd_sites/) and modify the different parameters. In section
subnet, write the IP subnet and change the following options (underlined fields in the
example):
subnet172.30.8.0netmask255.255.255.0{
subnet-mask:
optionsubnet-mask255.255.255.0;
broadcast-address:
optionbroadcast-address172.30.8.255;
routers (specify the IP address of the router that will be the default gateway of the site):
optionrouters172.30.8.1;
In section pool, modify the options:
pool{
log (add the name of the site or of the subnet):
log(concat("[",binary-to-ascii(16,8,":",hardware),"] POOL VoIP Site XXX"));
range (it will define the range of IP address the DHCP server can use to address the devices of
that subnet):
range172.30.8.10172.30.8.200;
Warning
XiVO only answers to DHCP requests from supported devices. In case of
you need to address other equipment, use the option allow unknown-clients; in the
/etc/dhcp/dhcpd_sites/ files
If you have checked the “DHCP integration” (See Advanced Configuration for the basic setup) in provisionning configuration, you will also MUST add the parameter below: (Otherwise provd won’t be able to route the devices to the correct plugins)
At this point, you can apply the changes of the DHCP server with the command:
serviceisc-dhcp-serverrestart
After that, XiVO will start to serve the DHCP requests of the devices located on other sites or
other subnets than the VOIP subnet. You will see in /var/log/daemon.log all the DHCP
requests received and how they are handled by XiVO.
Postfix, the mail server shipped with XiVO, should be stopped on an installed XiVO with no valid and reachable DNS servers configured. If Postfix is not stopped, messages will bounce in queues and could end up affecting core pbx features.
If you need to disable Postfix here is how you should do it:
systemctlstoppostfixsystemctldisablepostfix
If you ever need to enable Postfix again:
systemctlenablepostfixsystemctlstartpostfix
Alternatively, you can empty Postfix’s queues by issuging the following commands on the XiVO server:
This section describes how to configure additional network devices that may be used to better
accomodate more complex network infrastructures. Network interfaces are managed in the XiVO web
interface via the page Configuration ‣ Network ‣ Interfaces.
XiVO offers 2 types of interfaces: VoIP and Data. The VoIP interface is used by the DHCP
server, provisioning server, and phone devices connected to your XiVO. These services will use the
information provided on the VoIP interface for their configuration. For example, the DHCP server
will only listen on the VoIP interface by default.
To change these settings, you must either create a new interface or edit an existing one and change
its type. When adding a new VoIP interface, the type of the old one will automatically be changed
to Data.
Note that since our eth0 network interface already has a default gateway,
we do not enter information in the Defaultgateway field for our eth1 interface.
Once the changes have been saved, the action Apply network configuration will appear in bold.
This action must be clicked in order for the changes to take effect.
Static routes cannot be added via the web interface. However, you may add static routes to your XiVO
by following following the steps described below. This procedure will ensure that your static routes
are applied at startup (i.e. each time the network interface goes up).
Fields <network interface>, <destination> and <gateway> should be replaced by your specific
configuration. For example, if you want to add a route for 192.168.50.128/25 via 192.168.17.254
which should be added when eth0 goes up:
The above check is to ensure that the route will be applied only if the correct interface
goes up. This check should contain the actual name of the interface (i.e. eth0 or eth0.2 or
eth1 or …). Otherwise the route won’t be set up in every cases.
#!/bin/sh
# Set MTU per iface
if [ "${IFACE}" = "<data interface>" ]; then
ip link set ${IFACE} mtu <data mtu>
elif [ "${IFACE}" = "<voip interface>" ]; then
ip link set ${IFACE} mtu <voip mtu>
fi
Change the <data interface> to the name of your interface (e.g. eth0), and the <data mtu> to
the new MTU (e.g. 1492),
Change the <voip interface> to the name of your interface (e.g. eth1), and the <voip mtu> to
the new MTU (e.g. 1488)
Note
In the above example you can set a different MTU per interface.
If you don’t need a per-interface MTU you can simply write:
Starting from the Callisto version, the database on the XiVO PBX and all mediaservers is started inside a docker container based on custom image.
On first startup the database will be initialized and the required structure and data will be created inside a host mounted folder /var/lib/postgresql/11/main/.
The database image contains a default postgres configuration and some specific defaults required by our application:
the postgres default configuration is located in /var/lib/postgresql/11/main/postgresql.conf
and our custom defaults are in /var/lib/postgresql/11/main/conf.d/00-xivo-default.conf.
Warning
Do not change these files!
If you need to change some parameters, create another file in /var/lib/postgresql/11/main/conf.d/ prefixed with a number like 01 or upper and with a .conf extension. This file will be loaded after all defaults and can override any parameter.
This schema shows required database connections between different types of servers.
These connections must be authorized in pg_hba.conf file. It is being done automatically or it is described in installation or upgrade documentation.
It also shows how asterisk database is replicated. Only configuration tables are replicated between asterisk databases
and only event tables (cel and queue_log) are replicated to stats database.
You can retrieve the backup from the web-interface in
Services ‣ IPBX ‣ IPBX Configuration ‣ Backup Files page.
Otherwise, with shell access, you can retrieve them in /var/backups/xivo.
In this directory you will find db.tgz and data.tgz files for the database and data
backups.
A backup of both the configuration files and the database used by a XiVO installation is done
automatically every day.
These backups are created in the /var/backups/xivo directory and are kept for 7 days.
Warning
A XiVO backup includes the entirety of the original machine’s network configuration :
it WILL overwrite any present network settings when you restore it.
Remember to change those settings back if required before restarting network services or the machine itself,
especially if you do not have physical or console access!
Before restoring a XiVO on a fresh install you have to setup XiVO using the wizard (see Running the Wizard section).
Stop monit and all the xivo services:
xivo-servicestop
Before restoring the database, all other services connected to it (XiVO CC, MDS) must be stopped also. You can list active connections:
sudo-upostgrespsql-c"SELECT*FROMpg_stat_activityWHEREpid<>pg_backend_pid()"
If you want to restore XiVO < 2017.06 that was configured for XiVO CC, you must create PostgreSQL user stats before
restoring the database. See Creating user stats.
Restoring the data.tgz file also restores system files such as host
hostname, network interfaces, etc. You will need to reapply the network
configuration if you restore the data.tgz file.
Restart the services you stopped in the first step:
xivo-servicestart
You may also reboot the system. Remember that the network settings were overwritten by the backed up settings, check and fix if necessary before rebooting!
xivo-dist is the xivo repository sources manager. It is used to switch between distributions
(production, development, release candidate, archived version). Example use cases :
switch to production repository : xivo-distxivo-five
switch to development repository : xivo-distxivo-dev
switch to release candidate repository : xivo-distxivo-rc
switch to an archived version’s repository (here 14.18) : xivo-distxivo-14.18
X.509 certificates are used to authorize and secure communications with the server. They are mainly
used for HTTPS, but can also be used for SIPS, CTIS, WSS, etc.
There are two certificates shipped by default in XiVO:
/usr/share/xivo-certs/server.crt: the default certificate used for backend services and REST APIs
/etc/docker/nginx/ssl/xivoxc.crt: the default certificates used by the web interface
(and also by the UC Application when in UC Addon mode)
XiVO uses HTTPS where possible. The certificates are generated at install time. The main certificates are located
in /usr/share/xivo-certs/server.crt (used by backend services and REST APIs)
and in /etc/docker/nginx/ssl/xivoxc.crt (used ny Nginx and therefore the Webi)
However, these certificates are self-signed, and HTTP clients (browser or REST API client) will
complain about this default certificate because it is not signed by a trusted Certification
Authority (CA).
To make the HTTP client accept this certificate, you have two choices:
configure your HTTP client to trust the self-signed XiVO certificate by adding a new trusted CA.
The CA certificate (or bundle) is the file /usr/share/xivo-certs/server.crt.
replace the self-signed certificate with your own trusted certificate.
This certificate is used for XiVO Webi and, more importantly, for UC Application when in UC-Addon mode.
In this case this is mandatory (at least to use WebRTC) to install trusted certificate.
For this, follow these steps:
Replace the following files with your own private key/certificate pair:
Change the hostname of XiVO for each XiVO component: the different processes of XiVO heavily use
HTTPS for internal communication, and for these connection to establish successfully, all
hostnames used must match the Common Name (CN) of your certificate. Basically, you must replace
all occurrences of localhost (the default hostname) with your CN in the configuration of the
XiVO services. For example:
Also, you must replace localhost, in the definition of your directories in the web interface under Configuration ‣ Directories, by the hostname matching the CN of your certificate.
Then, when done, you must re-save, the CTI Directories definition:
Go to Services ‣ CTI Server ‣ Directories ‣ Definitions
Edit each directory to re-select the new URI
And save it
If your certificate is not self-signed, and you obtained it from a third-party CA that is trusted
by your system, you must enable the system-based certificate verification. By default,
certificate verification is set to consider /usr/share/xivo-certs/server.crt as the only CA
certificate.
First you need to install the debian ca-certificates package:
apt-getinstallca-certificates
If one of the CA (or intermediate CA) of your certificate is not present in the CA shipped by the
ca-certificates package you will need to add it manually:
Create the following dir if not present:
mkdir/usr/local/share/ca-certificates/
Copy inside this directory the certificate of the missing CA in a .crt file
And finally upload ca-certificates configuration:
update-ca-certificates
Then to activate the certificat verification, the options are the following:
Consul: verify:True
Other XiVO services: verify_certificate:True
The procedure is the same as 2. with more configuration for each service. For example:
Setting verify_certificate to False will disable the certificate verification, but the
connection will still be encrypted. This is pretty safe as long as XiVO services stay on the same
machine, however, this is dangerous when XiVO services are separated by an untrusted network,
such as the Internet.
Ensure your CN resolves to a valid IP address with:
a DNS entry
and an entry in /etc/hosts resolving your CN to 127.0.0.1. Note that /etc/hosts
will be rewritten by xivo-sysconfd. To make the change persistent, you need to create custom templates:
in /etc/xivo/custom-templates/system/etc/hosts (based on template /usr/share/xivo-config/templates/system/etc/hosts)
and in /etc/xivo/sysconfd/custom-templates/resolvconf/hosts (based on template /usr/share/xivo-sysconfd/templates/resolvconf/hosts)
Your X.509 certificate must have subjectAltName defined. See the example at cacert.org
or detailed documentation at ietf.org.
Since Jabbah.07 the conf is only re-generated after an edition in the Webi.
Launching manually a modulereloadres_pjsip.so in asterisk CLI will not
reload the current conf from the db, it will only re-load the current generated conf
(see How to reload the configuration ?).
When you save an object in the Admin Web interface (a User, or a Line or …) the Web Interface calls
xivo-sysconfd service which will reload the configuration.
Configuration files for every service running on a XiVO server will respect these rules:
Default configuration directory in /etc/xivo-{service}/conf.d (e.g.
/etc/xivo-agentd/conf.d/)
Default configuration file in /etc/xivo-{service}/config.yml (e.g.
/etc/xivo-agentd/config.yml)
The files /etc/xivo-{service}/config.yml should not be modified because they will be
overridden during upgrades. However, they may be used as examples for creating additional
configuration files as long as they respect the Configuration priority. Any exceptions to
these rules are documented below.
Purpose: This file is used to normalize the caller number received from the provider.
Warning
Please read Caller Number Normalization to understand what are the impacts of changing or not changing the caller number.
This file xivo_in_callerid.conf consists of:
sections of configuration like [national1]
each section having:
comment a comment to explain the role of this section
callerid a pattern matching a number
strip the number of digits to strip from the caller number
add what to add to the caller number
How the file is processed:
Sections are only used to make differentations and give sense to options.
Sections are scanned for matching in file order, so you can implement priorities easily.
If the callerid didn’t match: do nothing
If a number matched:
If strip only: strip specified number at the beginning of the number
If add only: add the specified digits at the beginning of the number
If both: begin with striping and finish with add. Usefull if incoming callerid need to be set in the “international format” : for example in France, replace (0) by (+33)
Examples (but again, take care of the important note above):
If you use a prefix to dial outgoing numbers (like a 0) you should add a 0 to all the add= sections,
You may want to display incoming numbers in E.164 format. For example, you can change the [national1] section to:
callerid = ^0[1-9]\d{8}$
strip = 1
add = +33
To enable the changes you have to restart xivo-agid:
Purpose: This file can be used to change the ringtone played by the phone depending on the
origin of the call.
Warning
Note that this feature has not been tested for all phones and all call flows.
This page describes how you can customize this file but does not intend to list all validated
call flows or phones.
This file xivo_ring.conf consists of :
profiles of configuration (some examples for different brands are already included: [aastra],
[snom] etc.)
one section named [number] where you apply the profile to an extension or a context etc.
Here is the process you should follow if you want to use/customize this feature :
Create a new profile, e.g.:
[myprofile-aastra]
Change the phonetype accordingly, in our example:
[myprofile-aastra]phonetype=aastra
Chose the ringtone for the different type of calls (note that the ringtone names are
brand-specific):
Purpose: This file specifies various configuration options and paths related
to Asterisk and used by the web interface.
As file is embedded in docker, to edit it, you should execute:
dockercpxivo_webi_1:/etc/xivo/web-interface/ipbx.ini/tmpvi/tmp/ipbx.ini# And save your modificationdockercp/tmp/ipbx.inixivo_webi_1:/etc/xivo/web-interface/ipbx.ini
Here is a partial glimpse of what can be configured in file ipbx.ini :
Enable/Disable modification of SIP line username and password:
[user]readonly-idpwd="true"
When editing a SIP line, the username and password fields cannot be modified
via the web interface. Set this option to false to enable the modification of
both fields. This option is set to “true” by default.
Warning
This feature is not fully tested. It should be used only when
absolutely necessary and with great care.
The default consul installation in XiVO uses the
configuration file in /etc/consul/xivo/*.json. All files in this directory
are installed with the package and should not be modified by the
administrator. To use a different configuration, the adminstrator can add it’s
own configuration file at another location and set the new configuration directory by creating a
systemd unit drop-in file in the /etc/systemd/system/consul.service.d directory.
The default installation generates a master token that can be retrieved in
/var/lib/consul/master_token. This master token will not be used if a new
configuration is supplied.
# on the consul host
scproot@<xivo-host>:/lib/systemd/system/consul.service/lib/systemd/system
systemctldaemon-reload
scp-rroot@<xivo-host>:/etc/consul/etc
scp-rroot@<xivo-host>:/usr/share/xivo-certs/usr/share
consulagent-data-dir/var/lib/consul-config-dir/etc/consul/xivo/
Note
To start consul with the systemd unit file, you may need to change owner and group
(consul:consul) for all files inside /etc/consul, /usr/share/xivo-certs
and /var/lib/consul
It’s configuration files /etc/logrotate.d/asterisk and /etc/asterisk/logger.conf
The message log level is enabled by default in logger.conf and contains notices, warnings
and errors. The full log entry is commented in logger.conf and should only be enabled when
verbose debugging is required. Using this option in production would produce VERY large log files.
XiVO has a NTP server, that must be synchronized to a reference server. This can be a public one or customized for specific target networking architecture.
XiVO’s NTP server is used by default as NTP server for the devices time reference.
server192.168.0.1# LAN existing NTP Serverserver0.debian.pool.ntp.orgiburstdynamic# default in ntp.confserver1.debian.pool.ntp.orgiburstdynamic# default in ntp.conf
If no reference server to synchronize to, add this to synchronize locally:
server127.127.1.0# local clock (LCL)fudge127.127.1.0stratum10# LCL is not very reliable
Restart NTP service
Check NTP synchronization status.
Warning
If #5 shows that NTP doesn’t use NTP configuration in /etc/ntp.conf, maybe have
you done a dhclient for one of your network interface and the dhcp server that gave the IP
address also gave a NTP server address. Thus you might check if the file /var/lib/ntp/ntp.conf.dhcp
exists, if yes, this is used for NTP configuration prior to /etc/ntp.conf. Remove it and
restart NTP, check NTP synchronization status, then it should work.
If you use XiVO behind an HTTP proxy, you must do a couple of manipulations for
it to work correctly.
Warning
We do not recomend to use http_proxy environment variable. It may
break some services.
Instead you should configure the proxy on a per service basis as described
below.
XiVO uses consul for service discovery. When a daemon is
started, it registers itself on the configured consul node.
Consul template may be used to generate the
configuration files for each daemons that requires the availability of another
service. Consul template can also be used to reload the appropriate service.
XiVO services expose more and more resources through REST API, but they also ensure that the access
is restricted to the authorized programs. For this, we use an authentication daemon who delivers authorizations via tokens.
Newly created webi user can’t see any webi menus. To add them, use the key action button.
Then choose objects which can be edited by this user and save the form.
Important
These menus require additional permissions to allow webi to access ConfigMgt and external Confd port:
To allow admin users to use these menus, you must also give them the permission
Authenticate configuration server web services request (required for admin users)
from the Rules ‣ IPBX ‣ Control System menu.
xivo-auth is a scalable, extendable and configurable authentication service.
It uses an HTTP interface to emit tokens to users who can then use those tokens
to identify and authenticate themselves with other services compatible with
xivo-auth.
xivo-auth contains 4 major components, an HTTP interface, a celery worker,
authentication backends and a consul client. All operations are made through
the HTTP interface, tokens are stored by consul as well as the persistence
for some of the data attached to tokens. The celery worker is used to schedule
tasks that outlive the lifetime of the xivo-auth process. Backends are used
to test if a supplied username/password combination is valid and provide the
xivo-user-uuid.
xivo-auth is made of the following modules and packages.
To simplify authentication of internal services without renewing the Token we have added
a command line tool xivo-auth-static-token-manager to manage static tokens. Currently
you can get a static token, which is created automatically during the installation. The
same tool can be used to create a new one if needed. The static token is created with default
acl: confd.users.read.
In legacy webi PHP code, calls to confd are done server side through the internal confd port (listening only on localhost).
On this endpoint, no authentication is necessary.
While moving some part of the webi code towards Js, needed calls to confd are done client side and therefore can only be done
through the external confd port (listening on all IP interfaces).
On this endpoint authentication is needed.
The following schema summarizes the approach:
Accessing confd API from Webi client side. (source)
Given a webi administrator is logged in the webi and opens a menu rewritten in Js:
Js client asks a token to authd, sending its Webi cookie
This call is proxified via Nginx to authd which first asks the Webi to validate the cookie before proxifying the request
authd returns a token based on the cookie. For this :
Here’s how the mapping between webi permission to confd ACL is done:
the XiVO Session backend retrieve the webi admin user and its configured webi permissions
these webi permissions are converted to a python dict
which is then flattened, read and compared to a mapping dict named WEBI_PERMS_TO_CONFD_ACL to retrieve the correct ACLs
If you want to add a mapping you simply have to edit the WEBI_PERMS_TO_CONFD_ACL dict to add a new mapping
between a menu path to an confd ACL or list of ACL.
Purpose: Authenticate a XiVO administrator’s session. This backend receives an administrator’s webi cookie with session id and returns a valid token with a confd ACL
depending on the logged administrator webi permission:
Webi administrator of type root receives a wildcard confd ACL
Webi administrator of type admin receives a confd ACL depending on its webi permission (see table below)
xivo-auth is used through HTTP requests, using HTTPS. Its default port is 9497.
As a user, the most common operation is to get a new token. This is done with
the POST method.
Alice retrieves a token using her username/password:
$ # Alice creates a new token, using the xivo_user backend, expiring in 10 minutes
$ curl -k -X POST -H 'Content-Type: application/json' -u 'alice:s3cre7' "https://localhost:9497/0.1/token" -d '{"backend": "xivo_user", "expiration": 600}';echo
{"data": {"issued_at": "2015-06-05T10:16:58.557553", "token": "1823c1ee-6c6a-0cdc-d869-964a7f08a744", "auth_id": "63f3dc3c-865d-419e-bec2-e18c4b118224", "xivo_user_uuid": "63f3dc3c-865d-419e-bec2-e18c4b118224", "expires_at": "2015-06-05T11:16:58.557595"}}
In this example Alice used here XiVO CTI client login alice and password s3cre7. The
authentication source is determined by the backend in the POST data.
Alice could also have specified an expiration time on her POST request. The
expiration value is the number of seconds before the token expires.
After retrieving her token, Alice can query other services that use xivo-auth
and send her token to those service. Those services can then use this token
on Alice’s behalf to access her personal storage.
If Alice wants to revoke her token before its expiration:
A service that requires authentication and identification can use xivo-auth to
externalise the burden of authentication. The new service can then accept a
token as part of its operations to authenticate the user using the service.
Once a service receives a token from one of its user, it will need to check the
validity of that token. There are 2 forms of verification, one that only checks
if the token is valid and the other returns information about this token’s
session if it is valid.
Checking if a token is valid:
$ curl -k -i -X HEAD -H 'Content-Type: application/json' "https://localhost:9497/0.1/token/1823c1ee-6c6a-0cdc-d869-964a7f08a744"
HTTP/1.1 204 NO CONTENT
Content-Type: text/html; charset=utf-8
Content-Length: 0
Date: Fri, 05 Jun 2015 14:49:50 GMT
Server: pcm-dev-0
$ # get more information about this token
$ curl -k -X GET -H 'Content-Type: application/json' "https://localhost:9497/0.1/token/1823c1ee-6c6a-0cdc-d869-964a7f08a744";echo
{"data": {"issued_at": "2015-06-05T10:16:58.557553", "token": "1823c1ee-6c6a-0cdc-d869-964a7f08a744", "auth_id": "63f3dc3c-865d-419e-bec2-e18c4b118224", "xivo_user_uuid": "63f3dc3c-865d-419e-bec2-e18c4b118224", "expires_at": "2015-06-05T11:16:58.557595"}}
xivo-confd resources are organised through a plugin mechanism. There are 2 main plugin categories:
Resource plugins
A plugin that manages a resource (e.g. users, extensions, voicemails, etc). A resource plugin
exposes the 4 basic CRUD operations (Create, Read, Update, Delete) in order to operate on a
resource in a RESTful manner.
Association plugins
A plugin for associating or dissociating 2 resources (e.g a user and a line). An association
plugin exposes an HTTP action for associating (either POST or PUT) and another for
dissociating (DELETE)
The following diagram outlines the most important parts of a plugin:
Class that receives and handles HTTP requests. Resources use flask-restful for handling requests.
There are 2 kinds of resources: ListResource for root URLs and ItemResource for URLs that
have an ID. ListResource will handle creating a resource (POST) and searching through a
list of available resources (GET). ItemResource handles fetching a single item (GET),
updating (PUT) and deleting (DELETE).
Service
Class that handles business logic for a resource, such as what to do in order to get, create,
update, or delete a resource. Service classes do not manipulate data directly. Instead, they
coordinate what to do via other objects.
There are 2 kinds of services: CRUDService for basic CRUD operations in Resource
plugins, and AssociationService for association/dissociation operations in Association
plugins.
Dao
Data Access Object. Knows how to get data and how to manipulate it, such as SQL queries, files,
etc.
Notifier
Sends events after an operation has completed. An event will be sent in a messaging queue for
each CRUD operation. Certain resources also need to send events to other daemons in order to
reload some configuration data. (i.e. asterisk needs to reload the dialplan when an extension is
updated)
Validator
Makes sure that a resource’s data does not contain any errors before doing something with it.
A Validator can be used for validating input data or business rules.
xivo-confgend uses drivers to implement the logic required to generate
configuration files. It uses stevedore
to do the driver instantiation and discovery.
Plugins in xivo-confgend use setuptools’ entry points. That means that
installing a new plugin to xivo-confgend requires an entry point in the plugin’s
setup.py.
Driver plugin are classes that are used to generate the content of a
configuration file.
The implementation of a plugin should have the following properties.
It’s __init__ method should take one argument
It should have a generate method which will return the content of the file
A setup.py adding an entry point
The __init__ method argument is the content of the configuration of
xivo-confgend. This allows the driver implementor to add values to the
configuration in /etc/xivo-confgend/conf.d/*.yml and these values will be
available in the driver.
The generate method has no argument, the configuration provided to the
__init__ should be sufficient for most cases. generate is called within a
scoped_session of xivo-dao, allowing the usage of xivo-dao without prior setup
in the driver.
The namespaces used for entry points in xivo-confgend have the following form:
xivo_confgend.<resource>.<filename>
as an example, a generator for sip.conf would have the following namespace:
xivo-dird is the directory server for XiVO. It offers a simple REST interface to query all
directories that are configured. xivo-dird is extendable with plugins.
This sections controls which plugins are to be loaded at xivo-dird startup. All plugin types must
have at least one plugin enabled, or xivo-dird will not start. For back-end plugins, sources using a
back-end plugin that is not enabled will be ignored.
A dictionary describing the content of each display. The key is the display’s name, and the value
are the display’s content.
The display content is a list of fields. Each field is a dictionary with the following keys:
title: The label of the field
default: The default value of the field
type: An arbitrary identifier of the field. May be used by consumers to identify the field
without matching the label. For meaningful values inside XiVO, see
Integration of XiVO dird with the rest of XiVO.
field: the key of the data from the source that will be used for this field.
The display may be used by a plugin view to configure which fields are to be presented to the
consumer.
displays_phone
A dictionary describing the content of phone-related displays. Like displays, the key is the
display’s name and the value is the display’s content. These displays are used by phone-related
view plugins, like the cisco_view plugin.
The display content contains 2 keys, name and number.
The value of the name key is a list of source result fields. For a given source result, the
first field that will return a non-empty value will be used as the display name on the phone.
For example, if name is configured with ["display_name","name"] and you have a source result
with fields {"display_name":"","name":"Bob"}, then “Bob” will be displayed on the phone.
The value of the number key is a list of number item. Each item is composed of a dictionary
containing at least a field key, and optionally a name_format key. For example, if you
have the following number configuration:
and you have a source result {"display_name":"Bob","phone":"101","phone_mobile":"102"},
then 2 results will be displayed on your phone:
“Bob”, with number “101”
“Bob (Mobile)”, with number “102”
The name_format value is a python format string. There’s two substitution variables
available, {name} and {number}.
profile_to_display
A dictionary associating a profile to a display. It allows xivo-dird to use the right display
when a consumer makes a query with a profile. The key is the profile name and the value is the
display name.
profile_to_display_phone:
A dictionary associating a profile to a phone display. This is similar to profile_to_display,
but only used by phone-related view plugins.
This section is a dictionary whose keys are the service plugin name and values are the configuration
of that service. Hence the content of the value is dependent of the service plugin. See the
documentation of the service plugin (Stock Plugins Documentation).
This section is a dictionary whose keys are the source name and values are the configuration for that
source. See the Sources Configuration section for more details about source
configuration.
the type of the source. It must be the same than the name of one of the enabled back-end plugins.
name
is the name of this given configuration. The name is used to associate the source to profiles.
The value is arbitrary, but it must be unique across all sources.
Warning
Changing the name of the source will make all favorites in that source disappear. There
is currently no tool to help you migrate favorites between source names, so choose your
source names carefully.
The other options are dependent on the source type (the back-end used). See the documentation of the
back-end plugin (Stock Plugins Documentation). However, the following keys should be present in all source
configurations:
first_matched_columns (optional)
the columns used for the reverse lookup. Any column having the search term will be a reverse
lookup result.
format_columns (optional)
a mapping between result fields and a format string. The new key will be added to the result, if
this name already exists in the result, it will be replaced with the new value. The syntax is a
python format string. See https://docs.python.org/2/library/string.html#formatspec for a complete
reference.
searched_columns (optional)
the columns used for the lookup. Any column containing the search term substring will be a lookup
result.
unique_column (optional)
This column is what makes an entry unique in this source. The unique_column is used to build
the uid that is passed to the list method to fetch a list of results by unique ids. This is
necessary for listing and identifying favorites.
The XiVO dird architecture uses plugins as extension points for most of its
job. It uses stevedore to do the plugin
instantiation and discovery and ABC
classes to define the required interface.
Plugins in xivo-dird use setuptools’ entry points. That means that installing a
new plugin to xivo-dird requires an entry point in the plugin’s setup.py. Each
entry point’s namespace is documented in the appropriate documentation
section. These entry points allow xivo-dird to be able to discover and load
extensions packaged with xivo-dird or installed separately.
Each kind of plugin does a specific job. There are three kinds of plugins in
dird.
Back-ends are used to query directories. Each back-end implements a way to query
a given directory. Each instance of a given back-end is called a source. Sources
are used by the services to get results from each configured directory.
Given one LDAP back-end, I can configure a source from the LDAP at alpha.example.com and another
source from the other LDAP at beta.example.com. Both of these sources use the LDAP back-end.
Service plugins add new functionality to the dird server. These functionalities
are available to views. When loaded, a service plugin receives its configuration
and a dictionary of available sources.
Some service examples that come to mind include:
A lookup service to search through all configured sources.
A reverse lookup service to search through all configured sources and return a
specific field of the first matching result.
The following example adds a service that will return an empty list when used.
dummy.py:
1# -*- coding: utf-8 -*- 2 3importlogging 4 5fromxivo_dirdimportBaseServicePlugin 6 7logger=logging.getLogger(__name__) 8 9classDummyServicePlugin(BaseServicePlugin):10"""11 This plugin is responsible fow instantiating and returning the12 DummyService. It manages its life time and should take care of13 its cleanup if necessary14 """1516defload(self,args):17"""18 Ignores all provided arguments and instantiate a DummyService that19 is returned to the core20 """21logger.info('dummy loaded')22self._service=DummyService()23returnself._service2425defunload(self):26logger.info('dummy unloaded')272829classDummyService(object):30"""31 A very dumb service that will return an empty list every time it is used32 """3334deflist(self):35"""36 This function must be called explicitly from the view, `list` is not a37 special method name for xivo-dird38 """39return[]
View plugins add new routes to the HTTP application in xivo-dird, in particular the REST API of
xivo-dird: they define the URLs to which xivo-dird will respond and the formatting of data received
and sent through those URLs.
For example, we can define a REST API formatted in JSON with one view and the same API formatted in
XML with another view. Supporting the directory function of a phone is generally a matter of
adding a new view for the format that the phone consumes.
load(args): set up resources used by the plugin, depending on the config. Typically,
register routes on Flask. Those routes would typically call a service.
args is a dictionary containing:
key config: the section of the configuration file for all views in dict form
key services: a dictionary of services, indexed by name, which may be called from a route
Purpose: present directory entries in JSON format.
Note
For purpose of alphabetic ordering in results, accented character are converted to unaccented.
Field used to order result
Field for ordering is selected based on configuration of view/display.
First non-empty field with type name is used. If there is no relevant value available, the result goes to end.
Relevance of results in lookup
Lookup results are ordered in way to prefer more relevant results:
No HTTP authentication is tried when phonebook_username or phonebook_password are empty.
phonebook_password (optional)
the password to use in HTTP requests.
phonebook_timeout (optional)
the HTTP request timeout, in seconds.
Defaults to 1.0.
To be able to access the phone book of a remote XiVO, you must create a web services access user
(Configuration ‣ Web Services Access) on the remote XiVO.
Purpose: search directory entries among users’ personal contacts
You should only have one source of type personal, because only one will be used to list personal
contacts. The personal backend needs a working Consul installation. This backend works with the
personal service, which allows users to add personal contacts.
In the directory displays (also in the main configuration file of xivo-dird, in the views section), the
following keys are interpreted and displayed in xlet people of the XiVO Client:
title
The title will be shown as a header for the column
type
agent: the field value will be ignored and replaced by an icon showing the status of the
agent assigned to the contact (e.g. green icon for logged agent, red icon for unlogged agent,
…)
callable: a dropdown action on the number field will be added to call the field value.
email: a dropdown action on the number field will be added to send an email to the
field value.
favorite: the boolean field value will be replaced by an icon showing if the status is
favorite (yellow star filled) or not (yellow star empty).
name: a decoration will be added to the field value (typically a color dot) showing the
presence status of the contact (e.g. Disconnected, Available, Away, …)
number: only one number type can be defined per profile. The field value will be:
added a decoration (typically a color dot) showing the status of the phone of the contact
(e.g. Offline, Ringing, Talking, …)
replaced with a button to call the contact with your phone when using the mouse
personal: the boolean field value will be used to show a deletion action for the contact
The web interface does not allow the administrator to specify the unique_column and
unique_column_format. To add these configuration options, add a file to /etc/xivo-dird/sources.d
containing the same name than the directory definition and all missing fields.
Example:
Given an ldap directory source using Active Directory named myactivedirectory:
Add a file /etc/xivo-dird/sources.d/myactivedirectory.yml with the following content to
enable favorites on this source.
name:myactivedirectory# the same name than the directory definitionunique_column:objectGUIDunique_column_format:binary_uuid
Some configuration options are not available in the web interface. To add configuration to a source
that is configured in the web interface, create a file in /etc/xivo-dird/sources.d/ with the key
name matching your web interface configuration and add all missing fields.
Example:
adding a timeout configuration to a CSV web service source
A source is an instance of a back-end. One backend may be used multiples times to query multiple
directories of the same type. For example, I could have the customer-csv and the employee-csv
sources, each using the CSV back-end, but reading a different file.
xivo-dird-phoned is an interface to use directory service with phone. It offers a simple REST
interface to authenticate a phone and search result from XiVO dird.
xivo-dird-phoned is used through HTTP requests, using HTTP and HTTPS. Its default port is 9498
and 9499. As a user, the common operation is to search through directory from a phone. The phone
need to send 2 informations:
xivo_user_uuid: The XiVO user uuid that the phone is associated. It’s used to search
through personal contacts (see personal).
profile: The profile that the user is associated. It’s used to format results as configured.
Note
Since most phones dont’t support HTTPS, a small protection is to configure
authorized_subnets in Configuration Files or in Services ‣
General settings ‣ Phonebook ‣ Hosts
Keeping records of personal communications for long periods may be subject to local legislation, to
avoid personal data retention. Also, keeping too many records may become resource intensive for the
server. To ease the removal of such records, xivo-purge-db is a process that removes old log
entries from the database. This allows keeping records for a maximum period and deleting older ones.
By default, xivo-purge-db removes all logs older than a year (365 days). xivo-purge-db is run
nightly.
Note
Please check the laws applicable to your country and modify days_to_keep (see below)
in the configuration file accordingly.
After an execution of xivo-purge-db, postgresql’s Autovacuum Daemon should perform a
VACUUM ANALYZE automatically (after 1 minute). This command marks memory as reusable but does
not actually free disk space, which is fine if your disk is not getting full. In the case when
xivo-purge-db hasn’t run for a long time (e.g. upgrading to 15.11 or when
days_to_keep is decreased), some administrator may want to perform
a VACUUM FULL to recover disk space.
Warning
VACUUM FULL will require a service interruption. This may take several hours depending
on the size of purged database.
In the case you want to keep archives of the logs removed by xivo-purge-db, you may install plugins
to xivo-purge-db that will be run before the purge.
XiVO does not provide any archive plugin. You will need to develop plugins for your own need. If you
want to share your plugins, please open a pull request.
Each plugin is a Python callable (function or class constructor), that takes a dictionary of
configuration as argument. The keys of this dictionary are the keys taken from the configuration
file. This allows you to add plugin-specific configuration in /etc/xivo-purge-db/conf.d/.
The following example will be save a file in /tmp/xivo_purge_db.sample with the following
content:
Save tables before purge. 365 days to keep!
1sample_file='/tmp/xivo_purge_db.sample'23defsample_plugin(config):4withopen(sample_file,'w')asoutput:5output.write('Save tables before purge. {0} days to keep!'.format(config['days_to_keep']))
XiVO has many running services. To restart the whole stack, the xivo-service command can
be used to make sure the service is restarted in the right order.
If xivo-upgrade fails or aborts in mid-process, the system might end up in a faulty condition. If in
doubt, run the following command to check the current state of xivo’s firewall rules:
iptables-nvL
If, among others, it displays something like the following line (notice the DROP and 5060):
00DROPudp--**0.0.0.0/00.0.0.0/0udpdpt:5060
Then your XiVO will not be able to register any SIP phones. In this case, you must delete the DROP
rules with the following command:
iptables-DINPUT-pudp--dport5060-jDROP
Repeat this command until no more unwanted rules are left.
If this option is true, when xivo-sysconfd receives a request to reload the dialplan for
example, it will wait for the dialplan reload to complete before replying to the request.
When this option is false, xivo-sysconfd reply to the request immediately.
By default, this option is set to false to speed up some operations (for example, editing a user from the
web interface or from xivo-confd), but this means that there will be a small delay (up to a few
seconds in the worst case) between the time you create your user and the time you can dial
successfully its extension.
After any clean installation of XiVO, it must be initialized through a program called wizard.
Wizard is usually passed through the web interface, but there is another way - through a REST API.
You can pass the wizard with a single request to the API, by providing a specific JSON body as argument.
You can use the swagger found on XIVO_IP/api > xivo_confd > wizard to send the POST request.
By default the XiVO appliance handles the system configuration (network interfaces, nameservers etc.).
If handle_system_conf is set to false when launching the wizard, then the XiVO will not touch the system configuration.
It will not touch/change:
/etc/hosts
/etc/hostname
/etc/mailname
/etc/network/interfaces
/etc/postfix/canonical
/etc/postfix/main.cf
/etc/resolv.conf
All the settings passed to the wizard API will only be set in the XiVO db, but will not be applied on the system.
Warning
Beware, though, that even if you run the wizard with handle_system_conf to false the system configuration will still be accessible via the webi.
If you change it there and then click on Apply network configuration this will touch/change the system configuration.
If set to true, after the wizard is finished, all executable scripts in directory /etc/xivo/wizard.d are going to be run.
Those scripts must be runnable by xivo-confd (file has permission set to ‘x’ for www-data) plus any necessary right to perform their additionnal actions.
The scripts are run in ascii order (0-9, A-Z, a-z). In case of unsuccessful run,
an exception is raised and all non-finished scripts are stopped. You can then find the failing script’s output in xivo-confd log.
Another exception is raised if the directory /etc/xivo/wizard.d doesn’t exist.
Specifically this /var/lib/xivo/sounds/recordings directory is synchronized both ways:
from Main to each MDS
and then from each MDS to Main
Warning
Because of the both ways sync, it means that the deletion of files in this folder won’t be taken into account.
Deleting a file will delete it on (for example) the Main, but during next sync, it will be retrieved back from the MDS.
If you want to delete/clean this folder you currently need to:
Files in the above listed folders prefixed with xds_overridewon’t be synchronized.
Note
For example if you create on the XiVO Main the file
/etc/asterisk/extensions_extra.d/xds_override_mydialplan.conf,
it won’t be synchronized to the other MDS.
Files in /etc/asterisk/extensions_extra.d/ are not overriden on MDS. It means that if you create on MDS1 a file in /etc/asterisk/extensions_extra.d/ it will remain on MDS1 (as long as the filename is not the same as one on the XiVO Main).
The HA solution in XiVO makes it possible to maintain basic telephony
function whether your main XiVO server is running or not. When running a XiVO HA cluster, users are
guaranteed to never experience a downtime of more than 5 minutes of their basic telephony service.
The HA solution in XiVO is based on a 2-nodes “master and slave” architecture. In the normal
situation, both the master and slave nodes are running in parallel, the slave acting as a “hot
standby”, and all the telephony services are provided by the master node. If the master fails or
must be shutdown for maintenance, then the telephony devices automatically communicate with the
slave node instead of the master one. Once the master is up again, the telephony devices failback to
the master node. Both the failover and the failback operation are done automatically, i.e. without
any user intervention, although an administrator might want to run some manual operations after
failback as to, for example, make sure any voicemail messages that were left on the slave are copied
back to the master.
When you upgrade a node of your cluster, you must also upgrade the other so that
they both are running the same version of XiVO. Otherwise, the replication might not work
properly.
You must configure the HA in the Web interface
(Configuration ‣ Management ‣ High Availability page).
You can configure the master and slave in whatever order you want.
You must also run xivo-sync-i on the master to setup file synchronization. Running xivo-sync-i will create a passwordless SSH key on the master, stored under the /root/.ssh directory,
and will add it to the /root/.ssh/authorized_keys file on the slave.
Note
If you want to try the ssh logging as advised by the ssh-copy-id script, you must select
the new key to be used by ssh: ssh-i/root/.ssh/xivo_id_rsaroot@<slave_ip>
The following directories will then be rsync’ed every hour:
/etc/asterisk/extensions_extra.d
/etc/xivo/asterisk
/var/lib/asterisk/agi-bin
/var/lib/asterisk/moh
/var/lib/xivo/certificates
/var/lib/xivo/sounds/acd
/var/lib/xivo/sounds/playback
Warning
When the HA is configured, some changes will be automatically
made to the configuration of XiVO.
SIP expiry value on master and slave will be automatically updated:
min: 3 minutes
max: 5 minutes
default: 4 minutes
Services ‣ IPBX ‣ General Settings ‣ SIP Protocol
The provisioning server configuration will be automatically updated in order to allow
phones to switch from XiVO power failure.
Configuration ‣ Provisioning ‣ Template Line ‣ Edit default
Warning
Do not change these values when the HA is configured, as this may cause problems.
These values will be reset to blank when the HA is disabled.
Important
For the telephony devices to take the new proxy/registrar settings
into account, you must resynchronize the devices
or restart them manually.
Queue logs and CELs are not replicated from the master node to the slave. Instead, both servers have their own event data.
Thanks to it you can install DB Replic on slave and run it in a special HA mode to replicate only queue logs and CELs to XiVO CC:
Edit the /etc/docker/xivo/custom.env file on slave:
Set REPORTING_DB_HOST address
Set ELASTICSEARCH address
Set IS_HA_SLAVE=true
Create log directory /var/log/xivo-db-replication with owner daemon:daemon
Install the configuration package: apt-getinstallxivocc-docker-components
4 scripts are used to manage services and data replication.
xivo-master-slave-db-replication<slave_ip> is used on the master to replicate the master’s
data on the slave server. It runs on the master.
xivo-manage-slave-services{start,stop} is used on the slave to start, stop monit and asterisk.
The services won’t be restarted after an upgrade or restart.
xivo-check-master-status<master_ip> is used to check the status of the master and enable or
disable services accordingly.
xivo-sync is used to sync directories from master to slave.
Since DHCP parameters are replicated, Master and Slave node MUST be on the same VoIP network.
When the master node is down, some features are not available and some behave a bit
differently. This includes:
Call history / call records are not recorded.
Voicemail messages saved on the master node are not available.
Custom voicemail greetings recorded on the master node are not available.
Phone provisioning is disabled, i.e. a phone will always keep the same configuration, even after
restarting it.
Phone remote directory is not accessible, because provisioned IP address points to the master.
Note that, on failover and on failback:
DND, call forwards, call filtering, …, statuses may be lost if changed recently.
If you are connected as an agent, then you might need to reconnect as an agent
when the master goes down. Since it’s hard to know when the master goes down,
if your CTI client disconnects and you can’t reconnect it, then it’s a sign
the master might be down.
Additionally, only on failback:
Voicemail messages are not copied from the slave to the master, i.e. if someone
left a message on your voicemail when the master was down, you won’t be able to
consult it once the master is up again.
More generally, custom sounds are not copied back. This includes recordings.
Here’s the list of limitations that are more relevant on an administrator standpoint:
The master status is up or down, there’s no middle status. This mean that if Asterisk is crashed
the XiVO is still up and the failover will NOT happen.
This is useful if you have one or more ISDN lines (i.e. T1/E1 or T0 lines) that you want to use
whatever the state of your XiVO HA cluster. To use a berofos within your XiVO HA
installation, you need to properly configure both your berofos and your XiVOs,
then the berofos will automatically switch your ISDN lines from your master node to
your slave node if your master goes down, and vice-versa when it comes back up.
You can also use a Berofos failover switch to secure the ISDN provider lines
when installing a XiVO in front of an existing PBX.
The goal of this configuration is to mitigate the consequences of an outage of the XiVO : with this
equipment the ISDN provider links could be switched to the PBX directly if the XiVO goes down.
XiVO does not offer natively the possibility to configure Berofos in this failover mode.
The Berofos Integration with PBX section describes a workaround.
You can then connect your berofos to your network and power it on. By default, the berofos
will try to get an IP address via DHCP. If it is not able to get such address from a DHCP
server, it will take the 192.168.0.2/24 IP address.
Note
The DHCP server on XiVO does not offer IP addresses to berofos devices by default.
Next step is to create the /etc/bnfos.conf file via the following command:
bnfos--scan-x
If no berofos device is detected using this last command, you’ll have to explicitly specify the IP
address of the berofos via the -h option:
bnfos--scan-x-h<berofosip>
At this stage, your /etc/bnfos.conf file should contains something like this:
This, among other things, disable the watchdog. The switching from one relay mode to the other will
be done by the XiVO slave node once it detects the master node is down, and vice-versa.
Finally, you can make sure everything works fine by running the xivo-berofos command:
xivo-berofosmaster
The green LEDs on your berofos should be lighted on ports A and B.
It’s possible to use more than 1 berofos with XiVO.
For each supplementary berofos you want to use, you must first configure it properly
like you did for the first one. The only difference is that you need to add a berofos
declaration to the /etc/bnfos.conf file instead of creating/overwriting the
file. Here’s an example of a valid config file for 2 berofos:
Use the following only if you want to use “Least Recent” call distribution strategy and
that outbound agent calls have to be taken into account by the distribution strategy.
By default, when your agents process incoming and outgoing calls, the call distribution will not take into account agents
which are in outgoing calls in the least recent call strategy and at the end of an outgoing call there is no wrapup.
So an agent can be distributed just after an outgoing calls even if another agent is free for a longer time, because the
outgoing call is not taken into account by the distribution strategy.
You will find below how to improve that.
XiVO-CC agent can make outgoing calls through an outgoing queue. This brings the statistics and
supervision visualization for outgoing ACD calls. However, some special configuration steps are
required. The outgoing calls must be dialed from CC Agent application to use this feature.
If the agent dials an outbound call of more than 6 digits (default) you should see the internal queue statistics updated.
The agent’s state should be “(in call)” for ongoing call and when the call ends, the number of taken calls should be incremented:
Once done, calls requested by an agent through the Cti.js with more than 6 digits are routed via
the outgoing queue. You can change the number of digits using the parameter xuc.outboundLength
in the XuC’s configuration.
When configuring external service as authentication provider, you may have trouble to login if the external system is slow. To overcome this issue, you can increase the default timeout (5000 milliseconds default) by setting the LOGIN_TIMEOUT_MS parameter in the custom.env of your xivocc installation. This value is the delay in milliseconds before aborting a login attempt.
Edit file /etc/docker/xuc/xuc.conf with the following content:
include "application.conf"authentication {ldap {managerDN="uid=company,ou=people,dc=company,dc=com"managerPassword="xxxxxxxxxx"url="ldap://ldap.company.com:389"searchBase="ou=people,dc=company,dc=com"userSearchFilter="uid=%s"}}
Where
managerDN is the LDAP user name of a user with read rights on the whole LDAP (at least the part which contains the users)
managerPassword is the password for this user
url is the URL to access the customer LDAP: [ldap|ldaps]://LDAP_HOST:LDAP_PORT (N.B. you MUST specify the port. Usually 389 for ldap and 636 for ldaps). Example:
to use LDAP ldap://10.32.5.6:389
to use LDAP s: ldaps://ldap.corp.com:636 - see also Note for LDAPs
searchBase is the LDAP OU where to look for users
userSearchFilter is the LDAP filter to search for user by a given login (i.e. the filter to search by login)
Then customize the docker-xivocc.yml file to use this xuc.conf configuration by adding a volume and an environment variable to specify the alternate config file location
As said above to connect to LDAP with a TLS/SSL connection you just need to put ldaps in the url of the ldap authentication configuration.
Then it should work out of the box if the LDAP server uses a certificate signed by a known Certificate Authority of the xucserver JDK.
If the certificate used by the customer LDAP server is not signed by a known Certificate Authority then you need to do the following:
Note
You’re probably in this case if you get the following error in the xucserver log when someone is trying to log in:
play.api.UnexpectedException:Unexpectedexception[AuthenticationDriverException:UnexpectedauthenticationprobleminLdapDrivermodule,error:Anerroroccurredwhileattemptingtoconnecttoserverldap.test.avencall.com:636:IOException(LDAPException(resultCode=91(connecterror),errorMessage='An error occurred while attempting to establish a connection to server ldap.test.avencall.com/10.32.0.1:636:SSLHandshakeException(PKIXpathbuildingfailed:sun.security.provider.certpath.SunCertPathBuilderException:unabletofindvalidcertificationpathtorequestedtarget),ldapSDKVersion=6.0.0,revision=524c20f3bbcc0d83fb56b9e136a2fd3a7f60437d'))]
The customer needs to give you the fullchain certificate file used by the LDAP server (in the following we will refer to it as CUSTOMER_LDAP_CERT),
Copy CUSTOMER_LDAP_CERT file to the xucserver host,
Then copy the CUSTOMER_LDAP_CERT file inside the xucserver container:
To enable Kerberos authentication and single sign on feature, you need to have an existing Kerberos infrastructure with a
Key Distribution Center and a Ticket Granting Service. You need to be able to create a service, construct a kerberos server configuration and export a keytab to perform the following configuration. This service must be on the kerberos realm used by your users and must match the dns name of the server hosting the XUC server (or the nginx reverse proxy server if you use one). For example, assuming you have a realm named MYDOMAIN, you can create a service named HTTP/xuc.mydomain and a dns entry for xuc.mydomain pointing the server hosting the XUC.
Warning
The created domain name must be trusted by the user’s browser.
The bash commands detailed here are for demonstration only and needs to be adapted to your specific environment. It shows how to create a service for the XUC Server named HTTP/xuc, associated to the example realm mydomain.
Only the following encryption types are supported by XiVOCC:
Copy the previously generated xuc.keytab keytab file to the server hosting the XUC docker container, for example: /etc/docker/kerberos/xuc.keytab.
Create or edit the file /etc/krb5.conf on the server hosting the XUC docker container and change settings according to your kerberos environment. For example, the file may contain (name and ip addresses must match your kerberos environment):
Edit the docker compose file /etc/docker/compose/docker-xivocc.yml to add the following configuration in the xuc section (file name, service name, password may differ on your setup):
Enable SingleSignOn on the Agent, Manager, Web and Desktop application interface. Change the value of the following environment variables in the /etc/docker/compose/custom.env:
To enable CAS authentication and single sign on feature, you need to have an existing CAS infrastructure. You need to be able to create a service for the XiVOCC environment.
Warning
The CAS authentication server must be accessible from the user and the server hosting the XiVOCC containers.
CAS Server users’ username must match the XiVO username to allow login on the XiVOCC applications.
The CAS server must support at least CAS Protocol version 2.0.
Edit the docker compose file /etc/docker/compose/docker-xivocc.yml to add the following configuration in the xuc section (use your CAS server URL instead of https://cas-server.example.org/cas and set CAS_LOGOUT_ENABLE to true if you want to logout from CAS when logging out from the application):
To enable OIDC authentication and single sign on feature, you need to have an existing OpenID Connect 1.0 infrastructure. You need to be able to create a realm and a client for the XiVOCC environment.
Warning
The OIDC authentication server must be accessible from the user and the server hosting the XiVOCC containers.
OIDC Server users’ username must match the XiVO username to allow login on the XiVOCC applications.
Audience field in access_token must contain your clientId
Edit the docker compose file /etc/docker/compose/docker-xivocc.yml to add the following configuration in the xuc section (use your OIDC server URL instead of https://oidc-server.example.org/auth/realms/myrealm and set ENABLE_OIDC to true if you want to use this authentication as default one):
OIDC_AUDIENCE : to define additional check on aud access_token field, default is set to OIDC_CLIENT_ID
OIDC_USERNAME_FIELD : to define which field in access_token to use to map XiVO username , default is preferred_username
OIDC_LOGOUT_ENABLE : (this option is only compatible with Keycloak server < 18) to define if logging out of the XiVO application will also logout the user from the SSO, default is set to false
If you configured another kind of authentication, like Login Timeout Configuration or Kerberos Authentication for example, you can enforce this authentication mechanism by preventing fall back on the XiVO authentication mechanism. In order to achieve that, you need to perform the following configuration.
You need to include in the docker-xivocc.yml file a link to a specific configuration file by adding in xuc section a specific volume
and an environment variable to specify the alternate config file location
Edit in /etc/docker/xuc/ folder a configuration file named xuc.conf to disable the xivo based authentication:
include "application.conf"authentication {xivo=""}
Recreate the containers according to the new configuration : xivocc-dcompup-d
Allowing xuc user to login to API or Applications
By default, the ‘xuc’ user can only be used internaly by the xucserver to connect to the xivo. We strongly advise you shouldn’t change this behavior but if you need to enable it, you can do it by setting the following variable in the custom.env file of your xivocc server.
You can check the server certificate chain by using the following web site https://www.ssllabs.com/ssltest/analyze.html which will warn you if there is an error with the certificate (Chainissues-Incomplete).
When a client application (browser or mobile application) checks a certificate for a web site, it checks the received certificate is issued by a known certificate authority and matches the web site domain name. But sometimes, the certificate is not issued by a root certificate authority but by an intermediate authority.
Here is an example of a such a certificate chain:
GeoTrust Global CA
|--> RapidSSL SHA256 - CA - G3
|--> *.company.com
The possible problem here is that even if the browser knows the root authority, it is unaware of the intermediate one. The solution is to create a bundle of the complete certificate chain by concatenating the certificates of all parties (root, intermediate & site). Please see http://nginx.org/en/docs/http/configuring_https_servers.html#chains for more information.
If using an HTTPS connection for the XiVO Mobile Assistant, you must use a trusted certificate with a complete certification chain, see Install trusted certificate for nginx.
This feature can be disabled by changing showRecordingControls option in file application.conf.
You can also set the environnment variable SHOW_RECORDING_CONTROLS to false for your xucmgt container in /etc/docker/compose/custom.env file. When disabled the recording status is not displayed any more
By using the showQueueControls option in application.conf, you may allow an agent to enter or leave an activity.
You can also use SHOW_QUEUE_CONTROLS environment variable in /etc/docker/compose/custom.env file.
You can configure a default queue for dissuasion by setting the queue name in defaultQueueDissuasion in application.conf.
This option once set, will show the queue in the dissuasion dropdown.
You can also use QUEUEDISSUASION_DEFAULT_QUEUE environment variable in /etc/docker/xivo/custom.env file on the XiVO PBX and restart the services with xivo-dcompup-d.
To see/change the dissuasion destination via the CC Agent or CC Manager, a XiVO User must have a supervisor right with Update dissuasion access.
To do this a XiVO Administrator must connect to the configmgt (https://XIVO_IP/configmgt) and configure the user with:
You can configure notifyOnHold (in seconds)) in application.conf, this option once set, will trigger a popup and a system notification to user if he has a call on hold for a long time.
You can also use NOTIFY_ON_HOLD environment variable in /etc/docker/compose/custom.env file.
You can configure XiVO to have the following scenario:
The agent person leaves temporarily his office (lunch, break, …)
He sets his presence in the CCAgent to the according state
The agent will be automatically set in pause and his phone will not ring from
queues
He comes back to his office and set his presence to ‘Available’
The pause will be automatically cancelled
By default the pause action from the agent cannot be specified with a specific cause such as Lunch Time, or Tea Time. To be able to use a specific cause,
you will have to define new Presences in the cti server configuration.
You must define pause status with action Activate pause to all queue to true, to be able to pause agent on all the queues he is working on.
Note
Optional You can edit ready presence defined with an action Disable pause to all queue to fallback to be available whenever the agent reconnects back to CCAgent. (for example, you closed the webpage, or did a F5 refresh). Once you reconnect you will be put in ready state.
By default, if you don’t add option to ready state, you will reconnect with last presence state known.
When this presences are defined, you must restart the xuc server to be able to use them in ccagent, these presences will also be
automatically available in CCmanager and new real time counters will be calculated.
Presence from ready to pause
Presence from pause to ready
Note
Presence color are not taken into account in the CC Agent (or CC Manager) application.
They all will be displayed in Red.
Behavior was changed in 2017.LTS1 (see 2017.LTS1 release notes in Release Notes)
By default, CCManager access is authorized only for users with Administrateur or Superviseur rigths (as defined in the
Configuration Management server).
If required, you can authorize all users to connect to the CCManager interface by setting the ENFORCE_MANAGER_SECURITY environment variable to false in the
/etc/docker/compose/custom.env file:
...ENFORCE_MANAGER_SECURITY=false
Then you need to recreate the xucmgt container with xivocc-dcompup-d.
Then each user will be able to log in the CCManager. Otherwise, each user that wants to connect to the CCManager will need to have a Administrateur or Superviseur profile in the Configuration Management server.
By default when a supervisor spies on an agent - see Agents actions - the agent is only warned via its CC Agent Call control listen icon.
You can change the behavior to warn the agent when spied swith a small beep and/or a function key lit on its deskphone.
To do this, set the ENABLE_CHANSPY_BEEP environment variable to true in the /etc/docker/compose/custom.env file:
The first step is to configure the link towards the Recording Server by running the configuration script:
xivocc-recording-config
During the configuration, you will be asked for :
the Recording Server IP (e.g. 192.168.0.2)
the XiVO PBX name (it must not contain any space or “-” character).
If you configure more than one XiVO PBX on the same Recording Server, you must give a different name to each of them.
After having configured the recording, you have to enable it in the Queue’s configuration or via sub-routines. See below.
To enable recording on a queue, go to Services ‣ Contact Center ‣ Queues and edit the queue.
Then, in the recording section:
Recording mode set it to Recorded or Recorded on demand
Recorded: call will be recorded
Recorded on demand: recording starts in paused state and can be activated by the agent (see agent recording configuration)
Activate check it for the recording mode to be active
You need to check the Activate parameter for the recording to be enabled.
When Activate is checked, the recording will be enabled according to the mode selected.
Enable the call recording for incall 0123456789 by editing it via the XiVO PBX web interface
and set the field Pre-process subroutine to xivocc-incall-recording
By default recording is stopped when a call is transferred to a queues in Not Recorded mode (see the feature description: Automatic Stop/Start Recording On Queues).
This can be deactivated by adding ENABLE_RECORDING_RULES environment variable to the xuc section of your docker-xivocc.yml file:
Recording files are automatically deleted after the configured time (set during installation, see Installation).
However you can mark a recording to be deleted before the configured expiration time by attaching a specific data to the call you want to remove the recording.
To do this, use the Attach call data API with the following body:
Recording can be enabled on a gateway instead of the XiVO PBX where the users, queues and other objects are configured. This architecture will allow to off-load the recording process to a gateway server.
Note that in this architecture not all the recording features are available - see Recording On Gateway Features section.
Important
This page describes the case when recording is activated on the XiVO Gateway.
If you want to configure it on the XiVO PBX you MUST follow the Recording guide.
Beware that you cannot use both.
The first step is to configure the link towards the Recording Server by running the configuration script:
xivocc-recording-config
During the configuration, you will be asked for :
the Recording Server IP (e.g. 192.168.0.2)
the XiVO Gateway name (it must not contain any space or “-” character).
If you configure more than one XiVO PBX on the same Recording Server, you must give a different name to each of them.
After having configured the recording, you have to enable via sub-routines. See below.
When the recording is activated on the XiVO Gateway you can activate the Recording Control feature by following this specific procedure :
Allow the xucserver to connect to your XiVO Gateways:
Copy the file /etc/asterisk/manager.d/02-xivocc.conf from the XiVO PBX to the same folder on the gateway.
Configure the XiVO Gateway as a Media Server
On your XiVO PBX, add your XiVO Gateway as a Media Server in Configuration ‣ Media servers
Important
After this step the xucserver will try to connect to the XiVO Gateway asterisk AMI
On your XiVO PBX, configure the provider trunks: you need to add on your XiVO PBX the same provider trunk that is already
created on your XiVO Gateway BUT with selecting, for the field Media Server the XiVO Gateway you added.
Data are replicated almost instantaneously with the db_replic service. See also the Replication schema.
To see replication status open /var/log/xivo-db-replication/xivo-db-replication.log on XiVO.
The information about the last replicated id is lost when the Logstash container is recreated
(e.g. when upgrading to another LTS). In this case Logstash re-replicates the last 7 days of data.
Note that as the data are already stored in Elasticsearch, no progress will be visible and no new data will appear
for few minutes.
Since Helios, Elasticsearch’s default memory is set to 1.5 GB (but it actually uses more memory, something around 500 MB up to the limit).
You are able to override this value by setting the ES_JAVA_OPTS variable in the /etc/docker/compose/custom.env file on XiVO CC.
You can choose your values as shown below (Xms and Xmx must be the same):
ES_JAVA_OPTS=-Xms3g-Xmx3g or
ES_JAVA_OPTS=-Xms2500m-Xmx2500m
Warning
To apply the configuration you must run xivocc-dcompup-d.
Warning: This will recreate the elasticsearch container. Therefore you will loose all data (kibana dashboard included).
So you MUSTbackup your Kibana configuration beforehand.
Call history by default shows the last 7 days. You can change it by setting the CALL_HISTORY_NB_OF_DAYS environment variable to a specific number of days in the /etc/docker/compose/custom.env file.
Warning
Note that setting this to a large number of days may slow down the solution.
Currently all web applications are translated in French if the locale of the browser (or the OS lang for desktop application) is not found.
You can change, for example to fallback to english if the locale is not known by XiVO.
To do so, you need to set APP_LANG_FALLBACK in XiVO CC /etc/docker/compose/custom.env file with one of the following value:
To enable External Directory feature you need to configure it in the /etc/docker/compose/custom.env file:
EXTERNAL_VIEW_URL=https://myxivocc/externaldir
Note
When EXTERNAL_VIEW_URL is set, it will be displayed in both UC Assistant and CC Agent
Warning
Take care of the following restrictions:
The EXTERNAL_VIEW_URL must be seen as hosted by XiVO CC platform (otherwise it won’t open because of CORS restriction).
You MUST use the same HTTP protocol to access the CC application (UC Assistant or CC Agent) AND to access the external view.
For example, if you access the application over HTTPS, you must access the external view over HTTPS too (to the avoid Mixed Content errors).
The external URL MUST NOT have the ‘X-Frame-Options’ to ‘sameorigin’, else the feature will not work (e.g. you can’t use google.com as directory…).
For security reasons, we strongly recommend to not change this option (i.e. to not raise the credential lifetime).
This warning applies even more if you are connecting UC application through the XiVO Edge solutions (i.e. when the UC applications
are opened on the Internet).
The default validity period for authentification credentials is one hour. This credential is automatically renewed while using the assistants.
This is also the period during which you do not have to enter your password when reconnecting to the assistants.
This duration in seconds can be configured in the /etc/docker/compose/custom.env file:
To pre-fill email when clicking on an email link of XiVO users search results (see UC Assistant Search section) you need to create the /etc/docker/xucmgt/email.tpl file on XiVO CC server:
This template must be in a Json valid format and must contain the two following fields:
field
Description
subject
Pre-filled text for email subject
body
Pre-filled text for email body
The template text can contain parameters that will be automatically replaced by actual value when clicking on email link. Format to include in text is {parameter}.
If the replacement is not possible the parameter will be replaced by a default place holder value.
Parameter
Description
Default value
callernum
The ongoing call caller phone number
##NUMBER##
dstname
The full name of search result associated to this email
##NAME##
Here is a sample of a valid email template:
{"subject":"Information about missed call","body":"Hello {dstname}, someone tried to reach you. He wants to be called back on {callernum}."}
Warning
Take care of the following limitations:
Email display must be configured for directory serach (see Directories and Views)
This features relies on the html mailto: tag therefore:
an email client must be configured for the email to be sent
beware of the URI maximum length for browser: the subject and body will be appended in a mailto: tag to the email address.
Beware that there may be some limitations on the URI size (2000 characters might be good maximum
as you can see in this stackoverflow post)
Template will apply to all users of the system on all applications (UC Assistant, CC Agent, Switchboard)
No carriage return can be put in the text template (email body will be only on 1 line)
It is possible to display customer information in an external web application using Xivo sheet mecanism.
Go to Services > CTI Server > Sheets > Models to configure a sheet:
Tab General Settings: Give a name
Tab Sheet: You must define a sheet with at least folderNumber and popupUrl fields set:
folderNumber (MANDATORY)
field type = text
It has to be defined. Can be calculated or use a default value not equal to “-”
Note: You could leave “empty” using a / symbol or using a whitespace (in hexadecimal: %20)
popupUrl (MANDATORY)
field type = text
The url to open when call arrives : i.e. http://mycrm.com/customerInfo?folder= the folder number will be automatically
appended at the end of the URL
Additionally to the existing xivo variables, you can also use here the following variables(only available in Web Agent and Desktop Agent):
{xuc-token}: will be replaced by a token used for xuc websocket and rest api, for example http://mycrm.com/customerInfo?token={xuc-token}&folder=
{xuc-username}: will be replaced by the username of the logged on user, for example http://mycrm.com/customerInfo?username={xuc-username}&folder=
multiTab (OPTIONAL)
field type = text
set to the text true to open each popup in a new window.
Then go to Services > CTI Server > Sheets > Events and choose the right events for opening the URL (if you choose two events, url will opened twice etc.)
Example : Using the caller number to open a customer info web page
Define folderNumber with any default value i.e. 123456
on CC Agent application the sheet is opened by default,
on UC Assistant application the sheet is not opened by default.
You can change the behavior with the following sheet variables:
popupUCActivated:
if set to true the sheet will be opened on UC Assistant application
if set to false (default) the sheet won’t be opened on UC Assistant application
popupAgentActivated:
if set to true (default) the sheet will be opened on CC Agent application
if set to false the sheet won’t be opened on CC Agent application
For example, if you want the sheet to only open on UC Assistant application you should add in your sheet configuration:
in Services > CTI Server > Sheets > Models:
Tab Sheet add the following definition:
popupAgentActivated
field type = text
display value = false
popupUCActivated
field type = text
display value = true
Note
These variables can also be filled via a dialplan variable value with the UserEvent application and the {dp-...} syntax mechanism.
See the XiVO PBX sheet description.
It is also possible to run an executable using Xivo sheet mecanism. This is only available in the desktop agent and desktop assistant.
Warning
For the executable to be run on a Desktop Assistant in UC mode, you need to activate the Screen popup on UC Assistant
(in CC Agent mode the screen popup doesn’t need to be activated and therefore the executable will be run out-of-the-box).
Go to Services > CTI Server > Sheets > Models:
Tab General Settings: Give a name
Tab Sheet: You must define a sheet with at least runAsExecutable and popupUrl fields set:
popupUrl (MANDATORY)
field type = text
It should contain an executable name accessible by the client user (where the desktop application is) or a full executable path.
runAsExecutable (MANDATORY)
field type = text
Display value true
executableArgs (OPTIONAL)
field type = text
set the argument for the executable.
Then go to Services > CTI Server > Sheets > Events and choose the right events for starting the application.
Example : Run the notify-send command on linux:
Define popupUrl with a display value of notify-send
Define runAsExecutable with a display value of true
Define executableArgs with a display value of caller:{xivo-calleridnum} where the variable xivo-calleridnum will be replaced by the caller phone number.
Do NOT forget to check that XUC_HOST in /etc/docker/compose/custom.env is also configured with the same FQDN as in the certificate, not the IP address.
Using the xivocc-dcomp script, you can control the run of the XiVO CC components:
xivocc-dcomp[command][container]
List of commands:
up-d - run containers
stop - stop containers
restart - restart containers
reload - reload container (only applicable to ``pgxivocc`` and ``nginx``)
If you don’t enter container name, the command applies on all containers.
Use container names without the xivocc_ prefix and _1 suffix.
Warning
Restarting xuc server with active calls may result in some agent’s having incorrect state after the restart. Hang-up of such call will return agent into correct state.
When transfering a call using DTMF (*1) you get an invalid extension error when dialing the
extension.
The workaround to this problem is to create a preprocess subroutine and assign it to the destinations
where you have the problem.
Under Services ‣ IPBX ‣ IPBX configuration ‣ Configuration files add a new file
containing the following dialplan:
[allow-transfer]exten=s,1,NoOp(## Setting transfer context ##)same=n,Set(__TRANSFER_CONTEXT=<internal-context>)same=n,Return()
Do not forget to substitute <internal-context> with your internal context.
Some places where you might want to add this preprocess subroutine is on queues and outgoing calls
to be able to transfer the called person to another extension.
XiVO does not currently support Fax detection. The following describe a workaround to use this
feature. The behavior is to answer all incoming (external) call, wait for a number of seconds (4 in
this example) : if a fax is detected, receive it otherwise route the call normally.
Note
This workaround works only :
on incoming calls towards an User (and an User only),
if the incoming trunk is a DAHDI or a SIP trunk,
if the user has a voicemail which is activated and with the email field filled
XiVO >= 13.08 (needs asterisk 11)
Be aware that this workaround will probably not survive any upgrade.
In the Web Interface and under Services ‣ IPBX ‣ IPBX configuration ‣
Configuration files add a new file named fax-detection.conf containing the following
dialplan:
;; Fax Detection
[pre-user-global-faxdetection]
exten = s,1,NoOp(Answer call to be able to detect fax if call is external AND user has an email configured)
same = n,GotoIf($["${XIVO_CALLORIGIN}" = "extern"]?:return)
same = n,GotoIf(${XIVO_USEREMAIL}?:return)
same = n,Set(FAXOPT(faxdetect)=yes) ; Activate dynamically fax detection
same = n,Answer()
same = n,Wait(4) ; You can change the number of seconds it will wait for fax (4 to 6 is good)
same = n,Set(FAXOPT(faxdetect)=no) ; If no fax was detected deactivate dyamically fax detection (needed if you want directmedia to work)
same = n(return),Return()
exten = fax,1,NoOp(Fax detected from ${CALLERID(num)} towards ${XIVO_DSTNUM} - will be sent upon reception to ${XIVO_USEREMAIL})
same = n,GotoIf($["${CHANNEL(channeltype)}" = "DAHDI"]?changeechocan:continue)
same = n(changeechocan),Set(CHANNEL(echocan_mode)=fax) ; if chan type is dahdi set echo canceller in fax mode
same = n(continue),Gosub(faxtomail,s,1(${XIVO_USEREMAIL}))
In the file /etc/xivo/asterisk/xivo_globals.conf set the global user subroutine to
pre-user-global-faxdetection : this subroutine will be executed each time a user is called:
You can use a Berofos failover switch to secure the ISDN provider lines
when installing a XiVO in front of an existing PBX.
The goal of this configuration is to mitigate the consequences of an outage of the XiVO : with this
equipment the ISDN provider links could be switched to the PBX directly if the XiVO goes down.
XiVO does not offer natively the possibility to configure Berofos in this failover mode.
This section describes a workaround.
Add the following script /usr/local/sbin/berofos-workaround:
#!/bin/bash
# Script workaround for berofos integration with a XiVO in front of PABX
res=$(/usr/sbin/service asterisk status)
does_ast_run=$?
if [ $does_ast_run -eq 0 ]; then
/usr/bin/logger "$0 - Asterisk is running"
# If asterisk is running, we (re)enable wdog and (re)set the mode
/usr/bin/bnfos --set mode=1 -f fos1 -s
/usr/bin/bnfos --set modedef=1 -f fos1 -s
/usr/bin/bnfos --set wdog=1 -f fos1 -s
# Now 'kick' berofos ten times each 5 seconds
for ((i == 1; i <= 10; i += 1)); do
/usr/bin/bnfos --kick -f fos1 -s
/bin/sleep 5
done
else
/usr/bin/logger "$0 - Asterisk is not running"
fi
Add execution rights to script:
chmod+x/usr/local/sbin/berofos-workaround
Create a cron to launch the script every minutes /etc/cron.d/berofos-cron-workaround:
# Workaround to berofos integrationMAILTO=""*/1****root/usr/local/sbin/berofos-workaround
If you observes that your CTI server is sometimes unexpectedly terminating with the following
message in /var/log/xivo-ctid.log:
(WARNING)(main):AMI:CLOSING
Then you might be in the case where asterisk generates lots of data in a short period of time on the
AMI while the CTI server is busy processing other thing and is not actively reading from its AMI
connection. If the CTI server takes too much time before consuming some data from the AMI
connection, asterisk will close the AMI connection. The CTI server will terminate itself once it
detects the connection to the AMI has been lost.
There’s a workaround to this problem called the ami-proxy, which is a process which buffers the AMI
connection between the CTI server and asterisk. This should only be used as a last resort solution,
since this increases the latency between the processes and does not fix the root issue.
To enable the ami-proxy, you must:
Add a file /etc/systemd/system/xivo-ctid.service.d/ami-proxy.conf:
The database and the underlying database cluster used by XiVO is sensitive to the system locale
configuration. The locale used by the database and the database cluster is set when XiVO is
installed. If you change your system locale without particular attention to PostgreSQL, you might
make the database and database cluster temporarily unusable.
When working with locale and PostgreSQL, there’s a few useful commands and things to know:
locale-a to see the list of currently available locales on your system
locale to display information about the current locale of your shell
grep^lc_/etc/postgresql/9.4/main/postgresql.conf to see the locale configuration of your
database cluster
sudo-upostgrespsql-l to see the locale of your databases
the /etc/locale.gen file and the associated locale-gen command to configure the
available system locales
systemctlrestartpostgresql.service to restart your database cluster
the PostgreSQL log file located at /var/log/postgresql/postgresql-9.4-main.log
Note
You can use any locale with XiVO as long as it uses an UTF-8 encoding.
Then this usually means that the locale that is configured in postgresql.conf (here en_US.UTF-8)
is not currently available on your system, i.e. does not show up the output of locale-a. You
have two choices to fix this issue:
either make the locale available by uncommenting it in the /etc/locale.gen file and running
locale-gen
or modify the /etc/postgresql/9.4/main/postgresql.conf file to set the various lc_*
options to a locale that is available on your system
Then this usually means that your database backup has a locale that is not currently available on
your system. You have two choices to fix this issue:
either make the locale available by uncommenting it in the /etc/locale.gen file, running
locale-gen and restarting your database cluster
or if you want to restore your backup using a different locale (for example fr_FR.UTF-8),
then restore your backup using the following commands instead:
Changing the locale (LC_COLLATE and LC_CTYPE) of the database
If you have decided to change the locale of your database, you must:
make sure that you have enough space on your hard drive, more precisely in the file system holding
the /var/lib/postgresql directory. You’ll have, for a moment, two copies of the
asterisk database.
prepare for a service interruption. The procedure requires the services to be restarted twice,
and the system performance will be degraded while the database with the new locale is being
created, which can take a few hours if you have a really large database.
make sure the new locale is available on your system, i.e. shows up in the output of locale-a
Then use the following commands (replacing fr_FR.UTF-8 by your locale):
http.conf - asterisk’s webserver must accept connection from outside, the listen address must be updated, for the sake of
simplicity let’s use 0.0.0.0, you can also pick an address of one of the network interfaces:
The configuration is reloaded by module reload res_rtp_asterisk.so.
WebRTC requires DTLS keys to be generated in /etc/asterisk/keys. If you need to manually generate the DTLS
certificates following instructions on the Asterisk Wiki: https://wiki.asterisk.org/wiki/display/AST/Secure+Calling+Tutorial.
You just need to generate the TLS certificates (first call of ast_tls_cert), other steps are not necessary.
Make sure asterisk can read files by executing: chown-Rasterisk.asterisk/etc/asterisk/keys
XUC overview page available at @XUC_IP:PORT, usually @SERVER_IP:8090. You have to check if the “Internal configuration cache database”
contains agents, queues etc.
XUC sample page available at @XUC_IP:PORT/sample, usually @SERVER_IP:8090/sample. You can use this page to check user login and other
API functions. CCManager, agent and assistant web use functions available on the sample page.
The XUC process exposes some metrics to troubleshoot or monitor the health of the process. Some of these metrics were previously exposed in a sub-page of the XUC overview page. The metrics are not exposed using the JMX technology available in java.
JMX is enabled by default in java but only available on the local machine running the process. Moreover as we are using docker, it’s only available inside the docker container itself. To make it available from the outside of the container and host running the XUC process, you need to explicitely configure it to do so.
In the following configuration, replace
JMX_PORT with the port number where you want to expose the JMX
JMX_HOST by the docker host IP address (not the container one but the IP of the server running docker)
Edit your docker compose file (/etc/docker/compose/docker-xivocc.yml) and change the configuration of the xuc container:
Once restarted you can then use tools to explore the metrics: jconsole, visualvm with MBeans plugin, eclipse,… For example, here are the steps to configure visualvm and explore the JMX metrics:
Alternatively you could integrate a JMX plugin to your running process which allows to gather JMX metrics over HTTP. You need to download jolokia JVM agent from their website: https://jolokia.org/ and transfer the jar file on the server hosting the XUC container (for example in /etc/docker/jolokia/jolokia-jvm-1.6.2-agent.jar).
Then you should change your docker compose configuration for the xuc process in docker-xivocc.yml:
Then restart the XUC process with the new configuration by running the command xivocc-dcompup-dxuc. The JMX metrics are now available over HTTP, see jolokia website for help on available endpoints: https://jolokia.org/documentation.html
Here are some example url to test:
* List all jmx metrics available: curlhttp://JMX_HTTP_HOST:JMX_HTTP_PORT/jolokia/list
* Get metrics of a specific service: curlhttp://JMX_HTTP_HOST:JMX_HTTP_PORT/jolokia/read/services.calltracking:type=AsteriskGraphTracker
You may also find these metrics interesting when troubleshooting the process:
* java.lang.Memory.HeapMemoryUsage: Information about the java heap memory
* java.lang.GarbageCollector: Information about the java garbage collector process
New queue will not appear immediately in CCAgent and CCManager until
the agent or the manager is not relogged to these applications accordingly. The Xuc server restart is not required.
If something goes wrong with the quality of an ongoing call, it will be reflected in live, every 20 seconds, inside the xuc server logs, with the following format:
Both those format include the user as well as the sip call id, so it can be grepped.
It can also be grepped by the type of message, “Audio quality issues” and “Call quality report”.
After experiencing a ‘no space left on device’ and restarting containers, it can sometimes happen
that the data from XiVO is not replicated anymore. The following error can be found only in docker logs of DB Replic:
This error is caused by a lock in liquibase db. Follow the below steps in order to fix the issue:
Warning
This problem should not happen, so you should know what you are doing and not follow this procedure blindly.
Stop db_replic (XiVO), xivo_stats (XiVO CC) and pack_reporting (XiVO CC)
On XiVOCC, enter inside the pgxivocc docker container:
dockerexec-itxivocc_pgxivocc_1/bin/bash
Log on the database as postgres:
su-postgrespsqlxivo_stats
Find if there still is an active lock:
xivo_stats=# select * from databasechangeloglock;id|locked|lockgranted|lockedby----+--------+-------------------------+-----------------------------------------------------------------1|t|2017-04-1015:28:10.684|fe80:0:0:0:42:acff:fe11:8%eth0(fe80:0:0:0:42:acff:fe11:8%eth0)
If so, delete the lock:
xivo_stats=# truncate databasechangeloglock;xivo_stats=# select * from databasechangeloglock;id|locked|lockgranted|lockedby----+--------+-------------+----------1|f||
Live reload configuration permit to reload its configuration on command received from WEBI
(this option is enabled by default).
If you deactivate Live reload, apart from commands to xivo-ctid service, no config update command will be sent to udpate the services configuration.
You must then reload the configuration accordingly.
The table below lists the parameters that will need a manual reload:
Services –> IPBX –> IPBX Settings
Menu
Section
Parameter
Reload command
Users
General
On-Hold Music, Caller ID
sipreload
Lines
all
sipreloaddialplanreload
Services
Enable supervision
dialplanreload
Voicemail
all
voicemailreloadsipreload
Func Keys
TypeCustomized with Supervision activated
dialplanreload + phone reboot
Groups
General
Name, Ring strategy,
User reachability timeout,
Time before retrying a call to a user,
Call a member already in line,
On-Hold Music
queuereloadall
Number
dialplanreload
Users
all
queuereloadmembers
Application
N.A.
N.A.
Call permissions
N.A.
N.A.
No answer
N.A.
N.A.
Schedules
N.A.
N.A.
Voicemails
all
all
voicemailreload
Conference rooms
General
Number, PIN code, Organizer PIN code
dialplanreload
Services –> IPBX –> Call management
Menu
Section
Parameter
Reload command
Incoming calls
all
N.A.
N.A.
Outgoing calls
Exten
all
dialplanreload
Call permissions
all
N.A.
N.A.
Call filters
all
N.A.
N.A.
Call pickups
Interceptors
all
sipreload
Intercepted
all
sipreload
Schedule
all
N.A.
N.A.
Services –> Call center –> Call management
Menu
Section
Parameter
Reload command
Agents
all
all
queuereloadall
Queues
General
Name, Ring strategy, On-Hold Music
queuereloadall
Number
dialplanreload
Announces
all
queuereloadall
Members
all
queuereloadmembers
Application
N.A.
N.A.
No answer
N.A.
N.A.
Advanced
all
queuereloadall
Schedules
N.A.
N.A.
Diversions
N.A.
N.A.
Qualifications
N.A.
N.A.
Agents
all
all
queuereloadall
Queues penalties
all
all
queuereloadall
Skills
all
all
queuereloadall
Skill rules
all
all
queuereloadall
Qualifications
all
N.A.
N.A.
Activate Directmedia with SIP Provider & DTMF RFC 2833
Important
This page describes how to enable Directmedia on your XiVO PBX in the specific following context:
with a SIP Provider authorizing directmedia (or requiring it),
and with this SIP Provider using DTMF according to RFC 2833
Directmedia is an Asterisk feature to optimize network streams.
By default, when asterisk establishes a call between two phones, it establishes the media stream (voice or video RTP stream) via
itself. Then, if A calls B, the media stream goes from A to asterisk and then from asterisk to B:
This is particularly useful when your XiVO PBX and phones are not located on the same site.
In this case, activating Directmedia could dramatically save network bandwidth.
As written in the note above we only cover the case where your SIP Provider will accept media stream directly between your
endpoints and its media gateways.
Also it describes how to configure your system if your SIP Provider accepts DTMF in RFC 2833.
And you must ensure that network routing is working between your different endpoints - as enabling directmedia means that media stream will
flow directly between endpoints (phones, gateways, operators etc.).
Note also that in this context network QoS should be taken into account with great care, but is outside the scope of this
page.
If you have other SIP trunks on your installation, you should verify that the DTMF mode is according to what the endpoint support.
And, as it is not covered in this guide, we recommend that you deactivate directmedia:
Edit the SIP trunk,
In tab Advanced set Redirect media streams to No
In tab Signalling set DTMF to the one supported by the endpoint.
after having un-checked the option Enable call transfer transfer won’t be possible from legacy XiVO Client.
Switchboard: calls towards Switchboard will be without directmedia. Directmedia will be activated on the call after having
been transfered (as the legacy transfer method must be used for Switchboard CTI application)
Jitterbuffer: jitterbuffer must be disabled on your XiVO PBX.
Recording: if the call recording is activated for calls, it will disable Directmedia on these calls.
ChanSpy: listening to an agent (see CCManager application documentation) will disable temporarily the directmedia.
When listening is stopped, media flow will be re-established directly between agent and caller.
When removing a certificate, you should remove all the files related to that
certificates.
Warning
If you remove a certificate that is used somewhere in XiVO, then you need
to manually reconfigure that portion of XiVO.
For example, if you remove the certificate files used for SIP TLS, then you need to
manually disable SIP TLS or asterisk will look for certificate file but it won’t
be able to find them.
The boss secretary filter allow to set a secretary or a boss role to a user. Filters can then be created
to filter calls directed to a boss using different strategies.
The secretary or boss role can be set in the user’s configuration page under the service tab. To use
this feature, at least one boss and one secretary must be defined.
The filter is used to associate a boss to one or many secretaries and to set a ring strategy. The call
filter is added in the Services ‣ IPBX ‣ Call management ‣ Call filters page.
Different ringing strategies can be applied :
Boss rings first then all secretaries one by one
Boss rings first then secretaries are all ringing simultaneously
Secretaries ring one by one
Secretaries are all ringing simultaneously
Boss and secretaries are ringing simultaneously
Change the caller id if the secretary wants to know which boss was initialy called
When one of serial strategies is used, the first secretary called is the last in the list. The order can
be modified by drag and drop in the list.
The call filter function can be activated and deactivated by the boss or the secretary using the
*37 extension. The extension is defined in IPBX services > Extensions.
The call filter has to be activated for each secretary if more than one is defined for a given boss.
The extension to use is *37<callfiltermemberid>.
In this example, you would set 2 FuncKeys*373 and *374 on the Boss.
A more convenient way to active the boss secretary filter is to assign a function key on the boss’ phone
or the secretary’s phone. In the user’s configuration under FuncKeys. A function key can be added
for each secretaries of a boss.
If supervision is activated, the key will light up when filter is activated for this secretary. If a
secretary also has a function key on the same boss/secretary combination the function key’s BLF will be
in sync between each phones.
Warning
With SCCP phones, you must configure a custom FuncKeys.
The call completion feature (or CCSS, for Call Completion Supplementary Services) in XiVO allows for
a caller to be automatically called back when a called party has become available.
To illustrate, let’s say Alice attempts to call Bob.
Bob is currently on a phone call with Carol, though, so Bob rejects the call from Alice
Alice then dials *40 to request call completion.
Once Bob has finished his phone call, Alice will be automatically called back by the system.
When she answers, Bob will be called on her behalf.
This feature has been introduced in XiVO in version 14.17.
when the called party is busy (Call Completion on Busy Subscriber)
when the called party doesn’t answer (Call Completion on No Response)
We have already discussed the busy scenario in the introduction section.
Let’s now illustrate the no answer scenario:
Alice attempts to call Bob.
Bob doesn’t answer the phone. Alternatively, Alice hangs up before Bob has the time to answer the
call.
Alice then dial *40 to request call completion.
When Bob’s phone becomes busy and then is no longer busy, Alice is automatically called back.
When she answers, Bob will be called on her behalf.
The important thing to note here is step #4. Bob’s phone needs to become busy and then no longer
busy for Alice to be called back. This means that if Bob was away when Alice called him, but when he
came back he did not received nor placed any call, then Alice will not be called back.
In fact, in all scenarios, after call completion has been requested by the caller, the called phone
needs to transition from busy to no longer busy for the caller to be called back. This means that
in the following scenario:
Alice attempts to call Bob.
Bob is currently on a phone call, so he doesn’t answer the call from Alice.
Bob finish his call a few seconds later.
Alice then dials *40 to request call completion (Bob is not busy anymore).
Then, for Alice to be called back, Bob needs to become busy and then not busy.
If Alice is busy when Bob becomes not busy, then the call completion callback will only happen
after both Alice and Bob are not busy.
When call completion is active, it can be cancelled by dialing the *40 extension.
Some timers governs the use of call completion. These are:
offer timer: the time the caller has to request call completion. Defaults to 30 (seconds).
busy available timer: when call completion on busy subscriber is requested, if this timer expires
before the called party becomes available, then the call completion attempt will be cancelled.
Defaults to 900 (seconds).
no response available timer: similar to the “busy available timer”, but when call completion on no
response is requested. Defaults to 900 (seconds).
recall timer: when the caller who requested call completion is called back, how long the original
caller’s phone rings before giving up. Defaults to 30 (seconds).
It’s currently impossible to modify the value of these timers in XiVO.
It is not possible to activate call completion in the following two scenarios.
First scenario: Alice tries to call Bob, but Bob has currently reached its “simultaneous calls”
limit. When activating call completion, Alice hears that the call completion can not be activated.
Note
The “simultaneous calls” option is configured per user via the XiVO web interface.
Second scenario: Alice tries to call Bob, but the call is redirected to Charlie.
This occurs when Bob redirects/rejects the call with any of the following:
Unconditional call forwarding towards Charlie
Closed schedule towards Charlie
Call permission forbidding Alice to call Bob
Preprocess subroutine forwarding the call towards Charlie
Call completion will activate and call back for the original called party
Scenario: Alice tries to call Bob, but the call is redirected to Charlie. When activating call
completion, Alice hears that the call completion is activated and eventually Alice is called back to
speak with Bob.
This occurs when Bob redirects/rejects the call with any of the following:
No-answer call forwarding towards Charlie
Busy call forwarding towards Charlie
Call completion will activate and call back for the rerouted called party
Scenario: Alice tries to call Bob, but the call is redirected to Charlie. When activating call
completion, Alice hears that the call completion is activated and eventually Alice is called back to
speak with Charlie.
This occurs when Bob redirects the call with any of the following:
Boss-Secretary filter to the secretary Charlie
Call completion will activate and call back for the original called party but fail to join him
Scenario: Alice tries to call Bob, but the call is redirected to Charlie. When activating call
completion, Alice hears that the call completion is activated and eventually Alice is called back to
speak with Bob. But when Alice answers, Bob is not called. If Alice activates call completion again,
she will hear that the call completion was cancelled.
This occurs when Bob redirects/rejects the call with any of the following:
Do Not Disturb mode
a new call forwarding rule that was applied after Alice activated call completion:
Unconditional call forwarding towards Charlie
Closed schedule towards Charlie
Call permission forbidding Alice to call Bob
Preprocess subroutine forwarding the call towards Charlie
If your XiVO has been installed in version 14.16 or earlier, then this extension is by default
disabled. Otherwise, this extension is by default enabled.
Providers can send the caller number in various formats (e.g. for french national number you could receive 0123456789 or +33123456789 or even 33123456789).
You can change the caller number to adapt to your need. For examples:
you may want to always display incoming numbers in E.164 format (e.g. +33123456789)
or, if you use a prefix to dial outgoing numbers (like a 0), you should add a 0 to the received caller number so you can redial it.
and that the Reverse lookup is done with the caller number after it has been modified
through the rules of this xivo_in_callerid.conf file.
Therefore, if you need to have the Customer Call History (used in CC Agent and Switchboard applications),
then you must void all the rules in this file (i.e. remove the content of the add and strip lines so the caller number is not changed).
But then you must take care that, if you also use the Reverse lookup, the phone numbers in your directory are stored in
the same format than received from the provider (i.e. if your provider sends +33123456789 the phone number must be stored in the
directory as +33123456789).
You can manage call permissions via the
Services ‣ IPBX ‣ Call management ‣ Call permissions
page.
Call permissions can be used for:
denying a user from calling a specific extension
denying a user of a group from calling a specific extension
denying a specific extension on a specific outgoing call from being called
denying an incoming call coming from a specific extension from calling you
More than one extension can match a given call permission, either by specifying more
than one extension for that permission or by using extension patterns.
You can also create permissions that allow a specific extension to be called
instead of being denied. This make it possible to create a general “deny all”
permission and then an “allow for some” one.
Finally, instead of unconditionally denying calling a specific extension,
call permissions can instead challenge the user for a password to be able
to call that extension.
As you can see, you can do a lot of things with XiVO’s call permissions. They
can be used to create fairly complex rules. That said, it is probably
not a good idea to so because it’s pretty sure you’ll get it somehow wrong.
You can only deny internal calls towards users’ extensions.
If you apply a Deny rule towards an extension to a User, it will only work if it is the extension of a user
(or an extension that go through an outgoing call).
It won’t work if the extension is the number of a Queue or a Conference room.
User’s Rightcall Code (Services ‣ IPBX ‣ IPBX Settings ‣ Users under
Services tab) overwrite all password call permissions for the user.
Warning
The extension can be anything but it will only work if it’s the extension of a user or
an extension that pass through an outgoing call. It does not work, for example, if
the extension is the number of a conference room.
Denying a user of a group from calling a specific extension
First, you must create a group and add the user to this group. Note that groups
aren’t required to have a number.
Then,
Add the extension in the extensions list
In the Groups tab, select the group
Denying users from calling a specific extension on a specific outgoing call
Add the extension in the extensions list
In the Outgoing calls tab, select the outgoing call
Note that selecting both a user and an outgoing call for the same call permission
doesn’t mean the call permission applies only to that user. In fact, it means that the
user can’t call that extension and that the extension can’t be called on the specific
outgoing call. This in redundant and you will get the same result by not
selecting the user.
Denying an incoming call coming from a specific extension from calling you
Call permissions on incoming calls are semantically different from the other scenarios
since the extension that you add to the permission will match the extension of the
caller (i.e. the caller number) and not the extension that the caller dialed (i.e.
the callee number).
Add the extension in the extensions list.
In the Incoming calls tab, select the incoming call
Call logs are pre-generated from CEL entries. The generation is done automatically
by xivo-call-logd. xivo-call-logs is also run nightly to generate call logs from
CEL that were missed by xivo-call-logd.
Note
The oldest call logs are periodically removed. See Purge Logs for more details.
Call logs can also be generated manually. To do so, log on to the target XiVO server and run:
xivo-call-logs
To avoid running for too long in one time, the call logs generation is limited to the N last
unprocessed CEL entries (default 20,000). This means that successive calls to xivo-call-logs
will process N more CELs, making about N/10 more calls available in call logs, going further back in
history, while processing new calls as well.
You can specify the number of CEL entries to consider. For example, to generate calls using the
100,000 last unprocessed CEL entries:
Pin code: Protects your conference room with a PIN number. People trying to join the room will be asked for the PIN code.
Organizer Pin Code: This pin code is used to define an organizer for the conference, organizer will have the right to mute
or kick participants with the Conferences monitoring in uc assistant application.
Waiting room: Once this option is checked the users are not able to speak in the room and have to wait the organizer
to join the conference.
Note
You must define a general pin code if you want to be able to organize conferences and use the organizers features.
Don’t play announce for first participant: First user joining will not get any announce.
No incoming notification: Users will not hear incoming announces. Deactivates the sound when user enters / leaves conference.
It also deactivates the name recording feature, but not the announce of number of participants.
Announce number of participants: Announce user(s) count on joining a conference.
Record name and announce when joining and leaving: The user is allowed to record his name that will be heard by the other
conference attendees. Can be reviewed afert record (yes) or not (No Review).
Recording: This conference room is recorded.
Max participants: Define the maximum number of participants, default to 0.
The general options allow the administrator to manage network connections between the CTI server and
the clients.
The section named STARTTLSoptions allows the administrator to enable
encrypted communications between the clients and xivo-ctid and specify the
certificate and private keys to use.
If no certificate and private key is configured, xivo-ctid will use the ones
located in /usr/share/xivo-certs.
Parting options are used to isolate XiVO users from each other. These options
should be used when using the same XiVO for different enterprises.
Context separation is based on the user’s line context. A user
with no line is not the member of any context and will not be able to do
anything with the CTI client.
Note
xivo-dird must be restarted to take into account this parameter.
xivo-ctid uses xivo-auth to authenticate users. The default authentication
backend is xivo_user. To change the authentication backend, add a
configuration file in /etc/xivo-ctid/conf.d with the following content:
auth:backend:backend_name
where backend name is the name of an enabled xivo-authBackends Plugins.
In the Status menu, under Presences, you can edit presences group.
The default presence group is francais. When editing
a group, you will see a list of presences and their descriptions.
To use another presence group, you can edit the CTI profile you are using and select
the appropriate presence group for that profile.
The CTI profiles define which features are made available to a user. You can
configure which profile will be used by a user in the menu IPBX
‣ PBX Settings ‣ Users:
You can also customize the default profiles or add new profiles in the menu
CTI Server ‣ Profiles:
To choose which features are available to users using a profile, you have to
select which Xlets will be available.
The Position attribute determines how the Xlets will be laid out:
dock will display a Xlet in its own frame. This frame can have some options:
Floating means that the frame can be detached from the main window of the CTI
Client.
Closable means that the Xlet can be hidden
Movable means that the Xlet can be moved (either inside the main window or outside)
Scroll means that the Xlet will display a scroll bar if the Xlet is too large.
grid will display a Xlet inside the main window, and it will not be
movable. Multiple grid Xlets will be laid out vertically (the second below
the first).
tab will display a Xlet inside a tab of the Xlet Tabber. Thus the Xlet
Tabber is required and can’t be in a tab position.
The Number attribute gives the order of the Xlets, beginning with 0. The order
applies only to Xlets having the same Position attribute.
Sheets can be defined under Services ‣ CTI Server ‣ Models
in the web interface. Once a sheet is defined, it has to be assigned to an event
in the Services ‣ CTI Server ‣ Events menu.
Model
The model contains the content of the displayed sheet.
Event
Events are actions that trigger the defined sheet. A sheet can be assigned to many events. In
that case, the sheet will be raised for each event.
Sheets allows to list different fields and associated content to be displayed in XivoCC application such as CC Agent.
The information will be automatically laid out in a linear fashion and will be read-only.
xivo- prefix is reserved and set inside the CTI server:
xivo-where for sheet events, event triggering the sheet
xivo-origin place from where the lookup is requested (did, internal, forcelookup)
xivo-direction incoming or internal
xivo-did DID number
xivo-calleridnum
xivo-calleridname
xivo-calleridrdnis contains information whether there was a transfer
xivo-calleridton Type Of Network (national, international)
xivo-calledidnum
xivo-calledidname
xivo-ipbxid (xivo-astid in 1.1)
xivo-directory : for directory requests, it is the directory database the item has been found
xivo-queuename queue called
xivo-agentnumber agent number called
xivo-date formatted date string
xivo-time formatted time string, when the sheet was triggered
xivo-channel asterisk channel value (for advanced users)
xivo-uniqueid asterisk uniqueid value (for advanced users)
db- prefixed variables are defined when the reverse lookup returns a result.
For example if you want to access to the reverse lookup full name, you need to define a field
fullname in the directory definition, mapping to the full name field in your directory. The
{db-fullname} will be replaced by the caller full name. Every field of the directory is
accessible this way.
dp- prefixed ones are the variables set through the dialplan (through UserEvent application)
For example if you want to access from the dialplan to a variable dp-test you
need to add in your dialplan this line (in a subroutine):
You can configure a sheet when a specific event is called. For example if you want to receive a
sheet when an agent answers to a call, you can choose a sheet model for the Link event.
The following events are available :
Dial: When the member’s phone starts ringing for calls on a group or queue
or when the user receives a call
Link: When a user or agent answers a call
Unlink: When a user or agent hangup a call received from a queue
Incoming DID: Received a call in a DID
Hangup: Hangup the call
The informations about a call opens a url on new browser tab.
(Before Electra it was displayed via the XiVO Client on forms called sheets.)
Example: Display a Web page when an agent answers a call
The first step is to assign the URL to a dialplan variable. Go in the
Services ‣ IPBX ‣ Configuration files and create a new file
called setsheeturl.conf. In this file, put the following:
[setsheeturl]
exten = s,1,NoOp(Starting Set Sheet URL)
same = n,Set(SHEET_URL_CTI=http://documentation.xivo.solutions)
same = n,UserEvent(dialplan2cti,UNIQUEID: ${UNIQUEID},CHANNEL: ${CHANNEL},VARIABLE: mysheeturl,VALUE: ${SHEET_URL_CTI})
same = n,Return()
You can replace documentation.xivo.solutions by the URL you want.
The second step is to set the URL when the call is queued. To do that, we will
use a preprocessing subroutine. This is configured in the queue configuration :
go to Services ‣ Call center ‣ Queues and edit the
queue. Set the field Preprocessingsubroutine to setsheeturl (the same
as above).
The third step is to configure the sheet to open the wanted URL. Go to
Services ‣ CTI Server ‣ Sheets ‣ Models and create a new
sheet. It must have a name and at least two fields : one with Field title popupUrl, Default value / and Display value {dp-mysheeturl}, the other
with Field title folderNumber and Display value /. See Sheet Configuration for more details.
The fourth and final step is to trigger the sheet when the agent answers the
queued call. Go to Services ‣ CTI Server ‣ Sheets ‣
Events and link the event Linked to the sheet you just created.
That’s it, you can assign agents to your queue, log the agents and make them
answer calls with the CC Agent opened, and your browser should open the
specified URL.
You must wait until the full synchronization process has completed to determine the state returned back from the device.
This can take several seconds. It is important to wait and do nothing during this time.
This page documents how to add and configure directories from custom sources. Directories added from
custom sources can be used for lookup via the directory feature of
phones or for reverse lookup on incoming calls.
This type of directory is used to query the users of a XiVO. On a fresh install, the local XiVO is
already configured. The URI field for this type of directory should be the base URL of a
xivo-confd server.
This directory type matches the xivo backend in xivo-dird.
Here is an example of a configuration where the userfield was used as a free
field to store the DID number of the user and the description to store it’s
location.
Services ‣ CTI Server ‣ Directories ‣ Definitions
XiVO offers the possibility to integrate LDAP servers. Once configured properly, you’ll be able to
search your LDAP servers from your XiVO client and from your phones (if they support this feature).
Note
This page describes how to add LDAP servers as sources of contacts. For other sources of
contacts, see Directories.
You can add a LDAP server by clicking on the add button at the top right corner of the
Configuration ‣ Management ‣ LDAP Servers page. You’ll then
be shown this page:
If you are using SSL with an LDAP server that is using a CA certificate from an
unknown certificate authority, you’ll have to put the certificate file as a
single file ending with .crt into /usr/local/share/ca-certificates
and run update-ca-certificates.
You also need to make sure that the /etc/ldap/ldap.conf file contains a
line TLS_CACERT/etc/ssl/certs/ca-certificates.crt.
After that, restart spawn-fcgi with servicespawn-fcgirestart.
Also, make sure to use the FQDN of the server
in the host field when using SSL. The host field must match exactly what’s in the CN
attribute of the server certificate.
If a custom filter is defined in the LDAP filter configuration, the fields in direct match will be
added to that filter using an &. To only use the filter field of your LDAP filter configuration,
do not add any direct match fields in your directory definition.
Example:
Given an LDAP filter with filter st=Canada
Given a directory definition with a direct match cn,o
Then the resulting filter when doing a search will be &(st=Canada)(|(cn=*%Q*)(o=*%Q*))
The source file of the directory must be in CSV format. You will be able to choose the headers and the separator in the next steps. For example, the file will look like:
The data returned by the Web service must have the same format than the file directory. In the same
way, you will be able to choose the headers and the separator in the next step.
This directory type matches the CSV web service backend in xivo-dird.
For web service directories, the Direct match and the Match reverse
directories must be filled with the name of the HTTP query parameter that will be used when doing
the HTTP requests.
Note that the CSV returned by the Web service is not further processed.
Manual configuration needs to be done to use a secure (SSL) connection.
See CSV web service for more details.
Given a configuration where the directory source returns results with fields firstname and lastname
. To add a name column to a directory, the administrator would add the following Mapped
fields:
Given a directory source that need a prefix to be called, a new field can be created from an exising
one. To add a prefix 9 to the numbers returned from a source, the administrator would add the
following Mapped fields:
Sometimes, it can be useful to add a field to the search results. A string can be added without any
formatting. To add a directory field to the xivodir directory, the administrator would add the
following Mapped fields:
Edit the default display filter or create your own in Services ‣ CTI Server ‣
Directories ‣ Display filters.
Services ‣ CTI Server ‣ Directories ‣ Display filters
Each line in the display filter will result in a header in your XiVO Client.
Field title: text displayed in the header.
Field type: type of the column, this information is used by the XiVO Client. (see
type description)
Default value: value that will be used if this field is empty for one of the
configured sources.
Field name: name of the field in the directory definitions. The specified names
should be available in the configured sources. To add new column name to a directory definition
see above.
There is a case where directed pickup does not work, which is the following:
GivenyouhaveauserUwithalineoftype"customized"GiventhiscustomlineisusingDAHDItechnologyGiventhisuserisamemberofgroupGWhenacallismadetogroupGThenyouwon't be able to intercept the call made to U by pressing *8<line number of U>
If you find yourself in this situation, you’ll need to write a bit of dialplan.
For example, if you have the following:
a user with a custom line with number 1001 in context default
In some cases, as the telephony provider, you want different independent organisations to have their
telephony served by your XiVO, e.g. different departments using the same telephony infrastructure,
but you do not want each organisation to see or edit the configuration of other organisations.
Some fields are globally unique and will collide when the same value is used in different entities:
User CTI login
Agent number
Queue name
Context name
An error message will appear when creating resources with colliding parameters, saying the resource
already exists, even if the entity-linked administrator can not see them.
The REST API does not have the notion of entity. When creating a resource without context via REST
API, the resource will be associated to an arbitrary entity. Affected resources are:
If you want to receive faxes from XiVO, you need to add incoming calls definition with the
Application destination and the FaxToMail application for every DID you want to receive faxes
from.
This applies even if you want the action to be different from sending an email, like putting it on a
FTP server. You’ll still need to enter an email address in these cases even though it won’t be used.
Note that, as usual when adding incoming call definitions, you must first define the incoming call
range in the used context.
You can change the body of the email sent upon fax reception by editing /etc/xivo/mail.txt.
The following variable can be included in the mail body:
%(dstnum)s: the DID that received the fax
%(srcnum)s: the sender number (as we received it)
If you want to include a regular percent character, i.e. %, you must write it as %% in
mail.txt or an error will occur when trying to do the variables substitution.
The agid service must be restarted to apply changes:
The following features are only available via the /etc/xivo/asterisk/xivo_fax.conf
configuration file. They are not available from the web-interface.
The way it works is the following:
you first declare some backends, i.e. actions to be taken when a fax is received. A backend name
looks like mail, ftp_example_org or printer_office.
once your backends are defined, you can use them in your destination numbers. For example, when
someone calls the DID 100, you might want the ftp_example_org and mail backend to be run,
but otherwise, you only want the mail backend to be run.
Here’s an example of a valid /etc/xivo/asterisk/xivo_fax.conf configuration file:
The directory option is optional and if not specified, the document will be put in the user’s
root directory.
The convert_to_pdf option is optional and defaults to 1. If it is set to 0, the TIFF file will
not be converted to PDF before being sent to the FTP server.
The uploaded file are named like ${XIVO_SRCNUM}-${EPOCH}.pdf.
XiVO is able to provision Cisco SPA122 and Linksys SPA2102, SPA3102 and SPA8000 analog gateways which can be used to
connect fax equipments. This section describes the creation of custom template for SPA3102 which
modifies several parameters.
Note
With SPA ATA plugins >= v0.8, you should not need to follow this section anymore since all of these parameters are now set in the base templates of all, except for Echo_Canc_Adapt_Enable, Echo_Supp_Enable, Echo_Canc_Enable.
Note
Be aware that most of the parameters are or could be country specific, i.e. :
Preferred Codec,
FAX Passthru Codec,
RTP Packet Size,
RTP-Start-Loopback Codec,
Ring Waveform,
Ring Frequency,
Ring Voltage,
FXS Port Impedance
Create a custom template for the SPA3102 base template:
Fax transmission, to be successful, MUST use G.711 codec. Fax streams cannot be encoded with
lossy compression codecs (like G.729a).
That said, you may want to establish a SIP trunk using G.729a for all other communications to save
bandwith. Here’s a way to be able to receive a fax in this configuration.
Note
There are some prerequisites:
your SIP Trunk must offer both G.729a and G.711 codecs
your fax users must have a customized outgoing calleridnum (for the codec change is based on
this variable)
We assume that outgoing call rules and fax users with their DID are created
Create the file /etc/asterisk/extensions_extra.d/fax.conf with the following content:
;; For faxes :
; The following subroutine forces inbound and outbound codec to alaw.
; For outbound codec selection we must set the variable with inheritance.
; Must be set on each Fax DID
[pre-incall-fax]
exten = s,1,NoOp(### Force alaw codec on both inbound (operator side) and outbound (analog gw side) when calling a Fax ###)
exten = s,n,Set(SIP_CODEC_INBOUND=alaw)
exten = s,n,Set(__SIP_CODEC_OUTBOUND=alaw)
exten = s,n,Return()
; The following subroutine forces outbound codec to alaw based on outgoing callerid number
; For outbound codec selection we must set the variable with inheritance.
; Must be set on each outgoing call rule
[pre-outcall-fax]
exten = s,1,NoOp(### Force alaw codec if caller is a Fax ###)
exten = s,n,GotoIf($["${CALLERID(num)}" = "0112697845"]?alaw:)
exten = s,n,GotoIf($["${CALLERID(num)}" = "0112697846"]?alaw:end)
exten = s,n(alaw),Set(__SIP_CODEC_OUTBOUND=alaw)
exten = s,n(end),Return()
For each Fax users’ DID add the following string in the Preprocesssubroutine field:
pre-incall-fax
For each Outgoing call rule add the the following string in the Preprocesssubroutine field:
The Services/Graphics section gives a historical overview of a XiVO system’s
activity based on snapshots recorded every 5 minutes.
Graphics are available for the following resources :
CPU
Entropy
Interruptions
IRQ Stats
System Load
Memory Usage
Open Files
Open Inodes
Swap Usage
Each section is presented as a series of 4 graphics : daily, weekly, monthly
and yearly history. Each graphic can be clicked on to zoom. All information presented is read only.
Pickup groups allow users to intercept calls directed towards other users of the group. This
is done either by dialing a special extension or by pressing a function key.
Pickup groups can be created in the Services ‣ IPBX ‣ Call management ‣ Call
pickups page.
In the general tab, you can define a name and a description for the pickup group.
In the Interceptors tab, you can define a list of users, groups or queues that can intercept
calls.
In the Intercepted tab, you can define a list of users, groups or queues that can be intercepted.
You can find more details about pattern matching in Asterisk (hence in XiVO) on
the Asterisk wiki.
DID will not be validated against context ranges if pattern matching is used.
Patterns are entered and displayed without the “_” prefix in the web interface.
For the moment, Name and Username need to be the same string.
The Context field will determine which extensions will be reachable by the
other side of the trunk:
If Context is set to default, then every user, group, conf room,
queue, etc. that have an extension if the default context will be
reachable directly by the other end of the trunk. This setting can ease
configuration if you manage both ends of the trunk.
If you are establishing a trunk with a provider, you probably don’t want
everything to be available to everyone else, so you can set the Context
field to Incalls. By default, there is no extension available in this
context, so we will be able to configure which extension are reachable by the
other end. This is the role of the incoming calls: making bridges from the
Incalls context to other contexts.
On XiVO A, create the other end of the SIP trunk on the Services
‣ IPBX ‣ Trunk management ‣ SIP Protocol:
On both XiVO, activate some codecs, Services
‣ IPBX ‣ General Settings ‣ SIP protocol, tab Signaling:
Enabledcodecs:atleastGSM(audio)
Warning
Without customizing the codecs, problems with sound quality or one-way sound may occur.
At that point, the Asterisk command sipshowregistry on XiVO B should print
a line showing that XiVO A is registered, meaning your trunk is established.
This will tell XiVO: if any extension begins with **99, then try to dial it
on the trunk xivo-trunk, after removing the 4 first characters (the **99
prefix).
The most useful special characters to match extensions are:
Now that we have calls going out from a XiVO, we need to route incoming calls on
the XiVO destination.
Note
This step is only necessary if the trunk is linked to an Incoming calls
context.
To route an incoming call to the right destination in the right context, we will
create an incoming call in Services ‣ IPBX ‣ Call management
‣ Incoming calls.
This will tell XiVO: if you receive an incoming call to the extension 101 in
the context Incalls, then route it to the user someone. The destination
context will be found automatically, depending on the context of the line of the
given user.
So, with the outgoing call set earlier on XiVO A, and with the incoming call
above set on XiVO B, a user on XiVO A will dial **99101, and the user
someone will ring on XiVO B.
Connection to global telephony network can be configured automatically in this version of XiVO.
For instructions how to configure it manually, see Interconnect XiVO with any VoIP provider.
When you want to send and receive calls to the global telephony network, one
option is to subscribe to a VoIP provider. To receive calls, your XiVO needs to
tell your provider that it is ready and to which IP the calls must be sent. To
send calls, your XiVO needs to authenticate itself, so that the provider knows
that your XiVO is authorized to send calls and whose account must be credited
with the call fare.
The steps to configure the interconnections are:
Establish the trunk between the two XiVO, that is the SIP connection
between the two servers
Configure outgoing calls on the server(s) used to emit calls
Configure incoming calls on the server(s) used to receive calls
For the moment, Name and Username need to be the same value.
If your XiVO is behind a NAT device or a firewall, you should set the
following:
Monitoring:Yes
This option will make Asterisk send a signal to the VoIP provider server every 60 seconds (default
settings), so that NATs and firewall know the connection is still alive. If you want to change the
value of this cycle period, you have to select the appropriate value of the following parameter:
QualifyFrequency:
At that point, the Asterisk command sipshowregistry should print a line
showing that you are registered, meaning your trunk is established.
Now that we have calls going out, we need to route incoming calls.
To route an incoming call to the right destination in the right context, we will
create an incoming call in Services ‣ IPBX ‣ Call management
‣ Incoming calls.
This will tell XiVO: if you receive an incoming call to the public phone number
in the context Incalls, then route it to the user
the_front_desk_guy. The destination context will be found automatically,
depending on the context of the line of the given user.
In the file /etc/asterisk/dahdi-channels.conf you need to adjust, for each span :
group : the group number (e.g. 0 for provider links, 2 for PBX links),
context : the context (e.g. from-extern for provider links, from-pabx for PBX links)
signalling : pri_cpe for provider links, pri_net for PBX side
Warning
most of the PBX uses overlap dialing for some destination (digits are sent one by one
instead of by block). In this case, the overlapdial parameter has to be activated on the PBX
spans:
overlapdial=incoming
Below an example of /etc/asterisk/dahdi-channels.conf:
We first need to create a route for calls coming from the PBX
# Create a file named pbx.conf in the directory /etc/asterisk/extensions_extra.d/,
# Add the following lines in the file:
[from-pabx]
exten = _X.,1,NoOp(### Call from PBX ${CARLLERID(num)} towards ${EXTEN} ###)
exten = _X.,n,Goto(default,${EXTEN},1)
This dialplan routes incoming calls from the PBX in the default context of XiVO.
It enables call from the PBX :
* towards a SIP phone (in default context)
* towards outgoing destniation (via the to-extern context included in default context)
In our example, incoming calls on spans 1 and 2 (spans pluged to the provider) are routed by
from-extern context. We are going to create a default route to redirect incoming calls to the PBX.
Create an incoming call as below :
DID : XXXX (according to the number of digits sent by the provider)
To use your DAHDI links you must create a customized interconnection.
Name : the name of the interconnection like e1_span1 or bri_port1
Interface : must be of the form dahdi/[grouporder][groupnumber] where :
grouporder is one of :
g : pick the first available channel in group,
searching from lowest to highest,
G : pick the first available channel in group,
searching from highest to lowest,
r : pick the first available channel in group, going in round-robin fashion
(and remembering where it last left off), searching from lowest to highest,
R : pick the first available channel in group, going in round-robin fashion
(and remembering where it last left off), searching from highest to lowest.
When setting up an interconnection with the public network or another PBX, it is possible to set a
caller ID in different places. Each way to configure a caller ID has it’s own use case.
The format for a caller ID is the following "MyName"<9999> If you don’t set the number part of
the caller ID, the dialplan’s number will be used instead. This might not be a good option in most
cases.
If you only need to set a number as an outgoing caller ID, you just have to put the number in the caller ID field like 0123456789.
When the internal caller’s caller ID is not usable to the called party, the outgoing call’s caller id can
be fixed to a given value that is more useful to the outside world. Giving the public number here
might be a good idea.
A user can also have a forced caller ID for outgoing calls. This can be useful for a user who has
his own public number (DID number). This option can be set in the user’s configuration page. For this,
the Outgoing Caller ID option must be set to Customize.
The user can also set his outgoing caller ID to Anonymous.
If you use a SIP provider trunk, and if your provider supports the RFC3325 for Anonymous calls, you have
to set the Send the Remote-Party-ID option of your SIP trunk to PAI:
With this option anonymous calls will be sent to your SIP provider with the RFC 3325 standard.
Note that in this case, the P-Asserted-Identity SIP Header will contain the Outgoing caller ID number if set. Otherwise it
will use the user’s internal caller id, which not a good idea. So you should configure a default caller ID in the outgoing call.
Interactive voice response (IVR) is a technology that allows a computer to interact with humans
through the use of voice and DTMF tones input via keypad. In telecommunications, IVR allows
customers to interact with a company’s host system via a telephone keypad or by speech recognition,
after which they can service their own inquiries by following the IVR dialogue.
—Wikipedia
The IVR can be easily added to XiVO using scripts. These scripts are written using the asterisk embeded language
also named dialplan .
First step, you need to create a configuration file, that contain an asterisk context and your IVR
dialpan. In our example, both (file and context) are named dp-ivr-example.
Important
Since WebRTC calls are initiated through an originate for UC/CC applications, you should use xivo-pickup subroutine to answer the channel properly in your custom dialplans like IVRs
Copy all these lines in the newly created configuration file (in our case, dp-ivr-example) :
[dp-ivr-example]
exten = s,1,NoOp(### dp-ivr-example.conf ###)
same = n,NoOp(Set the context containing your ivr destinations.)
same = n,Set(IVR_DESTINATION_CONTEXT=my-ivr-destination-context)
same = n,NoOp(Set the directory containing your ivr sounds.)
same = n,Set(GV_DIRECTORY_SOUNDS=/var/lib/xivo/sounds/ivr-sounds)
same = n,NoOp(the system answers the call before continuing)
same = n,GoSub(xivo-pickup,s,1)
same = n,NoOp(the system plays the first part of the audio file "welcome to ...")
same = n(first),Playback(${GV_DIRECTORY_SOUNDS}/ivr-example-welcome-sound)
same = n,NoOp(variable "counter" is set to 0)
same = n(beginning),Set(counter=0)
same = n,NoOp(variable "counter" is incremented and the label "start" is defined)
same = n(start),Set(counter=$[${counter} + 1])
same = n,NoOp(counter variable is now = ${counter})
same = n,NoOp(waiting for 1 second before reading the message that indicate all choices)
same = n,Wait(1)
same = n,NoOp(play the message ivr-example-choices that contain all choices)
same = n,Background(${GV_DIRECTORY_SOUNDS}/ivr-example-choices)
same = n,NoOp(waiting for DTMF during 5s)
same = n,Waitexten(5)
;##### CHOICE 1 #####
exten = 1,1,NoOp(pressed digit is 1, redirect to 8000 in ${IVR_DESTINATION_CONTEXT} context)
exten = 1,n,Goto(${IVR_DESTINATION_CONTEXT},8000,1)
;##### CHOICE 2 #####
exten = 2,1,NoOp(pressed digit is 2, redirect to 8833 in ${IVR_DESTINATION_CONTEXT} context)
exten = 2,n,Goto(${IVR_DESTINATION_CONTEXT},8833,1)
;##### CHOICE 3 #####
exten = 3,1,NoOp(pressed digit is 3, redirect to 8547 in ${IVR_DESTINATION_CONTEXT} context)
exten = 3,n,Goto(${IVR_DESTINATION_CONTEXT},8547,1)
;##### CHOICE 4 #####
exten = 4,1,NoOp(pressed digit is 4, redirect to start label in this context)
exten = 4,n,Goto(s,start)
;##### TIMEOUT #####
exten = t,1,NoOp(no digit pressed for 5s, process it like an error)
exten = t,n,Goto(i,1)
;##### INVALID CHOICE #####
exten = i,1,NoOp(if counter variable is 3 or more, then goto label "error")
exten = i,n,GotoIf($[${counter}>=3]?error)
exten = i,n,NoOp(pressed digit is invalid and less than 3 errors: the guide ivr-exemple-invalid-choice is now played)
exten = i,n,Playback(${GV_DIRECTORY_SOUNDS}/ivr-example-invalid-choice)
exten = i,n,Goto(s,start)
exten = i,n(error),Playback(${GV_DIRECTORY_SOUNDS}/ivr-example-error)
exten = i,n,Hangup()
To call the script dp-ivr-example from an external phone, you must create an incoming
call and redirect the call to the script dp-ivr-example with the command :
To call the script dp-ivr-example from an internal phone you must create an entry in the default
context (xivo-extrafeatures is included in default). The best way is to add the extension in
the file xivo-extrafeatures.conf.
First step, create your schedule (1) from the menu Call management ‣ Schedules.
In the General tab, give a name (3) to your schedule and configure the open hours (4) and select
the sound which is played when the company is closed.
In the Closed hours tab (6), configure all special closed days (7) and select the sound that
indicate to the caller that the company is exceptionally closed.
The IVR script is now only available during workdays.
Copy all these lines (2 contexts) in a configuration file on your XiVO server :
[dp-ivr-example]
exten = s,1,NoOp(### dp-ivr-example.conf ###)
same = n,NoOp(Set the context containing your ivr destinations.)
same = n,Set(IVR_DESTINATION_CONTEXT=my-ivr-destination-context)
same = n,NoOp(Set the directory containing your ivr sounds.)
same = n,Set(GV_DIRECTORY_SOUNDS=/var/lib/xivo/sounds/ivr-sounds)
same = n,NoOp(the system answers the call before continuing)
same = n,GoSub(xivo-pickup,s,1)
same = n,NoOp(the system plays the first part of the audio file "welcome to ...")
same = n(first),Playback(${GV_DIRECTORY_SOUNDS}/ivr-example-welcome-sound)
same = n,NoOp(variable "counter" is set to 0)
same = n(beginning),Set(counter=0)
same = n,NoOp(variable "counter" is incremented and the label "start" is defined)
same = n(start),Set(counter=$[${counter} + 1])
same = n,NoOp(counter variable is now = ${counter})
same = n,NoOp(waiting for 1 second before reading the message that indicate all choices)
same = n,Wait(1)
same = n,NoOp(play the message ivr-example-choices that contain all choices)
same = n,Background(${GV_DIRECTORY_SOUNDS}/ivr-example-choices)
same = n,NoOp(waiting for DTMF during 5s)
same = n,Waitexten(5)
;##### CHOICE 1 #####
exten = 1,1,NoOp(pressed digit is 1, redirect to 8000 in ${IVR_DESTINATION_CONTEXT} context)
exten = 1,n,Goto(${IVR_DESTINATION_CONTEXT},8000,1)
;##### CHOICE 2 #####
exten = 2,1,NoOp(pressed digit is 2, redirect to 8833 in ${IVR_DESTINATION_CONTEXT} context)
exten = 2,n,Goto(${IVR_DESTINATION_CONTEXT},8833,1)
;##### CHOICE 3 #####
exten = 3,1,NoOp(pressed digit is 3, redirect to the submenu dp-ivr-submenu)
exten = 3,n,Goto(dp-ivr-submenu,s,1)
;##### CHOICE 4 #####
exten = 4,1,NoOp(pressed digit is 4, redirect to start label in this context)
exten = 4,n,Goto(s,start)
;##### TIMEOUT #####
exten = t,1,NoOp(no digit pressed for 5s, process it like an error)
exten = t,n,Goto(i,1)
;##### INVALID CHOICE #####
exten = i,1,NoOp(if counter variable is 3 or more, then goto label "error")
exten = i,n,GotoIf($[${counter}>=3]?error)
exten = i,n,NoOp(pressed digit is invalid and less than 3 errors: the guide ivr-exemple-invalid-choice is now played)
exten = i,n,Playback(${GV_DIRECTORY_SOUNDS}/ivr-example-invalid-choice)
exten = i,n,Goto(s,start)
exten = i,n(error),Playback(${GV_DIRECTORY_SOUNDS}/ivr-example-error)
exten = i,n,Hangup()
[dp-ivr-submenu]
exten = s,1,NoOp(### dp-ivr-submenu ###)
same = n,NoOp(the system answers the call before continuing)
same = n,GoSub(xivo-pickup,s,1)
same = n,NoOp(variable "counter" is set to 0)
same = n(beginning),Set(counter=0)
same = n,NoOp(variable "counter" is incremented and the label "start" is defined)
same = n(start),Set(counter=$[${counter} + 1])
same = n,NoOp(counter variable is now = ${counter})
same = n,NoOp(waiting for 1 second before reading the message that indicate all choices)
same = n,Wait(1)
same = n,NoOp(play the message ivr-example-choices that contain all choices)
same = n,Background(${GV_DIRECTORY_SOUNDS}/ivr-example-submenu-choices)
same = n,NoOp(waiting for DTMF during 5s)
same = n,Waitexten(5)
;##### CHOICE 1 #####
exten = 1,1,NoOp(pressed digit is 1, redirect to 8000 in ${IVR_DESTINATION_CONTEXT} context)
exten = 1,n,Goto(${IVR_DESTINATION_CONTEXT},8000,1)
;##### CHOICE 2 #####
exten = 2,1,NoOp(pressed digit is 2, redirect to 8001 in ${IVR_DESTINATION_CONTEXT} context)
exten = 2,n,Goto(${IVR_DESTINATION_CONTEXT},8001,1)
;##### CHOICE 3 #####
exten = 3,1,NoOp(pressed digit is 3, redirect to the previous menu dp-ivr-example)
exten = 3,n,Goto(dp-ivr-example,s,beginning)
;##### TIMEOUT #####
exten = t,1,NoOp(no digit pressed for 5s, process it like an error)
exten = t,n,Goto(i,1)
;##### INVALID CHOICE #####
exten = i,1,NoOp(if counter variable is 3 or more, then goto label "error")
exten = i,n,GotoIf($[${counter}>=3]?error)
exten = i,n,NoOp(pressed digit is invalid and less than 3 errors: the guide ivr-exemple-invalid-choice is now played)
exten = i,n,Playback(${GV_DIRECTORY_SOUNDS}/ivr-example-invalid-choice)
exten = i,n,Goto(s,start)
exten = i,n(error),Playback(${GV_DIRECTORY_SOUNDS}/ivr-example-error)
exten = i,n,Hangup()
Lists XiVO related processes (most of which are daemons) with their corresponding
status, uptime, resource usage and controls to restart service,
stop service and stop monitoring service.
Only 1 audio channel must be present per file, i.e. files must be in mono.
If your music on hold files don’t seem to work, you should look for errors in the asterisk logs.
The on-hold music will always play from the start.
mp3: play MP3 files.
The on-hold music will play from an arbitrary position on the track, it will not play from the start.
custom: do not play sound files. Instead, run an external process. That process must send on
stdout the same binary format than WAV files.
Example process: /usr/bin/mpg123-s--mono-y-f8192-r8000http://streaming.example.com/stream.mp3
Note
Processes run by custom categories are started as soon as the category is created and will
only stop when the category is deleted. This means that on-hold music fed from online
streaming will constantly be receiving network traffic, even when there are no calls.
You can configure outgoing calls settings in Services ‣ IPBX ‣ Call Management ‣ Outgoing calls.
An outgoing call is composed with a definition of a outgoing route (the extension patterns that should match) and a destination (a trunk owned by a media server).
(advanced) Caller ID: Override the presented number once call is performed.
Internal: set the route to forward the internal caller’s caller ID to the trunk. This option is useful when the other side of the trunk can reach the user with it’s caller ID number.
Media server: define the route only for specific media server.
Context: define the route only for specific context.
Once route is defined and therefore can be selected if an extension match the route, you need to set the wanted destination.
A route destination is materialized by:
Trunk: SIP or Custom trunk that will be used to reach desired network.
Subroutine: Subroutine to apply once route has been selected.
A route can define rights aka call permissions, it means that a call can be discarded if missing the right to use this route.
The same applies for schedules where you can define time slots of availability of the route.
With XiVO, you can define paging (i.e. intercom) extensions to page a group of
users. When calling a paging extension, the phones of the specified users will
auto-answer, if they support it.
You can manage your paging extensions via the Services ‣ IPBX ‣ Paging
page.
When adding a new paging extension, the number can be any numeric value; to call it,
you just need to prefix the paging number with *11.
With XiVO it is possible to park calls, the same way you may park your car in a car parking.
If you define supervised keys on a phone set for all the users of a system, when a call is parked, all the users are able to
see that some one is waiting for an answer, push the phone key and get the call back to the phone.
There is a default parking number, 700, which is already configured when you install XiVO,
but you may change the default configuration by editing the parking extension in menu
Service ‣ IPBX ‣ IPBX Services ‣ Extensions ‣ Parking
Using this extension, you may define the parking number used to park call, the parking lots, wether the sytem is rotating over
the parking lots to park the calls, enable parking hint if you want to be able to supervise the parking using phone keys and other
system default parameters.
You have two options in case of parking timeout :
Callback the peer that parked this call
In this case the call is sent back to the user who parked the call.
Send park call to the dialplan
In case you don’t want to call back the user who parked the call, you have the option to send the call to any other extension or application.
If the parking times out, the call is sent back to the dialplan in context [parkedcallstimeout].
You can define this context in a dialplan configuration file Service ‣ IPBX ‣ Configuration Files where you may
define this context with dialplan commands.
Example:
[parkedcallstimeout]exten=s,1,Noop('park call time out')same=n,Playback(hello-world)same=n,Hangup()
It is also usual to define supervised phone keys to be able to park and unpark calls as in the example below.
A global phone book can be defined in Services ‣ IPBX ‣ IPBX Services ‣
Phonebook. The phone book can be used from XiVO assistants, from the phones directory look key if
the phone is compatible and are used to set the Caller ID for incoming calls.
You can add entries one by one or you can mass-import from a CSV file.
You can create a meeting room contact to been seen as an entry in your phonebook so that it can be searched and clickable from assistant.
To do so you need to fill at least:
* displayname of the room
* any number field with value following this format : video:roomName where roomName is the value you defined when you created a meeting room in XiVO webi.
Go in the Services ‣ IPBX ‣ IPBX Services ‣ Phonebook section and move your
mouse cursor on the + button in the upper right corner. Select Import a file.
The file to be imported must be a CSV file, with a pipe character | as field delimiter. The file
must be encoded in UTF-8 (without an initial BOM).
The auto-provisioning feature found in XiVO make it possible to provision, i.e.
configure, a lots of telephony devices in an efficient and effortless way.
Dialing the user’s provisioning code from the phone
And voila, once the phone has rebooted, your user is ready to make and receive calls.
No manual editing of configuration files nor fiddling in the phone’s web interface.
Device synchronisation does not work in the situation where multiple devices are connected from
behind a NAPT network equipment. The devices must be resynchronised manually.
You have two options to get your phone to be provisioned:
Set up a DHCP server
Tell manually each phone where to get the provisioning informations
You may want to manually configure the phones if you are only trying XiVO or if your network configuration does not allow the phones to access the XiVO DHCP server.
You may want to set up a DHCP server if you have a significant number of phones to connect, as no manual intervention will be required on each phone.
it only answers to DHCP requests coming from the VoIP subnet (see network configuration).
This means that if your phones are on the same broadcast domain than your computers,
and you would like the DHCP server on your XiVO to handle both your phones and your
computers, that won’t do it.
The DHCP server is configured via the Configuration ‣ Network ‣ DHCP page:
The lower IP address which will be assigned dynamically. This address should
be in the VoIP subnet. Example: 10.0.0.10.
Pool end
The higher IP address which will be assigned dynamically. This address should
be in the VoIP subnet. Example: 10.0.0.99.
Extra network interfaces
A list of space-separated network interface name. Example: eth0.
Useful if you have done some custom configuration in the /etc/dhcp/dhcpd_extra.conf
file. You need to explicitly specify the additional interfaces the DHCP server should
listen on.
After saving your modifications, you need to click on Apply system configuration
for them to be applied.
Here’s the list of other things that can be done from this page:
update the list of installable plugins, by clicking on the top left icon (1). On a fresh
XiVO installation, this is the first thing to do.
install a new plugin (2)
edit an installed plugin (3), i.e. install/uninstall optional files that are specific to each plugin, like
firmware or language files
upgrade an installed plugin (4)
uninstall an installed plugin (5)
After installing a new plugin, you are automatically redirected to its edit page. You
can then download and install optional files specific to the plugin. You are strongly
advised to install firmware and language files for the phones you’ll use although
it’s often not a strict requirement for the phones to work correctly.
Warning
If you uninstall a plugin that is used by some of your devices, they will be
left in an unconfigured state and won’t be associated to another plugin
automatically.
The search box at the top comes in handy when you want to find which plugin to install
for your device. For example, if you have a Cisco SPA508G, enter “508” in the search box
and you should see there’s 1 plugin compatible with it.
Note
If your device has a number in its model name, you should use only the number as the search keyword
since this is what usually gives the best results.
It’s possible there will be more than 1 plugin compatible with a given device. In these cases,
the difference between the two plugins is usually just the firmware version the plugins target.
If you are unsure about which version you should install, you should look for more information
on the vendor website.
It’s good practice to only install the plugins you need and no more.
http://provd.xivo.solutions/plugins/1/addons/testing/ – community supported devices “testing” repository
The difference between the stable and testing repositories is that the latter might contain plugins
that are not working properly or are still in developement.
The archive repository contains plugins that were once in the stable repository.
After setting a new URL, you must refresh the list of installable plugins by clicking the update icon
of the Configuration ‣ Provisioning ‣ Plugin page.
How to manually tell the phones to get their configuration
If you have set up a DHCP server on XiVO and the phones can access it, you can skip this section.
The according provisioning plugins must be installed.
Once you have installed the proper provd plugins for your devices and setup correctly your
DHCP server, you can then connect your devices to your network.
But first, go to Services ‣ IPBX ‣ Devices page. You will then see that no
devices are currently known by your XiVO:
You can then power on your devices on your LAN. For example, after you power on an Aastra 6757i and
give it the time to boot and maybe upgrade its firmware, you should then see the phone having its first
line configured as ‘autoprov’, and if you refresh the devices page, you should see that your XiVO
now knows about your 6757i:
You can then dial from your Aastra 6757i the provisioning code associated to a line of one of your user.
You will hear a prompt thanking you and your device should then reboot in the next few seconds.
Once the device has rebooted, it will then be properly configured for your user to use it. And also,
if you update the device page, you’ll see that the icon next to your device has now passed to green:
Edit the primary user associated to the terminal (one with the line 1) and put the device field to null.
click on the Save button on the web interface
The primary line of the phone has been removed, so the device will lose its funckeys associated
to primary user but there others lines associated to the device will stay provisionned.
The phone doesn’t restart and the phone is in autoprov mode in the device list.
If your phones are getting their network configuration from your XiVO’s DHCP server,
it’s possible to activate the DHCP integration on the
Configuration ‣ Provisioning ‣ General page.
What DHCP integration does is that, on every DHCP request made by one of your
phones, the DHCP server sends information about the request to provd, which
can then use this information to update its device database.
This feature is useful for phones which lack information in their TFTP/HTTP
requests. For example, without DHCP integration, it’s impossible to extract
model information for phones from the Cisco 7900 series. Without the model
information extracted, there’s chance your device won’t be automatically
associated to the best plugin.
This feature can also be useful if your phones are not always getting the same IP
addresses, for one reason or another. Again, this is useful only for some phones,
like the Cisco 7900; it has no effect for Aastra 6700.
Custom templates comes in handy when you have some really specific configuration
to make on your telephony devices.
Templates are handled on a per plugin basis. It’s not possible for a template to be
shared by more than one plugin since it’s a design limitation of the plugin system
of provd.
Note
When you install a new plugin, templates are not migrated automatically, so you must
manually copy them from the old plugin directory to the new one. This does not apply for a plugin upgrade.
Let’s suppose we have installed the xivo-aastra-3.3.1-SP2 plugin and
want to write some custom templates for it.
First thing to do is to go into the directory where the plugin is installed:
This is where the original templates lies. You should not edit these files
directly but instead copy the one you want to modify in the var/templates directory.
var/templates
This is the directory where you put and edit your custom templates.
var/tftpboot
This is where the configuration files lies once they have been generated from the templates.
You should look at them to confirm that your custom templates are giving you the result you are expecting.
Warning
When you uninstall a plugin, the plugin directory is removed altogether, including all the custom templates.
A few things to know before writing your first custom template:
when doing an include or an extend from a template, the file is first looked up
in the var/templates directory and then in the templates directory.
device in autoprov mode are affected by templates, because from the point of view
of provd, there’s no difference between a device in autoprov mode or fully configured.
This means there’s usually no need to modify static files in var/tftpboot. And this
is a bad idea since a plugin upgrade will override these files.
To create a custom template for a specific device you have to create a device-specific template
named <device_specific_file_with_extension>.tpl in the var/templates/ directory :
for an Aastra phone, if you want to customize the file 00085D2EECFB.cfg you will have
to create a template file named 00085D2EECFB.cfg.tpl,
for a Snom phone, if you want to customize the file 000413470411.xml you will have
to create a template file named 000413470411.xml.tpl,
for a Polycom phone, if you want to customize the file 0004f2211c8b-user.cfg you will have
to create a template file named 0004f2211c8b-user.cfg.tpl,
and so on.
Here, we want to customize the content of a device-specific file named 00085D2EECFB.cfg,
we need to create a template named 00085D2EECFB.cfg.tpl:
The choice to use this syntax comes from the fact that provd supports devices that do not have MAC addresses,
namely softphones.
Also, some devices have more than one file (like Snom), so this way make
it possible to customize more than 1 file.
The template to use as the base for a device specific template will vary depending on the need.
Typically, the model template will be a good choice, but it might not always be the case.
From time to time, new firmwares are released by the devices manufacturer.
This sometimes translate to a new plugin being available for these devices.
When this happens, it almost always means the new plugin obsoletes the older one.
The older plugin is then considered “end-of-life”, and won’t receive any new updates
nor be available for new installation.
Let’s suppose we have the old xivo-aastra-3.2.2.1136 plugin installed on our
xivo and want to use the newer xivo-aastra-3.3.1-SP2 plugin.
Both these plugins can be installed at the same time, and you can manually change
the plugin used by a phone by editing it via the Services ‣ IPBX ‣ Devices
page.
If you are using custom templates in your old plugin, you should copy
them to the new plugin and make sure that they are still compatible.
Once you take the decision to migrate all your phones to the new plugin, you can
use the following command:
The provisioning server has partial support for environment where the telephony devices are behind a
NAT equipment.
By default, each time the provisioning server receives an HTTP/TFTP request from a device, it makes
sure that only one device has the source IP address of the request. This is not a desirable
behaviour when the provisioning server is used in a NAT environment, since in this case, it’s normal
that more than 1 devices have the same source IP address (from the point of view of the server).
If all your devices used on your XiVO are behind a NAT, you should disable this behaviour by
setting the NAT option to 1 via the Configuration ‣ Provisioning ‣ General
page.
Enabling the NAT option will also improve the performance of the provisioning server in this scenario.
If you have many devices behind a NAT equipment, you should also check the security section to make sure the IP address of your NAT equipment doesn’t get banned
unintentionally.
You must only have phones of the following brands:
Aastra
Cisco SPA
Yealink
All your devices must be behind a NAT equipment (the devices may be grouped behind different NAT
equipments, not necessarily the same one)
You must provision the devices via the Web interface, i.e. associate the devices from the user
form. Using the 6-digit provisioning code on the phone will produce unexpected results (i.e. the
wrong device will be provisioned)
By design, the auto-provisioning process is vulnerable to:
Leakage of sensitive information: some files that are served by the provisioning server contains
sensitive information, e.g. SIP credentials that are used by SIP phones to make calls. Depending
on your network configuration and the amount of information an attacker has on your telephony
ecosystem (phone vendor, MAC address, etc.), he could retrieve the content of some files
containing sensitive information.
Denial-of-service attack: in its default configuration, each time the provisioning server identify
a request coming from a new device, it creates a new device object in its database. An attacker
could spoof requests to the provisioning server to create a huge amount of devices, creating a
denial-of-service condition.
That said, starting from XiVO 16.08, XiVO adds Fail2ban support to the
provisioning server to drastically lower the likelihood of such attacks. Every time a request for a
file potentially containing sensitive information is requested, a log line is appended to the
/var/log/xivo-provd-fail2ban.log file, which is monitored by fail2ban. The same thing
happens when a new device is automatically created by the provisioning server.
The fail2ban configuration for the provisioning server is located at
/etc/fail2ban/jail.d/xivo.conf. You may want to adjust the findtime / maxretry value
if you have special requirements. In particular, if you have many phones behind a NAT equipment,
you’ll probably have to adjust these values, since every request coming from your phones behind your
NAT will appear to the provisioning server as coming from the same source IP address, and this IP
address will then be more likely to get banned promptly if you, for example, reboot all your phones
at the same time. Another solution would be to add your IP address to the list of ignored IP address
of fail2ban. See the fail2ban(1) man page for more information.
If you have a phone provisioned with XiVO and its one of the supported ones, you’ll be able to search in your XiVO directory and place call directly
from your phone.
See the list of supported devices to know if a model supports the XiVO directory or not.
For the remote directory to work on your phones, the first thing to do is to go to the
Services ‣ IPBX ‣ (General settings) Phonebook page.
You then have to add the range of IP addresses that will be allowed to access the directory.
So if you know that your phone’s IP addresses are all in the 192.168.1.0/24 subnet, just
click on the small “+” icon and enter “192.168.1.0/24”, then save.
Once this is done, on your phone, just click on the “remote directory” function key and
you’ll be able to do a search in the XiVO directory from it.
At this point you should have a fully functional DHCP server that provides IP address to your
phones. Depending on what type of CISCO phone you have, you need to install the plugin sccp-legacy,
sccp-9.4 or both.
Note
Please refer to the Provisioning page for more information on
how to install CISCO firmwares.
Once your plugin is installed, you’ll be able to edit which firmwares and locales you need.
If you are unsure, you can choose all without any problem.
SCCP Phones support directmedia (direct RTP). In order for SCCP phones to use directmedia, one must enable the directmedia option in SCCP general settings:
Services ‣ IPBX ‣ IPBX settings ‣ SCCP general settings
Models not listed in the table above won’t be able to connect to Asterisk at all. Models listed as
“Testing” are not yet officially supported in XiVO: use them at your own risk.
The “Timezone aware” column indicates if the device supports the timezone tag in its configuration
file, i.e. in the file that the device request to the provisioning server when it boots. If you
have devices that don’t support the timezone tag and these devices are in a different timezone than
the one of the XiVO, you can look at the issue #5161 for
a potential solution.
Schedules are specific time frames that can be defined to open or close a service.
Within schedules you may specify opening days and hours or close days and hours.
A default destination as user, group … can be defined when the schedule is in closed state.
A schedule is composed of a name, a timezone, one or more opening hours or days that you may setup using a calendar widget,
a destination to be used when the schedule state is closed.
With the calendar widget you may select months, days of month, days of week and opening time.
You may also optionaly select closed hours and destination to be applied when period is inside the main schedule.
For example, your main schedule is opened between 08h00 and 18h00, but you are closed between 12h00 and 14h00.
When you have a schedule associated to a user, if this user is called during a closed
period, the caller will first hear a prompt saying the call is being transferred before
being actually redirected to the closed action of the schedule.
If you don’t want this prompt to be played, you can change the behaviour by:
editing the /etc/xivo/asterisk/xivo_globals.conf file and setting the
XIVO_FWD_SCHEDULE_OUT_ISDA to 1
reloading the asterisk dialplan with an asterisk-rx"dialplanreload".
Switchboard functionality is available in XiVO CC or UC Add-on.
The switchboard application allows an operator to view incoming calls, answer them,
put calls on hold, view and retrieve the calls on hold. See the Switchboard page for detailed explaination on usage.
The goal of this page is to explain how to configure your switchboard.
When using a Snom switchboard, you must not configure a function key on position 1.
To be able to use a Snom phone for the switchboard, the XiVO must be able to do HTTP requests to
the phone. This might be problematic if there’s a NAT between your XiVO and your phone. The
following command should work from your XiVO’s bash command line wgethttp://guest:guest@<phoneIPaddress>/command.htm?key=SPEAKER. If this command does not activate the phone’s speaker, your
network configuration will have to be fixed before you can use the Snom switchboard.
If you changed the administrator username or administrator password for your phone, via Configuration ‣ Provisioning‣ Template Device,
you need to follow the Configuration Customization procedure.
The switchboard uses a queue to track its calls on hold.
To create this queue, go to Services ‣ Call center ‣ Queues and click the add button.
The following configuration is mandatory :
General tab:
Name field MUST:
start with the name of your switchboard incoming call queue
and end with _hold
Note
For example, if the switchboard incoming call queue is standard_switchboard, the name of the switchboard hold queue must be standard_switchboard_hold.
Number field must a valid number in a context reachable by the switchboard operator
Advanced tab:
Join an empty queue option list has to be empty
Remove callers if there are no agents option list has to be empty
Create a Personal Hold Queue for Your Switchboard
A switchboard operator can have a personal hold queue instead of the general hold queue.
Note
A personal hold queue will always have the priority over the general one, meaning that the calls on hold for this operator will be sent by default to their personal hold queue.
To create this queue, go to Services ‣ Call center ‣ Queues and click the add button.
The following configuration is mandatory :
General tab:
The Name field MUST:
start with the name of the switchboard incoming calls queue
and end with _hold and the operator’s agent number
Note
For example, if the switchboard incoming call queue is standard_switchboard and operator agent number is 8002, the name of its personal switchboard hold queue must be standard_switchboard_hold_8002.
The Number field must a valid number in a context reachable by switchboard operator
Advanced tab:
Join an empty queue option list has to be empty
Remove callers if there are no agents option list has to be empty.
The agent must only be a member of the switchboard queue, they should not be a member of any other queue.
The General Hold Queue and Personnal Hold Queue must have NO members.
Incoming calls must be sent to the Switchboard queue to be distributed to
the operators. To do this, we have to change the destination of our incoming
call for the switchboard queue.
In this example, we associate our incoming call (DID 444) to our Switchboard queue:
Set “No Answer” Destinations on the Switchboard Queue
When there are no operators available to answer a call, “No Answer” destinations
should be used to redirect calls towards another destination.
You also need to set the timeout of the Switchboard queue to know when calls will be
redirected.
The reachability timeout must not be disabled nor be too short.
The time before retrying a call to a member should be as low as possible (1 second).
In this example we redirect “No Answer”, “Busy” and “Congestion” calls to the
everyone group and “Fail” calls to the guardian user.
You can also choose to redirect all the calls to another user or a voice mail.
Switchboard statistics can be retrieved in PDF format via the web interface in
Services ‣ Statistics ‣ Switchboard ‣ Statistics.
Start date: required field
End date: if empty, the result will contain statistics until the current date
Note
Switchboard statistics older than number of weeks defined by WEEKS_TO_KEEP environment variable in /etc/docker/xivo/custom.env are automatically removed.
Incoming calls can only be answered in order of arrival.
It means the agent can’t choose which call to answer first, they must answer the first one of the list, then the second, etc…
When operator retrieves a call, it will cancel the current ringing call. Mainly it will cancel the call the the Incoming call queue was sending to him.
It therefore puts back the Incoming call in the queue and gives the possibility to the operator to deal with the retrieved call.
Note therefore that it will behaves the same for a ringing call on the operator phone which don’t come from the queue: for example if someone inside the
company called the operator without going through the queue. In this case the ringing call will be cancelled and lost. This is a limitation. To overcome this
you must make sure that people inside the company should join the standard only via the Incoming call queue.
All calls towards your user’s extension will be sent to your UC Assistant
You can also place internal our outgoing calls with your UC Assistant
Note
When connecting for the first time, the user will be using its WebRTC account.
He can then chose the device he wants to use using the Device selection menu.
The user can see which device he’s using in the menu CallManagement shown just above.
In this menu he can change back his device to deskphone. That means the calls emitted or received will be
on the deskphone and the user can only control the deskphone with the UC Assistant.
If Alice logs out from UC Assistant, then all call will be received on her Deskphone.
Even if she had chosen the Browser/XiVO Client as device, when she logs out from UC Assistant, the call will fallback to her Deskphone.
For a Unique Account user, the forwarding rules are applied to the device the user is using.
For example if the user is connected to the UC Assistant using its WebRTC line, and if he doesn’t answer a call,
the non answer rule is directly applied without making the deskphone ring.
If a Unique Account user logs in UC Assistant and then quits the page (without logging out),
it can take few minutes before the next call will ring on its deskphone
(the WebRTC line gets unregistered, but after a delay depending on XiVO configuration).
Users can be imported and associated to other resources by use of a CSV file. CSV Importation can be
used in situations where you need to modify many users at the same in an efficient manner, or for
migrating users from one system to another. A CSV file can be created and edited by spreadsheet
tools such as Excel, LibreOffice/OpenOffice Calc, etc.
The first line of a CSV file contains a list of field names (also sometimes called “columns”). Each
new line afterwards are users to import. CSV data must respect the following conditions:
Files must be encoded in UTF-8
Fields must be separated with a ,
Fields can be optionally quoted with a "
Double-quotes can be escaped by writing them twice (e.g. Robert""Bob""Jenkins)
Empty fields or headers that are not defined will be considered null.
Fields of type bool must be either 0 for false, or 1 for true.
Fields of type int must be a positive number
Additionally, these restrictions for specific fields must also be respected:
Field labels: All user labels in this field must already exist before the import
In the following tables, columns have been grouped according to their resource. Each resource is
created and associated to its user when all required fields for that resource are present.
Number for calling the user from an incoming call (i.e outside of XiVO). The number
must be inside the range of acceptable numbers defined for the context.
incall_context
string
Yes
context used for calls coming from outside of XiVO
Once your file is ready, you can import it via Services ‣ IPBX ‣ IPBX settings
‣ Users. At the top of the page there is a plus button. A submenu will appear when the mouse is
on top. Click on Import a file.
The field list for an update is the same as for an import with the addition of the column uuid,
which is mandatory. For each line in the CSV file, the updater goes through the following steps:
Find the user, using the uuid
For each resource (line, voicemail, extension, etc) find out if it already exists.
If an existing resource was found, associate it with the user. Otherwise, create it.
Update all remaining fields
The following restrictions must also be respected during update:
Columns that are not included in the CSV header will not be updated.
A field that is empty (i.e, “”) will be converted to NULL, which will unset the value.
A line’s protocol cannot be changed (i.e you cannot go from “sip” to “sccp” or vice-versa).
An incall cannot be updated if the user has more than one incall associated.
All user labels in the labels field must already exist before the update
Updating is done through the same menu as importing (Services ‣ IPBX ‣ IPBX
settings ‣ Users). A submenu will appear when the mouse is on top. Click on Update from file in
the submenu.
Beginning, end and all import/update errors and warnings are logged to /var/log/xivo-confd.log.
CSV import/update can take several minutes. If it reaches a timeout you’ll see a message in the webi explaining that the import/update continues in the background
and that you should check the log to verify that it was successfully finished.
If there are any invalid CSV rows, associated warnings or errors will be printed in the log:
If there are warnings only the changes will be applied.
If there is one error or more all changes will be rollbacked.
CSV exports can be used as a scaffold for updating users, or as a means of importing users into
another system. An export will generate a CSV file with the same list of columns as an import, with
the addition of uuid and provisioning_code.
Exports are done through the same menu as importing (Services ‣ IPBX ‣ IPBX
settings ‣ Users). Click on Export to CSV in the submenu. You will be asked to download a
file.
Lines can be configured from the Lines tab when creating a user.
Users with line Unique Account, Phone or WebRTC can easily edit their line type from the same menu.
Users with line type SCCP or Custom cannot change line type. In that case, the line should be deleted and created again with a new line type.
Function keys can be configured to customize the user’s phone keys. Key types are pre-defined and
can be browsed through the Type drop-down list. The Supervision field allows the key to be
supervised. A supervised key will light up when enabled. In most cases, a user cannot add multiple
times exactly the same function key (example : two user function keys pointing to the same user).
Adding the same function key multiple times can lead to undefined behavior and
generally will delete one of the two function keys.
Warning
SCCP device only supports type “Customized”.
For User keys, start to key in the user name in destination, XiVO will try to complete with the corresponding user.
If the forward unconditional function key is used with no destination the user will be prompted when the user
presses the function key and the BLF will monitor ALL unconditional forward for this user.
When this option is activated, the user can press *3 during a conversation to start/stop online
call recording. The recorded file will be available in the monitor directory of the
Services ‣ IPBX ‣ Audio files menu.
By using the extension *26 from your phone (the “call recording” option must be activated
in Services ‣ IPBX ‣ Extensions).
When this option is activated, all calls made to or made by the user will be recorded in the monitor
directory of the Services ‣ IPBX ‣ Audio files menu.
Once your voicemail is configured, you have to edit the user configuration and
search the voicemail previously created and then associate it to your user.
Search for a voicemail in the user’s configuration
Unchecking the option Askpassword allows you to skip password checking for the voicemail only
when it is consulted from an internal context.
when calling the voicemail with *98
when calling the voicemail with *99<voicemail number>
Warning
If the the *99 extension is enabled and a user does not have a password on its voicemail, anyone from the same context will be able
to listen to its messages, change its password and greeting messages.
However, the password will be asked when the voicemail is consulted through an incoming call. For
instance, let’s consider the following incoming call:
With such a configuration, when calling this incoming call from the outside, we will be asked for:
the voicemail number we want to consult
the voicemail password, even if the “Disable password checking option” is activated
And then, we will be granted access to the voicemail.
Take note that the second “context” field contains the context of the voicemail. Voicemails of other contexts
will not be accessible through this incoming call.
Warning
For security reasons, such an incoming call should be avoided if a voicemail in the given context
has no password.
E-mail message can be configured to be sent to user of the voicemail :
configure mail server in Configuration ‣ Network ‣ Mail
set e-mail address of the user in configuration of his voicemail
Default message can be set in Services ‣ IBX ‣ General Settings ‣ Voicemails and it can be customized
from tab E-mail in Services ‣ IBX ‣ IPBX settings ‣ Voicemails.
Letters ; and \ must be preceded with backslash and , (comma) can be written only in the default message.
Current WebRTC implementation (since XiVO Freya 2020.18) does not require any of these manual configuration steps Users
XiVO comes with a WebRTC lines support, you can use in with XiVO UC Assistant and Desktop Assistant.
Before starting, please check the WebRTC Environment.
Former WebRTC implementation might require following configuration steps:
When the user is not connected to its WebRTC line, or disconnect from the assistant, you can route the call to a default number
as for example the user mobile number.
Update the fail option on the No Answer user tab configuration, and add an extension to the appropriate context.
Those REST API interfaces are documented on http://<youxivo>.api. They all require an authorization
token, obtained by giving valid credentials to the REST API of xivo-auth. The relevant settings are:
Login/Password: the xivo-auth credentials (for the xivo-auth backendxivo_service)
Those web services are deprecated. There is no documentation about their usage, and the goal is to
remove them.
They are still protected with HTTP authentication, requiring a login and password. The
relevant settings are:
Login/Password: the HTTP authentication credentials
Host: the authorized hosts that are allowed to make HTTP requests:
Empty value: HTTP authentication
Non-empty value: no HTTP authentication, all requests coming from this host will be accepted.
Valid hosts may be: a hostname, an IP address, a CIDR block.
There is no fine-grained permissions: either the user has access to every PHP web services, or none.
In XiVO, the contact center is implemented to fulfill the following objectives :
Call routing
Includes basic call distribution using call queues and skills-based routing
Agent and Supervisor workstation.
Provides the ability to execute contact center actions such as: agent login, agent logout and
to receive real time statistics regarding contact center status
Statistics reporting
Provides contact center management reporting on contact center activities
A call center agent is the person who handles incoming or outgoing customer
calls for a business. A call center agent might handle account inquiries,
customer complaints or support issues. Other names for a call center agent
include customer service representative (CSR), telephone sales or service
representative (TSR), attendant, associate, operator, account executive
or team member.
—SearchCRM
In this respect, agents in XiVO have no fixed line and can login from any registered device.
XiVO system agents can be external to the system, the agent can use it’s personal PSTN line, mobile phone or a terminal
connected to some other PBX system. We call these remote lines external line. The same agent can login to a standard
line, or to an external line. The choice is done via the line number on the login page.
where EXTERNAL_LINE_NUMBER@default is the number and context which can be used to join the remote phone, for a french
mobile phone it would usually be 0xxxxxxxxx@default.
The agent has to login using the custom line, the standard ccagent features are available. However, due to external line
some phone control features are not available - the agent can’t answer, put on hold or transfer calls from the ccagent
interface. On the XiVO side, please ensure that the call distributed to the agent is canceled if the agent doesn’t answer
before the call is answered by for example the voicemail.
A queue can be configured with the following options:
Name: used as an unique id, cannot be general
Display name: Displayed on the supervisor screen
On-Hold music: The music the caller will hear. The music is played when waiting and when the call is on hold.
A ring strategy defines how queue members are called when a call enters the queue.
A queue can use one of the following ring strategies:
Linear: For each call, in the same order, starting from the same member
For agents: In login order
For static members: In definition order
Least recent: call the member who least recently hung up a call
Fewest calls: call the member with the fewest completed calls
Round robin memory: call the “next” member after the one who answered last
Random: call a member at random
Weight random: same as random, but taking the member penalty into account
Warning
When editing a queue, you can’t change the ring strategy to linear. This
is due to an asterisk limitation. Unfortunately, if you want to change the
ring strategy of a queue to linear, you’ll have to delete it first and then
create a new queue with the right strategy.
Note
When an agent is a member of many queues, configured with the same weight, the order of call distribution
between multiple queues is nondeterministic and cannot be configured.
In order to have a deterministic behavior, you MUST configure different weight on each queues.
Note
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.
You may control how long a call will stay in a queue using different timers:
Member reachabillity time out (Advanced tab): Maximum number of seconds a call will ring on an agent’s phone. If a call is not answered within this time, the call will be forwarded to another agent.
Time before retrying a call to a member (Advanced tab): Used once a call has reached the “Member reachability time out”. The call will be put on hold for the number of seconds alloted before being redirected to another agent.
Ringing time (Application tab): The total time the call will stay in the queue.
Timeout priority (Application tab): Determines which timeout to use before ending a call. When set to “configuration”, the call will use the “Member reachability time out”. When set to “dialplan”, the call will use the “Ringing time”.
No answer: The call reached the “Ringing time” in Application tab and no agent answered the call
Congestion: The number of calls waiting has reached the “Maximum number of people allowed to wait” limit specified on the advanced tab
Fail: No agent was available to answer the call when the call entered the queue (“Join an empty queue” condition on the advanced tab) or
the call was queued and no agents were available to answer (“Remove callers if there are no agents” on the advanced tab)
Weight: Give the queue a priority to others queues (if agents belong to two or more queues). Check weight warning for explanation.
Warning
When configuring a queue with a higher weight, all the calls in this queue will be prioritized over the calls of other queues if they
they have the same set of members.
Here, the red call must wait end of orange and green calls. Even if the red calls ring agent first, if for some reasons agent did not answer red call, the red call will have to wait for orange and green.
If some others orange or green calls come after, red call will also have to wait.
Actually, red call must wait that queue of weight 2 and queue of weight 1 be completely empty.
Diversions can be used to redirect calls to another destination when a queue is very busy.
Calls are redirected using one of the two following scenarios:
The diversion check is done only once per call, before the preprocess subroutine is
executed and before the call enters the queue.
In the following sections, a waiting call is a call that has entered the queue but has not yet been
answered by a queue member.
When this scenario is used, the administrator can set a destination for calls to be sent to when the estimated waiting time is over the threshold.
Note that if a new call arrives when there are no waiting calls in the queue, the call will always be allowed to enter the queue.
Note
this estimated waiting time is computed from the actual hold time of all answered calls in the queue
(since last asterisk restart) according to an exponential smoothing formula
the estimated waiting time of a queue is updated only when a queue member answers a call.
Number of Waiting Calls per Logged-In Agent Overrun
When this scenario is used, the administrator can set a destination for calls to be sent to when the number of waiting
calls per logged-in agent is over the threshold.
The number of waiting calls includes the call for which the check is currently being performed.
The number of logged-in agents is the sum of user members and currently logged-in agent members. An
agent only needs to be logged in and a member of the queue to participate towards the count of logged-in agents,
regardless of whether he is available, on call, on pause or on wrapup.
The maximum number of waiting calls per logged-in agent can have a fractional part.
Note that if a new call arrives when there are no waiting calls in the queue, the call will
always be allowed to enter the queue. For example, in the following scenario:
Even if the number of waiting calls per logged-in agent (1) is greater than the maximum (0.5), the call
will still be accepted since there are currently no waiting calls.
By clicking on the name of the queue, a modal will appear.
Supervisors with no access to dissuasion will see some details about the queue.
Administrators and supervisors who have access to the dissuasion will see different tabs :
One tab showing some information about the queue
One tab to configure the dissuasion in case of an exceptional closing for this queue.
In the configuration tab, click on the title “Failed Destination”.
A dropdown appears, showing the sound files and/or the queue that can be set up as a failed destination.
The failed destination can be changed from this dropdown.
This interface allows a user to change queue assignement and the associated penalty. The queue table display the following columns
“Number”: The queue number
“Name”: The queue name
“Penalty”: The active penalty for the corresponding queue
“default”: The default penalty for the corresponding queue
The queue/active penalty couples can be saved as default configuration by clicking the “Set default” button, then “Save”.
The queue/default penalty couples can be saved as active configuration by clicking the “Set current” button, then “Save”.
Note
Removing an agent from a queue
Emptying the penalty textbox and saving will remove the queue from the active configuration for the agent.
Emptying the default textbox and saving will remove the queue from the default configuration for the agent.
From agent view you are able to add or remove more than one agent at the same time.
Once the agent selection is done, click on the edit button to display the configuration window
Click on the plus button to add a queue for selection, click on the minus button to remove a queue to the selection.
Once queue to add or removed are choosen, click on save button to apply your configuration change.
Click on “Apply default configuration” to apply existing default configuration to all selected users and make it the active configuration. This action only affects users with an existing default configuration, agents whithout default configuration remain unchanged.
From the agent view, after selecting one or more agents, you can create a base configuration by clicking on one of the menu item in the following drop down:
‘Create base configuration’ will allow you to create a base configuration from scratch for all the selected agents.
‘Create base configuration from active configuration’ will allow you to create a base configuration using the selected agents active configuration. The queue membership and penalty populated will be built based on the merged membership of all the selected agents. In case of conflict, the lowest penalty will be used.
In both cases, you will be able to review your changes before applying them. The ‘Create base configuration’ popup is similar to the single agent edition popup:
The queue table display the following columns:
“Number”: The queue number
“Name”: The queue name
“Penalty”: The active penalty for the corresponding queue
Click on the plus button to add a queue for selection. Once your configuration is complete, click on save button to apply your configuration change.
In order to re-apply or apply a default configuration, you may select agent whose base configuration is different from active configuration.
In the agent view, you will find a new column (Base config.) displaying if the base configuration is different from the active one:
The possible values for this field are:
“n/a”: The base configuration is not available for this agent
“Ok” : The base configuration match the active configuration
“Different”: The base configuration does not match the active configuration
You can use this column to filter agent whose base configuration is different from the active one and then apply the default configuration by using the “Edit agent” option.
Once you setup queue recording in XiVO (see Enable recording in the Queue configuration), visual indicators are displayed next to queue name in Global view. Respectively following icons represents recording mode set on the queue.
Furthermore shortcut action is displayed in the left menu to control the activation / deactivation of all recorded queues.
The switch will change its position in case the queue’s recording status is activated / deactivated through XiVO Web Interface accordingly.
The switch button will either activate all queues configured with recording mode set (Recorded or Recorded on demand), or stop the recording feature for all queues.
Note
Action is applied only for next calls. Ongoing call recording is not started nor stopped when switch is triggered.
It is possible to add columns to reflect more performance indicators, such as Percentage of calls answered/abandoned within XX seconds.
See Configuration to add such stats thresholds.
This section describes the CC Agent application features.
It is available as a web application from your Web Browser.
It is also available as a desktop application with these additionnal features:
show integrated popup when receiving call
get keyboard shortcut to answer/hangup and make call using Select2Call feature
CC Agent is a Web application for contact center operators. Some parameters for Recording, Callbacks, Queue control, Pause statuses and Sheet popup may be configured.
Instructions can be found in the configuration section.
From the interface you will be able to :
Manage your activities you are subscribed to receive calls.
See the customer history inside your organization when a call is coming
Interact with your phone from the call control panel
Get some real time statistics of your session
The web application can either be displayed in a minimal bar or be extended as seen in screen shot below when launched as standalone application. See desktop application.
Warning
The application offers support for the WebRTC lines, currently there’s a limitation on complementary services like the second call which is only partially supported.
Enter your CTI username, password and phone set you want to logged to on the login page.
If you are using Kerberos authentication and enabled SSO (see Kerberos Authentication), then you only have to set your phone set number, the authentication and login will be done automatically:
Note
Automatic login keeps you signed in until you log out.
At the top of the application, computed statistics from XUC are displayed to monitor the agent activity. Simply hover the icon to know its definition.
They are updated once current action is over.
Those statistics are clickable and display dynamic charts on top of the counters. The goal is to offer a global view to agents on their activity during the day.
There are two differents charts displayed.
The first one is a bar chart focusing on the time unit :
Total Available Time
Total Pause Time
Inbound ACD Calls Total Time
Outbound Calls Total Time
Total Wrapup Time
On click on each one of those buttons, the bar chart will be displayed.
You can hover each bar to have the detailed time spent for a specific indicator (HH:MM:SS).
The second one is a donut chart focusing on the number of calls :
Number of Inbound ACD calls
Number of Inbound Answered ACD Calls
Number of Outbound Calls
On click on each one of those buttons, the donut chart will be displayed.
You can hover each part of the donut to have the number of calls for one indicator.
The charts are updated once current action is over.
Once logged in you are automatically redirected to activities view, this view contains the list of activities you are registered in.
Hovering an activity triggers a popover which displays some real-time statistics about call distribution in this queue.
You may also call or transfer a call to an activity using the displayed phone icon
It is possible to filter on favorite activities just by clicking Myactivities check box.
You can manage subscription if allowed globally for the application (see CC Agent configuration). If enabled you will be able to enter/quit an activity just by clicking on checkbox associated to it.
Each time you enter an activity, it is automatically added to your favorites. At any time you can remove it by clicking on minus sign next to the name in Myactivities view.
Note
You can remove an activity if and only if you are not already registered in.
It’s also possible to enter all your favorites activities just by one click on All checkbox.
A little badge displays the number of waiting calls in each activity. The sum of all waiting calls in the agent activities is displayed in top menu and refreshed in real time.
In XiVO, when an activity is exceptionnally closed, a sound file containing a message can be played to the caller.
From its CC Agent application, an agent who has access to the dissuasion can:
see which sound file or default queue is currently configured
select another sound file to be played
select a default queue as a failed destination, instead of a sound file.
An agent can change the dissuasion if they have been granted access, it means if they have an administrator profile or a supervisor profile with the permission to change the dissuasion.
The agent profile can be set from the configmgt interface. See Profile Management section.
Note
The sound files available for the activity and displayed to the agent and the default queue are to be set by an administrator of the XiVO.
See Activity’s Failed Destination Configuration section.
In the Activity view, when clicking the Dissuasion button, a menu appears with the list of the sound files or default queues available for a queue.
If one of the sound file or default queue is selected for this queue, it will be highlighted in orange and the circle icon will be checked.
If no sound file or default queue are selected for the queue, the circle icon won’t be checked.
The agent can change the selected sound file or default queue from the dropdown menu.
When clicking on the Agents menu, you will see all the agents of your group. By hovering one of them, you will quickly find his current state (ready, calling, in pause…)
A simple click on the phone icon when agent is hovered will trigger a call to its phone number associated.
By default, agents are shown only if they are logged in (checkbox Logged checked). By unchecking the checkbox Logged, you will see all the agents of your group even if they are logged out.
When using the Agent interface, you will see your current calls at the top of the screen:
This panel will display the current caller name & number and also the associated activity if the call came from one.
You also have two indicator on the right side letting you know:
if the call is currently recorded
and if the call is currently listened by a supervisor (on this subject see also Warn agent when spied).
By hovering your mouse on the call line, an action pane will slide to display action button on the related call. The available buttons depend on the call state.
The Agent interface use Desktop notification for incoming calls and notify long calls on hold, but this feature needs to be enabled from the browser window when logging in:
Simple keyboard navigation (with UP and DOWN directional keys) is allowed to browse search results. Once a contact has been focused, ENTER key
can be pressed to open drop-down menu and so choose, still with directional keys, the action to achieve.
The Agent can also use the basic keyboard shortcuts available to perform basic call control tasks :
F3 to answer a call
F4 to hangup the current ongoing call
F7 to complete an attended transfer
F10 to put the focus in the search bar
Note
The list of usable keybindings is available by clicking on the menu at the top-right corner of the ccagent and the switchboard.
For agents with default WebRTC lines that connects to another webrtc line (aka “roaming agent”) may randomly take the wrong line configuration (especially when you refresh the page). Only workaround so far is to logout/login the agent to force the retrieval of the correct line. For roaming agent, it is recommended to not set default line to agent and use free sitting to wanted line.
First menu History tab is displaying the call history of connected agent.
It displays the last 20 calls for the last 7 days period.
Information shown in the call list are :
destination number or name of callee if call is emitted
source number or name of caller if a call is received or missed
Call icon status and call start date
By clicking on phone icon you will be able to call back if needed.
Warning
Pay attention that agent history is not the phone device history, but his call activity independently the device he is connected to. Actually when agent is logged out, if a call is received on his last used phone, nothing will be shown in his history.
Note
A call answered by another agent from the queue, will appear as answered in the history of the first agent.
While phone is ringing or discussion is ongoing, it is possible to have a quick overview of the customer call history of the caller just by clicking information menu.
Second tab of information menu displays all attached data enriched to the ongoing call or display Sheet fields if you are using Sheet Configuration.
The customer history is displayed from most recent to last one with an icon to know quickly waiting time of current or previous call :
It’s also possible to trigger either to open a web page, see Screen Popup or completely integrate a third party application while agent is having calls, see Configuration.
This feature will add an additional book button on the left side of the search bar.
It allows to open and close an external directory and is integrated the same way as any other tab content.
Call qualifications are used to describe a call in a queue with a certain qualification and its related sub qualification.
For example, a call can be qualified as a qualification Sales and a sub qualification Hardware.
Note
Call qualifications will require some 3rd party application (see Configuration) complementary to CCAgent to display a sheet for agents to qualify the call and save results to database.
Qualifications are managed on the
Services ‣ Call Center ‣ Qualifications page.
In order to retrieve all qualifications for a certain queue, the qualification must be added to that queue.
A queue can be assigned with multiple qualifications and a qualification can be assigned to multiple queues.
To assign a qualification or multiple qualifications to the queue, open
Removing a qualification will remove also all related sub qualifications. The sub qualifications can be removed
by opening the qualification edit page.
Note
The (sub)qualification will not be deleted from the database, but will be marked as inactive. This is due to the situation
in which a call has been already qualified with now removed qualification. Therefore the information won’t be lost.
recording is done on XiVO PBX (or the XiVO Gateway)
and recorded files are sent to the XiVO CC Recording server.
It’s then possible to search for recordings and download recorded files from Recording server.
If connected user is an administrator, he will also be able to download an access log file that tracks all actions made on files by all users having access to recording server.
When recording is enabled the whole conversation between caller and callee is recorded and then sent on dedicated recording server. All the files are then available for download only for predefined granted users (see Profiles Definition).
Any action made from the UI on a recording file (result, listen or download) is tracked in access log that can be downloaded by clicking on following icon if you have administrator role.
Note
This access log is defined to track information for 6 months by default.
Recording is done on XiVO PBX and sent to Recording server. If recorded file can’t be synchronized on XiVO CC Recording Server, files might be found on XiVO PBX in
ls-al/var/spool/xivocc-recording/failed
These files will be automatically resynchronized from XiVO PBX to XiVO CC Recording server each night.
In case an agent has transferred a call to another queue, which was answered by the agent available in that queue, the recording feature will display both agents (name and number) in column Agent
and both queues (name and number) under column File in one recording.
When a call enters a queue, the recording will be started (or not) according to the queue Recording mode (see Enable recording in the Queue configuration).
If this call is transferred to another queue, it will stop or start the recording according to the following table:
Recording is stopped when both parties of the call are external.
For example if an external incoming call is recorded and if, at some point, it is transferred to an external party,
as soon as the transfer is completed, the recording of the incoming call will be stopped.
In the same way if an internal user makes an outgoing call which is recorded and then transfers it to another external party,
as soon as the transfer is completed, the recording of the outgoing call will be stopped.
Recording server allows to prevent some numbers not to be recorded.
You can deactivate recording either
for specific called numbers (called Incalls or called Queues or called Users),
or, on outgoing calls, for calling Users internal numbers
Note
This feature is designed to activate recording globally (e.g. for every Queues) and then deactivate it for some Queues
(e.g. for queue 1001)
To do so, navigate to : http://XIVOCC_IP:9400/recording_control and in page Contrôled'enregistrement you can add or remove the
number to disable recording on this number.
The goal of the callback system is to be able to perform scheduled outgoing calls.
These requests can be completed with specific information such as a description or a personal name.
The core object of the callback system is the callback request. A callback request is made of the following fields:
First name of person to call
Last name
Phone number
Mobile phone number
Company name
Description
Due date
Each callback request is associated to a predefined callback period, which represents the preferred interval of the day
in which the call should be performed.
A callback request cannot exist on its own: it must be stored in a callback list, which is itself associated to a queue.
Once a callback request has been performed, it generates a callback ticket. This ticket sums up the original information of the callback request,
but adding some new fields:
Start date: date at which the callback request was actually performed
Last update: date of the last modification of the ticket
Comment
Status : the result of the callback
Agent: the Call Center agent who performed the callback
A callback list is an object which will contain callback request. It is associated to a queue,
and several callback lists can be associated to the same queue. Callback lists are created using the configuration manager
Once created, a list can be populated whether through the Callbacks tab of the CCManager, or programmatically
through the web services of the configuration server.
A callback period represents an interval of the day, bounded by a start date and an end date. It can be set as the default interval, so that
a newly created callback request will be associated to this period if none is specified.
Callbacks can be imported from a CSV file into a callback list.
Line delimiter must be a new line character and column separator must be one of: ‘|’ or ‘,’ or ‘;’. Columns can be optionaly enclosed by double-quote ‘”’.
The header line must contain the exact field named described below:
Field Name
Description
phoneNumber
The number to call (at least either phoneNumber or mobilePhoneNumber is required)
mobilePhoneNumber
Alternate number to call
firstName
The contact first name (optional)
lastName
The contact last name (optional)
company
The contact company (optional)
description
A text that will appear on the agent callback pane
dueDate
The date when to callback, using ISO format: YYYY-MM-DD,
ie. 2016-08-01 for August, 1st, 2016.
If not present the next day will be used as dueDate (optional)
period
The name of the period as defined in callback list.
If not present, the default period will be used (optional)
When an agent takes a callback, the column Takenby is updated with the number of the agent. The callback disappears when it is processed.
The agent can see the callbacks related to the queues he is logged on.
They are available in the Callbacks menu.
A notification is also shown to display pending callbacks in menu to know status at any time and from any other screen of the application.
On this page, the agent only has access to basic information about the callback: activity and due date,
On the left of each callback line, a colored clock indicates the temporal status of this callback:
blue if the callback is to be processed later
green if we are currently inside the callback period
red if the callback period is over
To process one of these callbacks, the agent must click on one of the callbacks line.
To launch the call, the agent must click on one of the available phone numbers.
Once the callback is launched, the status can be changed and a comment can be added.
If you set ‘To reschedule’ as status, the callback can be rescheduled at a later time and another period:
Other statuses are available to be set and will close callback once saved :
Answered if caller accepted the call
NoAnswer if caller were unreachable
Fax if callback has been resolved thanks to a Fax message
Handled by mail if callback has been resolved thanks to an E-mail
Clicking on the calendar icon next to the “New due date” field, will popup a calendar to select another callback date.
Also administrators and supervisors with “dissuasion” access right can change the exceptional closing dissuasion destination when logged in webagent or in the CCManager. see Activity’s Failed Destination Configuration.
Then, when logged in the CC Agent, this agent can see all the queues in the Activities view.
Important
But if an agent is also a Supervisor. When this agent is logged in the CC Agent,
it will see only the set of queues and agents as it was given him in the Supervisor profile via the Configuration Management Server.
Skills-based routing (SBR), or Skills-based call routing, is a call-assignment strategy used in call centres to assign incoming calls
to the most suitable agent, instead of simply choosing the next available agent.
It is an enhancement to the Automatic Call Distributor (ACD) systems found in most call centres.
The need for skills-based routing has arisen, as call centres have become larger and dealt with a wider variety of call types.
—Wikipedia
In this respect, skills-based routing is also based on call distribution to agents through waiting queues, but one or many skills can be
assigned to each agent, and call can be distributed to the most suitable agent.
In skills-based routing, you will have to find a way to be able to tag the call for a specific skill need. This can be done for example
by entering the call distribution system using different incoming call numbers, using an IVR to let the caller do his own choice, or by requesting
to the information system database the customer profile.
Assign the skill rule sets using a configuration file
Apply the skill rule sets to call qualification, i.e. incoming calls by using the preprocess subroutine field
Note that you shouldn’t use skill based routing on a queue with queue members of type user because
the behaviour is not defined and might change in a future XiVO version.
Skills are created using the menu Services ‣ Call center ‣ Skills. Each skill belongs to a category.
First create the category, and in this category create different skills.
Note that a skill name can’t contain upper case letters and must be globally unique (i.e. the
same name can’t be used in two different categories).
Once skills are created, rule sets can be defined.
A rule set is a list of rules. Here’s an example of a rule set containing 2 rules:
WT < 60, english > 50
english > 0
The first rule of this rule set can be read as:
If the caller has been waiting for less than 60 seconds (WT < 60), only try to call agents which
have the skill “english” set to a value higher than 50; otherwise, go to the next rule.
And the second rule can be read as:
Only try to call agents which have the skill “english” set to a value higher than 0.
Let’s examine some simple scenarios, because there’s actually
some subtilities on how calls are distributed. We will suppose that we have a queue with the default
settings and the following members:
When a new call enters the queue, then it is distributed to Agent A. As long as Agent A is
available and doesn’t answer the call, the call will never be distributed to Agent B, even after 60
seconds of waiting time.
When another call enters the queue, then after 60 seconds of waiting time, this call will be
distributed to Agent B (and the first call will still be distributed only to Agent A).
The reason is that there’s a difference between a call that is being distributed (i.e. that is
making agents ring) and a call that is waiting for being distributed. When a call is being
distributed to a set of members, no other rule is tried as long as there’s at least 1 of these
members available.
operand1 | operand2 (at least one of them are true)
‘!’ is the operator with the higher priority, and ‘|’ the one with the lower
priority. You can use parentheses ‘()’ to change the priority of operations.
The dynamic part can reference the following variables:
WT
EWT
The waiting time (WT) is the elapsed time since the call entered the queue. The time the call pass
in an IVR or another queue is not taken into account.
The estimated waiting time (EWT) has never fully worked. It is mentioned here only for historical
reason. You should not use it. It might be removed in a future XiVO version.
The skill part can reference any skills name as variables.
You can also use meta-variables, starting with a ‘$’, to substitute them with data set on the
Queue() call. For example, if you call Queue() with the skill rule set argument equal to:
select_lang(lang=german)
Then every $lang occurrence will be replaced by ‘german’.
Sometimes, a rule references a skill which is not defined for every agent. For example, given the
following rule:
english > 0 | english < 1
Then, for an agent which has the skill english defined, the result of this expression is always
true. For an agent which does not have the skill english defined, the result of this expression is
always false.
Said differently, an agent without a skill X is not the same as an agent with the skill X set to
the value 0.
Technically, this is what is happening when evaluating the rule “english > 0” for an agent without the skill
english:
This behaviour applies to every comparison operators.
Also, the syntax that is currently accepted for comparison is always of the form:
variablecmp_opconstant
Where “variable” is a variable name, “cmp_op” is a comparison operator and “constant” is an integer
constant. This means the following expressions are not accepted:
10 < english (but english > 10 is accepted)
english < french (the second operand must be a constant)
10 < 11 (the first operand must be a variable name)
A skill rule set is attached to a call using a bit of dialplan. This dialplan is stored in a
configuration file you may edit using menu Services ‣ IPBX ‣ Configuration
Files.
In the figure above, 3 different languages are selected using three different subroutines.
Each of this different selections of subroutines can be applied to the call qualifying object.
In the following example language selection is applied to incoming calls.
Pack reporting is a part of the XivoCC. It aims at computing historical statistics,
which are stored in the xivo_stats database. Sample reports based on them are accessible in SpagoBI.
Important
New tables in xivo_stats schema are available (prefixed with xc_). These tables are (so far) for internal use and can be changed without notice. Documentation will be available once this new statistic model will replace the existing one and fix the existing limitations of previous model described above.
Queue members should only be agents. If users are members of a queue, their statistics will be incomplete.
Configuration modifications on the XiVO (such as an agent deletion) are replicated on the statistics server, and their previous value is not kept.
However, statistics history is preserved.
Calls longer than 4 hours are considered as unterminated calls and therefore communication time is set to 0 for these calls.
If two agents are associated to the same call, they will have the same hold time for this call.
Transfer statistics limitations in call_data table:
Given two queues Q1 and Q2, two agents A1 and A2, and an external caller C.
C calls Q1 and A1 answers
A1 transfers to Q2 and A2 answers
A2 transfers to the outside
Then the second transfer is seen as a transfer to the outside.
Given one queue Q1, Two agents A1 and A2 and an external caller C.
C calls Q1 and A1 answers
A1 transfers to A2 through internal phone number
A1 completes the transfer
Then the call between A2 and C is not computed at all in statistics.
The reporting allows to attach as mush data as wished to a given call, in order to find them in the reporting database for future use.
This data must be in the form of a set of key-value pairs.
To attach data to a call, you must use the dialplan’s CELGenUserEvent application:
All report samples (see Upload Statistics Reports) bundled with XiVOCC are aimed to work with french date format.
By default dates are picked in french format (day/month/year). Either you need to type them explicitly in your locale format
either you can set Locale to french thanks to Flag menu in Spago. See #1662
Due to a SpagoBi limitation, when scheduling reports using string parameters, you need to enter manualy the parameter using comma and quotes to
separate values.
Example for queues support, technical and sales, the parameters of the schedulers
must be filled as follow:
Kibana is a web tool used to compute statistics based on Elasticsearch content.
The reports packaged with the Pack reporting give you an outline of your recent call center activity.
Here is a Kibana sample panel:
Graphs are based on the queue_log table, enriched with agent names and agent groups, and inserted into an Elasticsearch index.
It contains avents about calls placed on queues, and events about agent presences.
For each entry in the queue_log index, the following attributes are available:
queudis`downloads page playname : Queue display name
data1: basic queue_log data, with a different meaning according to the event
callid : Call unique identifier, generated by Asterisk
event : Call or agent status event - please see below
Each line in call_data, correspond to a unique call and contains only one uniqueId of one call leg.
This table is aggregated in near real time with the data of cel Asterisk table.
Important
End of a call is considered when phone is hung up, we don’t consider the time of transfers that can be done besides initial call.
Column
Type
Description
id
INTEGER
uniqueid
VARCHAR
Call unique reference, generated by Asterisk
dst_num
VARCHAR
Called number
start_time
TIMESTAMP
Call start time
answer_time
TIMESTAMP
Call answer time
end_time
TIMESTAMP
Call end time (phone is hung up)
status
status_type
Call status. Beware: only answered is properly filled.
ring_duration_on_answer
INTEGER
Ring time of the endpoint answering the call, in seconds
transfered
BOOLEAN
True if the call has been transfered
call_direction
call_direction_type
Call direction (‘’incoming’’ : call from the outside, received by XiVO ; ‘’outgoing’’ : call to the outside, originated by an endpoint associated to XiVO ; ‘’internal’’ : call taking place entirely inside the XiVO)
src_num
VARCHAR
Calling number
transfer_direction
call_direction_type
Indicates the transfer direction, if relevant
src_agent
VARCHAR
Agent originating the call
dst_agent
VARCHAR
Agent receiving the call, if it is a direct call on an agent. Not filled when the call is destined to a queue
src_interface
VARCHAR
Interface originating the call (in the Asterisk sense, ex : SCCP/01234)
Total ring time, in seconds (includes ringing of non-answered calls)
answer_time
TIMESTAMP
Answer time
hangup_time
TIMESTAMP
Hangup time
status
call_exit_type
Call status (full: full queue; closed: closed queue; joinempty: call arrived on empty queue; leaveempty : exit when queue becomes empty; divert_ca_ratio : call redirected because the ratio waiting calls/agents was exceeded ; divert_waittime: call redirected because estimated waiting time was exceeded; answered: call answered ; abandoned: call abandoned; timeout : maximum waiting time exceeded)
Statistics aggregated by queue, called number and time interval (15 minutes)
Column
Type
Description
time
TIMESTAMP
Start time of the considered interval
queue_ref
VARCHAR
Technical name of the queue
dst_num
VARCHAR
Called number
nb_offered
INTEGER
Number of presented calls
nb_abandoned
INTEGER
Number of abandoned calls
sum_resp_delay
INTEGER
Wait time, in seconds
answer_less_t1
INTEGER
Number of calls answered in less than t1 seconds
abandoned_btw_t1_t2
INTEGER
Number of calls abandoned between t1 and t2 seconds
answer_btw_t1_t2
INTEGER
Number of calls answered between t1 and t2 seconds
abandoned_more_t2
INTEGER
Number of calls answered in more than t2 seconds
communication_time
INTEGER
Total communication time in seconds
hold_time
INTEGER
Total hold time in seconds
wrapup_time
INTEGER
Total wrap-up time in seconds
The thresholds t1 and t2 are configurable:
in the table queue_specific_time_period for the default values in seconds. Installation values are t1=15 seconds and t2=20 seconds.
Data is saved in the form of (name, seconds) pairs, for example : (‘t1’, 15).
in the table queue_threshold_time for values specific to a queue. Data is saved in the form of a tuple (queue name, t1, t2).
Tables call_data, call_on_queue and hold_periods can be linked together by doing a join on a column holding the call reference.
The columns are the following:
Table
Reference column
call_data
uniqueid
call_on_queue
callid
hold_periods
linkedid
On the other hand, tables attached_data and call_element contains foreign key referencing the id column of call_data.
—
Tables call_on_queue, agentfeatures and agent_position can be linked together by doing a join on a column holding the agent number reference.
The columns are the following:
Table
Reference column
call_on_queue
agent_num
agentfeatures
number
agent_position
agent_num
—
Tables agentgroups and agentfeatures can be linked together by doing a join on a column holding the agent group id reference.
The columns are the following:
Table
Reference column
agentfeatures
numgroup
agentgroups
id
—
Tables transfers and call_data can be linked together by doing a join on a column holding the call uniqueid reference.
The columns are the following:
Let’s take the assumption that one Agent (A1 with id 8000 and phone number 1000) calls an internal User ( U1 with phone number 1001 ).
This call is transfered to Agent A2 (with id 8002 ) blindly. Then A1 calls internal another User ( U2 with phone number 1002 )
This call flow generates in call_data 2 lines (simplified table to keep only important fields) one for each call ( U1 and U2 ):
id
uniqueId
dst_num
answer_time
end_time
src_agent
dst_agent
transfered
transfer_direction
1
12345678.9
1001
2018-12-01 15:02:00
2018-12-01 15:12:00
8000
8002
true
internal
2
12345679.0
1002
2018-12-01 15:13:00
2018-12-01 15:23:00
8000
and get in transfers 1 line (where callidto id the uniqueId of the leg of Agent A2 with user U1):
id
callidfrom
callidto
1
12345678.9
98765432.1
Statistics (done by pack-reporting for spago reports) generates then stat_agent_specific:
time
agent_num
nb_emitted_internal_calls
conversation_time_emitted_internal_calls
hold_time
2018-11-29 15:15:00
8000
1
720
0
2018-11-29 15:30:00
8000
1
480
0
Important
We don’t consider the time of the transfer besides initial call and only time of established calls.
Let’s take the assumption that one Agent (A1 with id 8000 and phone number 1000) calls an internal User ( U1 with phone number 1001 ).
This call is transfered to Agent A2 (with id 8002 ) after talking with him. Finally A1 calls internal another User ( U2 with phone number 1002 )
This call flow generates in call_data 3 lines (simplified table to keep only important fields) one for each call between U1 and U2 and one for A2:
id
uniqueId
dst_num
answer_time
end_time
src_agent
dst_agent
transfered
transfer_direction
1
12345678.9
1001
2018-12-01 15:02:00
2018-12-01 15:12:00
8000
8002
true
internal
2
12345679.0
1002
2018-12-01 15:13:00
2018-12-01 15:23:00
8000
and get in transfers 1 line (where callidto id the uniqueId of the leg of Agent A2 with user U1):
id
callidfrom
callidto
1
12345678.9
98765432.1
also get in hold_period 1 line:
id
linkedId
start
end
1
12345678.9
2018-12-01 15:07:00
2018-12-01 15:12:00
Statistics (done by pack-reporting for spago reports) generates then stat_agent_specific:
time
agent_num
nb_emitted_internal_calls
conversation_time_emitted_internal_calls
hold_time
2018-11-29 15:15:00
8000
1
1020
300
2018-11-29 15:30:00
8000
1
480
0
Important
Conversation time can be over 900s (15mn) as hold time is included in this specific call flow.
This query get the phone set number on which the agent took the call.
It lists all calls answered by agent with line number on which he was logged in.
The query here is limiting to all calls answered the first day of August, but it can be easily customized to your needs.
As you can see on the schema above the Edge Solution is to be put inside one’s company
DMZ.
From the external world only the Edge Solution will be seen.
Only HTTPS and TURN flows should be authorized from the external - see Network Flows for more details.
The Edge Solution is composed of three components:
This is probably unneeded (traffic between servers inside the DMZ should be in most of the cases
unfiltered), but if it would be the case this flow must be authorized.
Currently there is no automatic upgrade process. Here is the manual process that you need to follow on the 3 edge servers (or the edge server depending if it’s a mono or three servers install).
This step overrides the current .yml files. If you had made some customization in them you will have to backport them by comparing the new one with the backup you did at previous step.
The Edge Solution must be configured with valid certificate for your domain.
You have to put the:
fullchain certificate: here /etc/docker/ssl/xivo-edge.crt
and also here /etc/docker/ssl/xivo-edge.chain (this last location is mandatory for the SIP Proxy service)
certificate key: here /etc/docker/ssl/xivo-edge.key
Make sure that the certificate key are given readonly permission to root:
This step is to be done on the server which will host the Web Proxy (nginx) service
Create the .env file with the following variables (replace values accordingly, and see example below):
cat>/etc/docker/edge/.env<< EOFXIVOCC_TAG=2022.10XIVOCC_DIST=latestXIVOCC_HOST=<IP ADDRESS OF THE XIVO CC/UC (xucserver/xucmgt/nginx server)>XIVO_HOST=<IP ADDRESS OF THE XIVO>EDGE_FQDN=<XIVO EDGE FQDN>EDGE_KAMAILIO_HOST=<IP ADDRESS OF THE KAMAILIO SERVER>EOF
This step is to be done on the server which will host the SIP Proxy (kamailio) service
Create the .env file with the following variables (replace values accordingly, and see example below):
cat>/etc/docker/edge/.env<< EOFXIVOCC_TAG=2022.10XIVOCC_DIST=latestEDGE_FQDN=<XIVO EDGE FQDN>XIVO_HOST=<IP ADDRESS OF THE XIVO>XIVO_MDS_HOST_DEFAULT="default: <DATA IP ADDRESS TO MDS DEFAULT>"EDGE_HOST_IP=<Edge server IP on which to listen>EOF
Important
If you configure the Edge Solution for a XDS installation you must:
add to the .env file a line per MDS with the following format:
XIVO_MDS_HOST_MDS1="<mds technical name>: <DATA IP ADDRESS TO MDS1>"
For example: XIVO_MDS_HOST_MDS1="mds1:192.168.240.2"
Mandatory step: You need to change any underscore in your mds naming to an hyphen
For example, for an mds named media_server_1 : XIVO_MDS_HOST_MDS1="media-server-1:192.168.240.2"
and add to the extra_hosts section of the kamailio service the
variable XIVO_MDS_HOST_MDS1
This step is to be done on the server which will host the STUN/TURN Server (coturn) service
Create the .env file with the following variables (replace values accordingly, and see example below):
cat>/etc/docker/edge/.env<< EOFXIVOCC_TAG=2022.10XIVOCC_DIST=latestEDGE_HOST_IP=<IP OF THE STUN/TURN SERVER>XIVO_HOST=<IP ADDRESS OF THE XIVO>TURN_EXTERNAL_IP=<External IP of the edge Server>TURN_SERVER_SECRET=<TURN_SECRET>TURN_REALM=<domain name of client>TURN_ALLOWED_PEERS=<list of allowed peers IP>EOF
Create the .env file with the following variables (replace values accordingly, and see example below):
cat>/etc/docker/edge/.env<< EOFXIVOCC_TAG=2022.10XIVOCC_DIST=latestXIVOCC_HOST=<IP ADDRESS OF THE XIVOCC>XIVO_HOST=<IP ADDRESS OF THE XIVO>EDGE_FQDN=<EDGE FQDN>TURN_SERVER_SECRET=<TURN_SECRET>TURN_REALM=<EDGE DOMAIN>EDGE_HOST_IP=<EDGE HOST IP>TURN_EXTERNAL_IP=<EDGE HOST IP>TURN_ALLOWED_PEERS=<list of allowed peers IP>XIVO_MDS_HOST_DEFAULT="default: <DATA IP ADDRESS TO MDS DEFAULT>"EOF
Specific steps when configuring the Edge Solution with XDS architecture
Add alias for MDS IP (for SIP Proxy): you must add the MDS in the extra_host
section of the SIP Proxy yml file. For this do:
add to the .env file a line per MDS with the following format:
XIVO_MDS_HOST_MDS1="<mds technical name>: <DATA IP ADDRESS TO MDS1>"
For example: XIVO_MDS_HOST_MDS1="mds1:192.168.240.2"
Mandatory step: You need to change any underscore in your mds naming to an hyphen
For example, for an mds named media_server_1 : XIVO_MDS_HOST_MDS1="media-server-1:192.168.240.2"
and add to the extra_hosts section of the kamailio service the
defined variable XIVO_MDS_HOST_MDS1 (in file kamailio-edge.yml):
On XiVO CC server (the server which hosts the xucmgt/xucserver and nginx) add the following variables in the /etc/docker/compose/custom.env file:
add XUC_INTERNAL_HOST=<XIVOCC_IP>
change XUC_HOST to the EDGE FQDN
and add the TURN_SERVER_SECRET with the <TURN_SECRET> value
(the <TURN_SECRET> is the secret generated for during TURN Server Secret)
specify the REPORTING_HOST and ELASTICSEARCH_HOST to the XiVO CC LAN IP address in order for SpagoBI and Kibana report to work (note that SpagoBI and Kibana work only if you access them via the internal LAN IP address).
in order for the history to work add the RECORDING_SERVER_HOST=<IP of recording server>
Optionally you can override ice gathering timeout (by default 2000 milliseconds) to a shorter value thanks to ICE_GATHERING_TIMEOUT_MS
On the XiVO you need to configure the STUN/TURN server address.
Warning
Your Edge installation must be up and running when you do this step.
As soon as you change this configuration all WebRTC users won’t work without the Edge Solution.
In the XiVO Admin webi Services -> IPBX -> General Settings -> SIP Protocol
tab Network
In parameter XiVO Edge FQDN enter the TURN server
address with format FQDN:3478 or IP:3478 (you must put port 3478).
Warning: this FQDN must be resolvable and reachable from the XiVO & Public Internet.
1 Server deployment: use the server public IP address or FQDN (i.e. edge.mycompany.com or DMZ_IP1 in 1 Server Schema)
3 Servers deployment: use the TURN server public IP address or FQDN (i.e. DMZ_IP3 in 3 Servers Schema)
Click save: it will reload the SIP and the RTP configuration of the XiVO (Main and MDS if any)
Then on each XiVO/MDS run the following script to generate the credentials for the TURN server
(the <TURN_SECRET> is the secret generated during TURN Server Secret):
xivo-edge-gen-turn-cred<TURN_SECRET>
This script will generate new turn username and password in /etc/asterisk/rtp.d/01-xivo-edge-turn-cred.conf
You then need to reload the rtp configuration
asterisk-rx'module reload res_rtp_asterisk.so'
Note
The turn address turnaddr is generated by confgend (see conf in file /etc/asterisk/rtp.conf).
it means that XiVO can’t reach (at the network level) one of the peer
candidates. But it would that the xivo doesn’t have network route toward
this peer candidate. It should not happen if the XiVO is correctly
configured with a default route.
The TURN server is by default configured to not relay towards internal network. One must whitelist the at least the XIVO IP (and MDS and Meetingroom server if you have one) - see TURN section of TURN Server Relay Authorization.
If you see these logs for an IP of either the XIVO or the MDS or the Meetingroom server then it may mean that you didn’t configure the relay permission correctly:
For example in the log above the coturn server does not accept to relay traffic towards 10.32.0.1 IP address.
It’s ok as long as 10.32.0.1 is not one of the XIVO or the MDS (or the Meetingroom) server IP address.
The TURN server is by default configured to not relay towards internal network. One must whitelist the at least the XIVO IP (and MDS and Meetingroom server if you have one) - see TURN section of TURN Server Relay Authorization.
If you see these logs for an IP of either the XIVO or the MDS or the Meetingroom server then it may mean that you didn’t configure the relay permission correctly:
For example in the log above the coturn server does not accept to relay traffic towards 10.32.0.5 IP address.
It’s ok as long as 10.32.0.5 is not one of the XIVO or the MDS (or the Meetingroom) server IP address.
By default OCSP is enabled.
For OCSP to work the Intermediate Certificate must be correctly installed. Normally this should be ok if you
did install the fullchain certificate as specified in the SSL Certificates config section.
If it is not the case one could deactivate OCSP for the web proxy by adding the following in the env file:
To be able to use the TURN server you must have valid credentials.
Credentials are given by the xucserver to the WebRTC client.
These credentials are generated by the xucserver and validated/verified
by the TURN server via a shared secret defined:
in xuc via the TURN_SERVER_SECRET variable
in TURN Server via the static-auth-secret parameter
By default only TURN is activated for both asterisk and WebRTC client.
This can be changed via the TURN_SERVER_ENABLE and STUN_SERVER_ENABLE variables to be put in the custome.env of the XiVO CC
These credentials are valid for a default lifetime of 3600s. The
WebRTC client renew the credential every TTL/2.
The TTL can be changed via the TURN_SERVER_CREDENTIAL_TTL xuc
environment variable. To change the credential TTL to 2hours add the
following in the XiVOCC custom.env file:
When A wants to call B, A will start - before sending the SIP INVITE, by
gathering what is called the “candidate”. This is A’s host IP addresses
and also what the STUN/TURN server will give him.
The more host IP addresses A has, the longer the STUN/TURN gathering
will take. Not to say that it also depends on the fact that these IP
addresses can reach the STUN/TURN server.
On the UC Application side this cannot be tweaked. But the candidate
gathering process is limited to 2 seconds.
On asterisk side this can be enhanced by setting a stun and ice
blacklist rule. This can be done by adding the following lines in a
file in /etc/asterisk/rtp.d/ directory (for example
/etc/asterisk/rtp.d/02-ice-optimization.conf):
If A calls B, when B answers, A and B will start to negotiate which RTP candidate they will use to communicate.
The longer the candidate list for A and B the greater the number of possibility and connectivity check to do.
On the UC Application side there is not much one can do except to shutdown some network interfaces.
But the candidate gathering process is limited to 2 seconds.
On asterisk side this can be enhanced by setting a stun and ice blacklist rule.
This can be done by adding the following lines in a file in /etc/asterisk/rtp.d/ directory
(for example /etc/asterisk/rtp.d/02-ice-optimization.conf):
Re-install the Meeting Room Launcher (it will override the .yml files): follow the 2. XiVO Meeting Rooms Launcher Setup steps to install new version
Note
This step overrides the current .yml files. If you had made some customization in them you will have to backport them by comparing the new one with the backup you did at previous step.
And then verify that the content of the .env file is correct:
Launch the following commands that will generate the .env file:
Warning
Please Copy the whole code block below and Paste it in a terminal. It will (re)generate the .env file.
Do not copy-paste only the .env content because it contains specific here-document syntax.
functiongeneratePassword(){opensslrand-hex16}JICOFO_AUTH_PASSWORD=$(generatePassword)JVB_AUTH_PASSWORD=$(generatePassword)JIGASI_XMPP_PASSWORD=$(generatePassword)JIGASI_SIP_PASSWORD=$(generatePassword)
cat>/etc/docker/meetingrooms/.env<< EOF# XiVO varsXIVOCC_TAG=2022.10XIVOCC_DIST=latestXUC_HOST=<FILL IN>MEETING_ROOMS_HOST_IP=<FILL IN>XIVO_HOST=<FILL IN>## XiVO Edge vars#TURN_CREDENTIALS=<FILL IN>TURN_HOST=<FILL IN>TURN_PORT=3478TURNS_HOST=\${TURN_HOST}TURNS_PORT=3478## JWT ConfigurationENABLE_AUTH=1ENABLE_GUESTS=0AUTH_TYPE=jwtJWT_APP_ID=xivoJWT_APP_SECRET=<FILL IN>## Security#JICOFO_AUTH_PASSWORD=${JICOFO_AUTH_PASSWORD}JVB_AUTH_PASSWORD=${JVB_AUTH_PASSWORD}JIGASI_XMPP_PASSWORD=${JIGASI_XMPP_PASSWORD}## Basic config#CONFIG=/etc/docker/meetingrooms/jitsi/DOCKER_HOST_ADDRESS=\${MEETING_ROOMS_HOST_IP}HTTP_PORT=80HTTPS_PORT=443TZ=Europe/ParisPUBLIC_URL=https://\${XUC_HOST}/videoENABLE_CLOSE_PAGE=trueENABLE_SIMULCAST=falseENABLE_BACKGROUND_SELECTION=false## Basic Jigasi configuration options#JIGASI_SIP_URI=xivo-jitsi@\${XIVO_HOST}JIGASI_SIP_PASSWORD=${JIGASI_SIP_PASSWORD}JIGASI_SIP_SERVER=\${XIVO_HOST}JIGASI_SIP_PORT=5060JIGASI_SIP_TRANSPORT=UDP## Basic Video configuration option#DESKTOP_SHARING_FRAMERATE_MIN=5DESKTOP_SHARING_FRAMERATE_MAX=30## Advanced configuration options (you generally don't need to change these)#XMPP_DOMAIN=meet.jitsiXMPP_SERVER=xmpp.meet.jitsiXMPP_BOSH_URL_BASE=http://xmpp.meet.jitsi:5280XMPP_AUTH_DOMAIN=auth.meet.jitsiXMPP_MUC_DOMAIN=muc.meet.jitsiXMPP_MODULES=muc_sizeXMPP_INTERNAL_MUC_DOMAIN=internal-muc.meet.jitsiXMPP_GUEST_DOMAIN=guest.meet.jitsiJVB_BREWERY_MUC=jvbbreweryJVB_AUTH_USER=jvbJVB_STUN_SERVERS=meet-jit-si-turnrelay.jitsi.net:443JVB_PORT=10000JVB_TCP_HARVESTER_DISABLED=trueJVB_TCP_PORT=4443JVB_TCP_MAPPED_PORT=4443JICOFO_AUTH_USER=focusJIGASI_XMPP_USER=jigasiJIGASI_BREWERY_MUC=jigasibreweryJIGASI_PORT_MIN=20000JIGASI_PORT_MAX=20050XMPP_RECORDER_DOMAIN=recorder.meet.jitsiJIBRI_RECORDER_USER=recorderJIBRI_XMPP_USER=jibriJIBRI_BREWERY_MUC=jibribreweryJIBRI_PENDING_TIMEOUT=90RESTART_POLICY=unless-stoppedENABLE_P2P=falseEOF
Then open the /etc/docker/meetingrooms/.env and fill in:
XUC_HOST var with the same content as the XUC_HOST var in your XiVO CC
configuration
MEETING_ROOMS_HOST_IP var with the meeting rooms server IP address.
It must be the meeting rooms server IP address accessible for your LAN client.
It must be set otherwise nothing will work correctly.
XIVO_HOST with the VoIP IP of the XiVO PBX
It will be the IP towards which the Jitsi SIP gateway will register
its SIP peer.
JWT_APP_SECRET with the same content as the CONFIGMGT_AUTH_SECRET var defined in your XiVO’s /etc/docker/xivo/custom.env file
Fill in also parameters linked to XiVO Edge (which is a prerequisite to use Meeting Room Server - see Requirements):
TURN_HOST var with the Edge STUN/TURN server FQDN
(i.e. which must be a FQDN corresponding to the certificate configured on the Edge STUN/TURN server).
TURN_CREDENTIALS var with the value of the TURN_SECRET configure in the Edge TURN Server (the secret generated during TURN Server Secret).
MEETINGROOM_AUTH_DOMAIN=<The domain serving the service, i.e. "meet.jitsi" by default, can be also set to "*">MEETINGROOM_AUTH_APP_ID=<Value of the JWT_APP_ID defined in your jitsi .env file>
Personal meeting room creation can only be done via the UC Assistant (it is not available for CC Agent or Switchboard)
There is no history of the video calls/conference (no history of video conference you joined nor video conference invitation you received/missed)
There must be at least one video participant for the meeting room to work.
If only audio participants are in the conference they won’t be able to speak to each other.
Invite to conference / Start a video call:
these features currently works only if the chat is enabled
the invite to conference invitation has a timeout set to 15s which is not configurable
if PIN code is modified while you are already in one of your personal meeting room, you can’t invite other people until you leave then rejoin it
CC Agent / Switchboard related notes:
these features do not work for a “roaming agent”: i.e. an agent that is logged on another user’s line (it applies to CC Agent or Switchboard application)
when an agent is in a meetingroom, he still receives queue calls. He has to put himself on pause manually to prevent it.
The background selection can become quite hungry for your network and your hardware, and may affect the other inputs of the conference. Be sure that your connection and architecture are strong enough before choosing to establish it.
Therefore performance issues with meetingrooms using this feature cannot be addressed to our support
Starting with the Izar LTS, it becomes possible to allow users in a Meeting Room to select their own background during the meeting.
To do so, an administrator of the Meeting Rooms virtual machine must add or edit the following environment variable in the /etc/docker/meetingrooms/.env file, preferably in the #Basic config section :
ENABLE_BACKGROUND_SELECTION=true
Then the jitsi web container must be recreated :
meetingrooms-dcompup-dweb
To select the background, the users in the conference must go to the … on the option bar then click on the Select background option.
Here they get to chose a background among the ones available by default, from an image file on their machine, or to dynamically share one of their application as a background.
They can also blur instead their default background if they want to. The application remembers the last used background for the next conference.
To disable it, you need to remove the variable from the /etc/docker/meetingrooms/.env file or setting it to false instead of true, then to recreate the jitsi web container once more.
You can also access a Meeting Room with a phone by dialing **MEETING_ROOM_NUMBER where MEETING_ROOM_NUMBER is the Meeting Room number.
You can only access Meeting Room which are configured the XiVO PBX with a number.
Given the XiVO PBX admin user created a Meeting Room:
Name: ProjectManagerConf
Display Name: Project Manager Conf
Number: 5000
Then someone can join the conference via its phone set by dialing: **5000
You can create a personal meeting room from the UCAssistant menu, with the name and pincode of your choice.
Other users can join a personal meeting room in a browser with an invitation link that can be found by the creator
of the room, when clicking on his meetingroom in the search results or favorites (share button).
In order to create a static meeting room in XiVO (meaning available for all the users of the XIVO)
go to Services ‣ IPBX ‣ IPBX Settings ‣ Meeting rooms
In order to use built-in IVR for Meeting Rooms in XiVO PBX, create an incoming call that will be available for remote users to join MR externally
go to Services ‣ IPBX ‣ IPBX Settings ‣ Call Management ‣ Incoming Calls
DID: your incoming call extension
Context: your incoming calls context (default is from-extern)
In menu Services->IPBX in Call management section use
option IVR. The page shows list of existing IVRs. Buttons in every IVR line
allows you to edit IVR dialplan metadata, edit dialplan and delete dialplan.
Dialplan flowchart consists of nodes representing dialplan actions and
connections between nodes. Every node type has one entry point (large circle on top of the node
rectangle) and this entry point accepts many connection lines. Exceptions are nodes Start, OnHangup and OnError
which have no entrypoint. Depending on node type, nodes have zero to many exit points (small circles
at bottom of node rectangle). Exit point of node is selected at runtime by
result of node action.
In editor you can
Add node to editor pane by clicking on node type in left menu.
Delete node by clicking red cross on node
Set node parameters by clicking pencil on top left node corner anf filling form
Interconnect nodes by dragging exit point of one node to entry point of another or same node
Delete connection line by clicking on rectangle with minus sign on the line
IVR dialplan always starts on Start node. This node can be only one in
flowchart and cannot be deleted. If caller hangs up in IVR dialplan, call is
moved to OnHangup node, if one exists in flowchart. Only one OnHangup node
can exists in flowchart. If runtime error happens (nonexistent voice prompt
file, wrong expression parameter) call is sent to the OnError node if one
exists. Only one OnError node can exist in flowchart.
Variables in IVR dialplan are NOT the same thing as asterisk dialplan
variables. Variables can be set at runtime using assign node or as result
of node action. Variable name must start with ‘$’ (dollar sign).
Node parameters can be constants or expressions.
For example node type ‘wait’ has parameter ‘seconds’ which defines time to
wait. This parameter can contain
2constant
=2+2expression
=10+$varexpressionwithvariable
String expression can contain string constants in apostrophes or quotes,
variables and concatenation operator ‘.’.
Numeric expressions can contain integer numbers, variables and operators ‘+’, ‘-’, ‘*’, ‘/’,
Logical expressions can contain comparision operators ‘==’, ‘!=’, ‘<’,
‘<=’, ‘>’, ‘<’, ‘>=’ and logical operators ‘!’, ‘&&’, ‘||’.
Expressions in node parameters are evaluated at runtime when node action
starts.
Some input fields are listboxes by nature, e.g. voice prompt file is selected
from existing files. In such case listbox can be swithced to text input field by
clicking to icon next the field label, to allow insert expresion.
E.g. if you have voice prompt files
message-en
message-fr
message-de
you can set variable $lang in dialplan and then expression:
= "message-" . $lang
allows you to use right language variant of message.
This node starts flowchart part which is used after caller hangup,
The node has no entry point therefore.
Only one node of type onhangup can be present in flowchart.
This node starts flowchart part which is used after runtime error.
The node has no entry point therefore.
Only one node of type onerror can be present in flowchart.
Sends HTTP(S) request
For GET request variables are used in URL query string
For POST request variables are sent as application/x-www-form-urlencoded data
Variable names in request are used without starting dollar sign.
Parameters
URL: URL of the request
Method: Request method
Variables: space separated list of variables used in request
Waits for DTMF digit, waiting is limited by ‘Timeout’ parameter
If DTMF digit is received and is listed in ‘Valid options’ parameter, corresponding node exit point is used.
If DTMF digit received is not listed in ‘Valid options’ parameter, file defined in parameter ‘Invalid voiceprompt’ is played and node is started again, unless number of tries defined in parameter ‘Repeat’ is reached.
If no DTMF digit is received till timeout, file defined in parameter ‘No choice voiceprompt’ is played and and node is started again, unless number of tries defined in parameter ‘Repeat’ is reached.
Node uses ‘f’ exit
Parameters
Repeat: Number of attempts to receive DTMF digit
Timeout: Time in seconds for which node waits for a DTMF digit
Valid options: List of expected DTMF digits (without any delimiter)
Menu voiceprompt: File played at node start
No choice voiceprompt: File played when no digit has been sent
Invalid voiceprompt: File played when unexpected DTMF digit has been sent
Exit points
0-9,A-D,*,#: used when corresponding DTMF digit has been sent and accepted by node
The XiVO mobile application should be used with at least the IZAR version of XiVO.
The XiVO must contain an EGDE infrastructure allowing teleworkers or travelling workers to be able to access XiVO from outside.
Follow the official documentation on required ports : See https://documentation.xivo.solutions/en/2022.10/edge/architecture.html#id3
Manufacturer’s software layer may create unattended behavior on unsupported devices. Please open a ticket to describe device - with OS version and the bug.
It is imperative t make preliminary tests on the mobiles which would not be compatible.
If you encounter problems, you can send an email to the support directly via the mobile application. It is however important to have configured on your mobile an application to send emails.
The logs of the mobile application are sent in an attached file in this email.
Push notification is a technology used in the XiVO server and the mobile application.
Since the Izar version, you can ring multiple devices at the same time.
When you choose to ring the mobile application and the UCAssistant, the system will know when the devices are both ready to receive the incoming call.
As the UC assistant is connected directly to the server via the web interface, this will be relatively quick.
For the mobile application, the operating systems (Android and IOS) are using a “DOZE” mode.
This mode closes the application when it has not been used for some time, to reduce the consumption of the battery.
To wake up the application, we use the push notification that goes through a public push server.
It will send a notification to the mobile to wake up the XiVO mobile application.
You might need to wait a certain time after you launched the call for the mobile application to wake up. This time can vary from one to ten seconds, depending on the push servers and the network quality.
Once the mobile application responds, we start ringing the available devices.
UC Assistant: Fast ringing on the UC direct connection to the web browser or desktop
Mobile application: Launching the ringtone on the mobile application when it will be awakened. The mode of operation used is the push notification. There can be a waiting time.
UC + Mobile Application: There is a delay before launching the ringtone on both devices, the time for the mobile application to wake up.
If the user looses access to the Internet, the application switches to a non-usable mode until access is regained (see screenshot below).
This display is removed when there is an internet access.
If you encounter an unsual behaviour and you manage to reproduce it on your application, you can send the logs directly via the configuration and click on Send logs to support.
Warning: The logs are sent by email, you must therefore have a messaging system configured on your phone.
If you didn’t give all the authorizations needed to use the mobile app, this error message will be displayed the next time you open the application.
This means the XiVO phone account is not active.
In this case, you should click the OK button and will be redirected to the settings.
If the phone is a “Samsung”, the phone accounts settings will be opened. You just have to activate the check mark next to XiVO.
If the phone is not a Samsung, you will be redirected to the wrong settings. You will need to search in your phone settings where to activate the XiVO phone account.
You can change the value of XIVO_MAPP_WAIT_WITH_MUSIC in the file /etc/xivo/asterisk/xivo_globals.conf to customize the ringtone behavior.
If the value is set to True, you will hear the default music on hold while attempting to reach to a user with a mobile application. Otherwise, you will hear a regular ringtone.
XIVO_MAPP_WAIT_WITH_MUSIC="True"
In case you do want to completely disable this, then you can set the value of XIVO_PLAY_MSG to False which will make caller hear a regular ringtone.
Before calling a user with a Mobile App, we wait for the mobile app to wake up (and (re)register (SIP level)).
By default we wait 15s: 3 loops of 5s.
If the Mobile App never wakes up (or never (re)registers) the call will continue depending on the callee ringing device:
if it was Mobile application: it will end up in user’s no answer scenario
if it was UC Assistant + Mobile application: it will call the UC Assistant
The time we wait for the Mobile App to wake up is configurable by configuring the number of loops, interval between two loops is now configurable too.
To do so, adjust the following two variables in the file /etc/xivo/asterisk/xivo_globals.conf:
XIVO_MAPP_LOOPS_MOBILEAPP configures the number of loops if the callee ringing device is Mobile application
XIVO_MAPP_LOOPS_WEBAPPANDMOBILEAPP configures the number of loops if the callee ringing device is UC Assistant + Mobile application
XIVO_MAPP_LOOPS_INTERVAL configures the time between two loops
Therefore you might, for example, want to:
lower the number of loops when ringing device is UC Assistant + Mobile application: in order to fallback more quickly on the UC Assistant if the Mobile App does not wake up
and increase the number of loops when ringing device is Mobile application: in order to give more time to the Mobile App to wake up before going to the callee no answer scenario
another more dynamic but risky scenario is to disable the message via XIVO_PLAY_MSG, then reducing the time between loops via XIVO_MAPP_LOOPS_INTERVAL, in this scenario, we advice you not to forget to adapt the loops number to give sufficient time to the MobileApp to wake up.
This section describes the feature of the UC Assistant application.
It is available as a web application from your Web Browser.
It is also available as a desktop application with these additionnal features:
show OS integrated notifications when receiving call
get keyboard shortcut to answer/hangup and make call using Select2Call feature
To login, you must have a user configured on the XiVO PBX with:
CTI Login enabled,
Login, password and profile configured
A configured line with a number
Warning
If a user tries to login without a line, an error message is displayed and
user is redirected to the login page (this applies also to Desktop Applications )
Note
Automatic login keeps you signed in until you log out.
From UC Assistant you can activate Do Not Disturb to block all incoming calls or forward call to any another number just by clicking on action button as seen on following screenshot:
You can then change your settings and enable them.
Action possibles are :
Enable DND
Disable DND
Edit call forwarding (for both unconditional or on missed call only)
You know that all incoming calls will be rejected once you see the following logo in the header bar :
All calls are forwarded once you see this following one :
Finally, calls are forwarded only if you missed it when you see this one :
Note
If calls are redirected, the forward number will be shown under your name.
Nevertheless, there is a precedence, if DND mode is enabled and also call forwarding, calls will be rejected.
The call history tab lists all the recent calls you were part of. For each call, it displays the status (received, emitted…), the duration, as well as
the time when the call happened. You also see the phone status of internal users. You can hover your mouse cursor on a call to add this phone to your contact, or call it. You can also click on it to
unfold it and see the call(s) details.
From top-right hamburger menu, it is possible to display additional actions to handle you personal contacts.
You will be able to create, delete all, import and export personal contact that you will be either able to search from the toolbar or find them in favorites panel if starred.
From menu, you can upload a .csv file that contains all the data of your personal contacts. You can either use a file exported from this same interface or create yours.
Here are the list of available attributes of a personal contact:
company
email
fax
firstname
lastname
mobile
number
As an example here a csv file that can be imported
By default, reverse lookup is enabled for personal contact display on incoming calls. Configuration is set to display firstname and lastname if number or mobile matches an existing personal contact.
Once, you’re phone is properly configured and you are connected as a user, you know that your using SIP phone once you see the following logo in the header bar :
When joining a conference, either as an attendee or an organizer, the UC Assistant will display specific informations about the conference you are joining.
Note
On WebRTC and Snom phones you can also do a device hosted three-party conference, in this section we describe
features of the XiVO hosted conferences.
Exit a conference room by clicking the hangup button
Put the conference on hold. Other attendees will not hear any hold music (if you’re on the same XiVO) but will not be able to hear you neither you will be able to hear the conference room.
As an organizer, you will also be able to:
Mute/Unmute all other attendee in the conference room
Mute/Unmute itself. If the participant is muted and starts speaking, the microphone icon in the volume meter will blink in red as a reminder. This red warning only happens in audio conferences, not in normal phone calls.
Organizer can also:
Mute/Unmute any attendee
Kick out an attendee. A message will be played to the kicked out attendee before leaving the conference.
Invite a user to the conference.
This can be done by clicking the invite to conference button in the user dropdown menu :
from the favorites tab,
or from the search results, by searching for a username.
The organizer can also invite a phone number to a conference via the additional call options. This option will be displayed after the organizer starts typing a phone number in the search bar.
It is possible from the assistant to send chat messages and have private text conversation.
It is possible to deactivate it if this feature is not suitable for your needs or if you have already an external chat application, see Disabling chat in UC Assistant and Switchboard.
There are two possible behaviors for handling messages:
No persistance (default) : Each message is an instant message that can be sent to another user logged in. messages are not stored anywhere and will be discarded once you refresh the page or log out.
With persistence : Can be enabled with Chat Backend. This allows then
To send messages to offline users
To retrieve you conversation history with other parties
To receive notifications when you logs in if you have unread messages that has been received while you were disconnected.
When you send a message, you are notified if the message was sent successfully or
if the message was not received because the recipient is not logged in.
When you receive a message, you are notified with a orange badge on the message tabs.
If you are using the desktop application, the electron tray icon also shows an orange badge.
You will also have a notification from your web browser or a system notification if you are using the desktop application.
You can send links in message, they will be clickable.
You can also write emojis from your keyboard (e.g., :smile:). You can find here some emojis exemple.
The conversation window also allows you to call a user on their internal phone number directly from the chat.
To do so, you can click on the phone icon next to the name of the user you’re chatting with.
If the video calls are available on your XiVO, you can launch one by clicking on the camera.
You can send a message from different places in the application :
From the contact line :
From an ongoing call :
from a conference call :
You are also able to list, at any time, all your ongoing conversation from the message tab :
This feature will add an additional book icon on the left side of the search bar.
When clicking on this book icon, it will open (or close) the defined external directory (the external directory being a directory accessible via an URL).
The search in the search bar will not search in this directory. But a search could be implemented in this external directory.
The screenshot below shows an example: when clicking on the book icon the external directory is shown. Here this external directory
was developped to list users per site.
This section concerns only WebRTC users, not Unique Account or SIP phone users.
After a user connects to the mobile application for the first time, a pop up notification will be sent on their UCAssistant. This is to inform the user that they will now receive calls on both mobile and web application.
The user will be able to change this by clicking on the call management section :
They can then choose if they want to receive calls on the mobile application, web application, or on both.
After a user uninstalled the mobile application, they can unpair the mobile app from the assistant by clicking on the chain icon next to the mobile option.
This section describes the Switchboard application features. It is available as a web application from your
Web Browser.
Currently it is not available as a desktop application.
What is the Switchboard application ?
Switchboard is a Web application for switchboard operators.
It is designed to handle the call flow of a company switchboard:
see current incoming calls,
answer incoming calls,
easy search/transfer to user of the company
being able to put calls in hold
All these actions can be used through keyboard shortcuts.
When the switchboard receives a call, the new call is added to the Incoming Calls list on the top right
and the phone starts ringing. The ccagent panel displays the client history tab of the person who is calling.
The operator can answer this call by:
clicking the Answer button on the left side, from the CCagent frame.
Pressing the F3 key.
Once the call has been answered, it is removed from the incoming calls list and only
displayed in the CCagent frame on the left side.
The switchboard operator can put a call on hold by :
clicking the Hold button (hourglass icon) in the call control
pressing the F9 key
When placing the call on hold, it will be removed from the Call control frame and displayed in the Calls on hold list on the bottom right.
The time counter shows how long the call has been on hold. The calls are ordered from the oldest to the newest.
In the example below, the switchboard operator put two calls on hold and can now answer the incoming call that is currently ringing.
The same shortcuts as the ones defined in CC Agent are available in the switchboard : see CC Agent shortcuts
In addition, the switchboard allow you to navigate in the hold queue calls list using Pageup and Pagedown keys, and to retrieve a call by pressing Enter.
It also has two exclusive keybindings :
F8 to complete a direct transfer the current ongoing call to the phone number in the search bar
The switchboard operator can use the chat to start a conversation with an UC Assistant user or another switchboard operator.
For more information about available chat features you can refer to Instant Messaging
To test your microphone and speaker, you may call the echo test application. After a welcome message, the application will
echo everything what you speak.
Dial the *55 number.
You should hear the “Echo” announcement.
After the announcement, you will hear back everything you say.
If you hear what you are saying it means that your microphone and speakers are working.
Press # or hangup to exit the echo test application.
New feature of Freya. Works only with devices in the supported list on Windows 10.
This new feature allows plantronics devices among the supported list to answer or hangup calls with their associated button.
Besides the plantronics device, it requires the plantronics hub to be installed and running on the user Windows 10 machine.
The plantronics service is loaded when logging in.
To use it correctly be sure to have your device connected and to have the plantronics hub (referenced as plantronics software) running while logging in.
Depending of the case, pushing the button should start the followings actions :
if your webrtc is ringing, you will answer
if your webrtc is dialing, you will hangup
if you are in a call or a conference, you will hangup
if the only call or conference you have is on hold, you will retrieve it
Each of those actions can still be completed as usual, but the service offers you a new way to do them.
When receiving a call, your computer will play a ringing sound. However, you can choose to play this sound on a separate audio device than the default selected by your operating system. For example, on a configuration with a headset, this device may be your default device but you can override this selection to play the ringing sound on your computer instead.
You can also choose to change your ringtone sound, both those options are available in the respective menu of the UCAssistant, CCAgent, and Switchboard, on the top right corner.
This feature is only available when using a WebRTC line.
Being a webrtc user allows you to mute your microphone while being in a call with somebody. Clicking this button again will unmute the microphone. Clicking directly on the volume meter will have the same effect as clicking on the mute button. The little microphone icon in the volume meter will change according to your mute state.
If the call quality can be impacted by some network issues or server configuration issues, a small message will appear.
The message will stay up to 10 seconds after the audio quality is back to normal.
The advanced statistics in the “show details” section and the play icon colors are updated live.
The current treshold are as following :
Quality goes to medium when something is higher than :
Jitter: 50 ms
Packet losts: 10%
Round trip time: 150 ms
Quality goes to bad when something is higher than :
If the quality of a call goes wrong, a live statistics feedback will be sent to the server.
There will also be an automatic feedback at the end of each call, giving informations on the point where the call quality was at it’s worst state.
For more informations on those logs - see Audio quality issues.
The XiVO Desktop Application is a standalone executable for either UC Assistant, Switchboard and CC Agent Environment. It is available for Windows (64bits) and Linux
Debian based distributions (64bits). It offers some additional features compares to the existing web version that can be run in a browser.
The UC Assistant and CC Agent are available as desktop application through Electron packaging, to be able to use these applications in a standalone executable you need to deploy this container first on client machine.
Or you can download it by opening the following url from your computer:
https://<xivo_uc_cc>/install/win64
and then start the downloaded program.
Note
If you have a secured installation (using https/wss) the port can be omitted as the default
port is already 443, generally speaking use the uc-assistant URL followed by /install/win64.
To install the latest version, you need to add a repository linked to the XiVO UC/CC CTI Server host. Create the file /etc/apt/sources.list.d/xivo-desktop-assistant.list containing the following line:
On first launch the application will display the settings page and ask for the application server.
Basically it should be the IP address of your server
If you don’t know it, you need to ask your system administrator or refer to Protocol and Application Server paragraph.
The top menu (accessible through tray icon or right click on the logo) allows you to navigate either to the application or to the settings page. If you did not enter any setting, the application will redirect you to the settings page.
This field allow you to define one shortcut in application to handle all basic actions that can be done for managing calls. With one combination keypress you should be able to:
Call the phone number contained in your clipboard (a.k.a Select2Call)
Answer a call if phone is ringing
Hangup if you are already on call
Note
To be able to call someone, you must beforehand have copied in your clipboard a phone number from any source (web page, e-mail, text document…)
Linux: select phone number then trigger shortcut
Windows: select phone number, type Ctrl+C then trigger shortcut
Default Select2Call shortcut is Ctrl+Space for Windows and Linux, you can either change it or disable it by leaving the field blank.
Warning
You must be logged in for using global shortcut and automatic dialing to work.
The Desktop Application can handle telephone number links that appear in web pages. The Desktop Application will
automatically dial the number when you click on a link.
It is supported on both Windows and Linux Debian based distributions (with a desktop environment compatible with Freedesktop).
You can specify your Desktop Assistant parameters by providing a xivoconfig.ini file or by editing the one that gets created automatically
on first launch.
Note
For Windows, this file must be located in user’s %APPDATA%/xivo-desktop-assistant/application/config.
For Linux, this file must be located in user’s $HOME/.config/xivo-desktop-assistant/application/config.
Below is an example of xivoconfig.ini file keys in use:
The Desktop Application can be started with following options:
--ignore-certificate-errors to disable certificate verification, this option is meant only for test purposes. You can use it with self-signed certificates.
On Windows both options must be set to the shortcut xivo-desktop-assistant.exe pointing to application located in C:\Users\<USER>\AppData\Local\xivo\xivo-desktop-assistant.exe so that Target of shortcut looks like for example to:
C:\Users\IEUser\AppData\Local\xivo\xivo-desktop-assistant.exe--ignore-certificate-errors-d
It is possible to set an environment variable named CUSTOM_USER_DATA where will be stored application configuration. This is usefull if you want for example two shortcuts with two distincts configuration (one for UC Assistant and one for CC Agent) on the same desktop application installed.
On Windows here an example of two shortcuts that set the environment variable (uc or cc) and launch the application. Following lines must be updated with your Windows user name and correct XiVO version and must be set in Target field of the shortcut).
If you don’t want to have a Chrome popup like this one when you click each time on a tel: link on Windows to make a call through your desktop application
You can edit your registry base to modify this Chrome key to avoid this display each time you want to call someone from a webpage
Logs of application are available in order to debug a crash at startup or during usage of the application.
They do not contain Javascript console logs, but only the interactions with operating system, like global
shortcut key or callto and tel protocol.
Note
On Windows, logs are located in user’s %APPDATA%/xivo-desktop-assistant/application/logs.
On Linux, logs are located in user’s $HOME/.config/xivo-desktop-assistant/application/logs.
If needed, you can use the developper console to diagnose a problem “live”.
To access the console, right click on the xivo cloud on the top left corner of your application
Then, in the ‘debug’ menu, you can either open the devtool, or the webview’s devtool
The normal devtool is the one for the electron application. In this one, you will moslty find errors about shortcut keys,
callto and tel protocol, network, and everything system-related.
The webview devtool is the one for what’s opened inside the desktop application, so the ccagent or the ucassistant. this
devtool is the same one that you get when you open the devtool from the web application in Chrome. You will mostly find network errors or
the errors that are specific to the ucassistant and ccagent features.
The main reason to open devtools is to display the console, but you have another functionality used by the desktop application that you
might need to debug : the localstorage. It’s located in the application tab of the electron devtool. To check the variables set there, you need
to click localstorage on the left, and click file://.
The variables that are set in there are the one coming from the xivoconfig.ini (except for the shortcut) and could be the cause of a wrong configuration.
If you don’t succeed to reach login page of desired application (i.e. just give you the possibility to retry or to change parameters) and if you observe some errors about certificate in debug mode, you should
Take care if your move a *.cer to *.crt. You must concatenate a key file to your *.cer (catcertifcate.cercertificate.key>certificate.crt). Just rename it will not work
Check that XUC_HOST in /etc/docker/compose/custom.env is also configured with the same FQDN as in the certificate, not the IP address.
Once CC Agent is launched through standalone application, a new button appears to be able to switch between a vertical
minimalist view and default one.
The XiVO mobile application comes in addition to the UC Assistant. It allows you to access the services deployed on your XiVO environment via your smartphone. You will need a Wifi or 4/5G connection.
Note
The mobile application can be used in WebRTC mode only.
The use of the application can be :
Exclusive, i.e. it is your unique Xivo environment
Shared, i.e. a hybrid approach with your UC Assistant. Several combinations of call processing are then possible.
You can do the following actions:
Call
Receive a call
Transfer a call
Call via your favorites
Call by searching in the company directory
Call by searching in your local cell phone directory
Forwarding management
Call management
Visibility on the presence of your colleagues
Access to voice messaging
Access to the history
Pop-up notification for missed calls
Pop-up message notification on the voice mail.
The following services are not currently available :
The Xivo - Wisper mobile application is available on the Android Play Store. You need to search for the “XiVO” application.
Once on the application you can tap install and then open the application.
When you open the application for the first time, it will ask for different authorizations :
* Mandatory authorizations, for the application to function properly
* An optional authorization, to allow access to your phone contacts.
List of requested authorizations :
• Stop battery optimization
• View in the foreground of the application
• Microphone
• Phone account to make calls
• Local phone book contacts (Optional)
When you first connect to the application, a connection page will be displayed with the following fields :
the address of the telephony server,
your login,
your password
Where to find the server address:
On your Web browser
If you use your web browser to access Xivo, you will find the information directly in the address bar.
On your Desktop Assistant
THe server address is in the parameters, on the upper right corner of your desktop assistant. Once in the settings, use the information in “application server”.
If you use only the app for Xivo connectivité, please ask your IT manager for the url.
About the authentication fields:
You must use the username and password that you usually use when logging in.
When you first login, a notification will be displayed in your UC Assistant. It shows you that you can choose, via the call management, on which devices you want to receive calls. See gif below :
Once you are logged in, you will be taken to the home page which is a dial pad.
From this page you can access :
* A dial pad to initiate a call via a number
* Your Favorites
* Your History
* Your voice mail when you have one
* A search bar
* Access to the configuration
You can launch a call by typing a number on the keyboard. For example, if I type *55 to launch a call to the echo test, a call button appears at the bottom of the screen.
You can access your favorites through the button located at the bottom left of the mobile application.
Once in your favorites, you can launch a call by pressing directly on the handset on the right of the chosen contact.
You will also have a view on the status of your colleagues.
You can access your call history through the button on the bottom right of the mobile application.
In the history you will have the possibility to launch a call by pressing directly on the handset.
You’ll also be able to see the status of the other users.
In some cases, you might get “Your call is in transit, thank you for your patience” before getting the screen “your call is ringing”.
Once the person you are calling has picked up the phone you will be taken to the call management page.
You can transfer a call while being on a call.
There are two ways to do it:
* Pressing the “+” button allows you to go directly to the Favorites and select the person you want to reach for your transfer. Once you have selected your favorite, the call will be launched and the person you were talking to will be put on hold.
You can access the pages :
Favorites
History
Search
From one of these pages, you can launch a second call and put on hold the person with whom you were in a conversation.
When you receive a call while being already on a call, you can put your current call on hold. In this context, the person you put on hold will hear a music on hold. You can then resume the call via the play button.
During the installation and the first connection to the mobile application, you must have noticed a change in the call management of your UC assistant.
You can, on your UCAssistant select the ringing device:
This allows you to select either your XiVO client or the mobile application or both.
You can access the configuration by pressing the button on the top right corner of the call management.
In this menu you have access to the following actions:
-Remove access to my phone contacts
-Integration of your forwarding number
-Xivo server address
-Activation of call forwarding
You can disconnect and disable the app by pressing the button at the bottom center of the page.
When you log out, you wont be able to receive calls on your smartphone anymore. In this case, only the UC Assistant -or your browser - will ring if you are connected to it.
The xivo solutions web socket API enables you to integrate enterprise communication functions to your business application.
It exposes Cti functions using javascript methods calls and web socket events.
You may add your own handlers for your application to react to telephony / contact center events.
This API is using websockets, and therefore needs a modern browser supporting them (firefox, chrome …)
<!-- jquery needed as a dependency CDN from https://code.jquery.com/ -->
<script src="https://code.jquery.com/jquery-2.2.4.min.js"
integrity="sha256-BbhdlvQf/xTY9gja0Dq3HiwQF8LaCRTXxZKRutelT44="
crossorigin="anonymous"></script>
<script src="http://<xucserver>:<xucport>/assets/javascripts/shotgun.js" type="text/javascript"></script>
<script src="cti.js" type="text/javascript"></script>
<script src="callback.js" type="text/javascript"></script>
<script src="membership.js" type="text/javascript"></script>
<!-- Optionnaly Include also the xc_webrtc and SIPml5 javascript APIs for the webRTC support -->
<script src="xc_webrtc.js" type="text/javascript"></script>
<script src="SIPml-api.js" type="text/javascript"></script>
Please note that the websocket server integrates a throttling mechanism to prevent flooding. If you exceed more than 15 request messages in 30 seconds (with a burst of 25), your messages will be throttled and you will receive an error {msgType: “Error”, ctiMessage: {Error: “Maximum throttle throughput exceeded.”}}
Request a list of configuration objects, objectType can be :
queue
agent
queuemember
Triggers handlers QUEUELIST, AGENTLIST, QUEUEMEMBERLIST.
Subscribes to configuration modification changes, handlers QUEUECONFIG, AGENTCONFIG, QUEUEMEMBER can also be called
This command deprecates previously used Cti.searchDirectory(pattern).
This command deprecates previously used Cti.searchDirectory(pattern) removed in xuc xivo16 versions.
List all the statuses configured on XiVO to know which are possible pause reasons.
{"msgType":"UsersStatuses","ctiMessage":[{"name":"disconnected","color":"#9E9E9E","longName":"Déconnecté","actions":[{"name":"agentlogoff","parameters":""}]},{"name":"away","color":"#FFDD00","longName":"Sorti","actions":[{"name":"enablednd","parameters":"false"}]},{"name":"berightback","color":"#F2833A","longName":"Bientôt de retour","actions":[{"name":"enablednd","parameters":"false"}]},{"name":"available","color":"#9BC920","longName":"Disponible","actions":[{"name":"enablednd","parameters":"false"}]},{"name":"ook","color":"#FF0F0F","longName":"Far Away","actions":[{"name":"queuepause_all","parameters":"true"}]},{"name":"outtolunch","color":"#6CA6FF","longName":"Parti Manger","actions":[{"name":"queuepause_all","parameters":"true"},{"name":"enablednd","parameters":"false"}]},{"name":"donotdisturb","color":"#D13224","longName":"Ne pas déranger","actions":[{"name":"enablednd","parameters":"true"}]}]}
Triggered when config of the user is updated. This happens if forward config is modified or voicemail for example. Any change of the following attribute might trigger this event.
Attach data to the device current calls. When there is a call connected to a device, Data can be attached by passing
key values as a json object Cti.setData(“{‘var1’:’val1’,’USR_var2’:’val2’}”);
The folowing json message is then sent to the server :
When the call is transfered i.e. (Cti.directTransfer(destination)), data is sent in the event ringing see Phone Events,
and in subsequent events.
Data is not propagated in the reporting database.
Note that USR_ prefix is added to the key, if the key does not start with it. Only attached data beginning with USR_ are sent back to the client API.
Warning
When transfering a call, these variables are attached to the new channel however to prevent propagation on all trunk channels, your trunk name must contain ‘trunk’ so they can be distinguished from sip devices.
Place a call from logged user’s mobile number to destination with the provided variables. Variables must take the following form:
{var1:"value 1",var2:"value 2"}
USR_var1 and USR_var2 will be attached to the call and propagated to Phone Events
If dial fails, a failure Phone Events will be sent back to application.
When placing a call using this api, Phone Events will be sent through the websocket when calls state change.
If a call is made to a conference room hosted on the XiVO, Conference Events will be sent also.
Warning
When entering a conference room using this API, if the conference room is configured with an administrator PIN, the user will enter directly the conference room as an administrator without having to enter a PIN code. If the conference room has only a user PIN, the user will also enter directly without having to enter a PIN code.
Answers a call.
uniqueId is optional, but if you set it, you can explicitly answer a call among other ringing calls. (however, this parameter is for WebRTC only)
Put current call on hold. uniqueId is optional.
If uniqueId is set it you can explicitly hold/unhold a call among other calls. (however, this parameter is for WebRTC only)
Note that you can’t have two established. If you have one establish call and on call on hold, if you unhold this last call, the established will go automatically on hold.
Contains a list of attached data,
system data XIVO_ or data attached
to the call key beginning by USR_
username
Can be the username cti of called
number, it’s only defined when the
called user is an internal user
An event Failure can be sent when Cti.dial cannot be completed. Currently it is very specific and is triggered only in case of Originate (webrtc) and peer initiator of the call is not registered
you will get these data in the events. Data can also be attached using the Cti.dial command.
You can also request a message with a concatenation of PhoneEvents for current calls by Cti.getCurrentCallsPhoneEvents command.
The response to this command is formatted as follows:
When opening the websocket, the following message will be received automatically. It will indicate the current phone status (or the webrtc status) of the user and indicate if the user is ready to receive calls. A new event will be received if, for any reason, the phone (or the webrtc line) becomes unavailable.
phoneNumbers (Array of string): list of phone numbers to subscribe
Subscribe to PhoneHintStatusEvents for a list of phone numbers. You will get an initial event with the current
Phone Hint Status (see Phone Hint Status Events for details) for every subscribed phone number and then a new
Phone Hint Status Events for every change to the phone number state. After the Xuc server restart it may happen
that the current phone state is unknown, in which case you will not get the initial event, only the first event update.
You can repeat the command to subscribe to more numbers. The subscription is valid for the current websocket and
can be cancelled either by closing the websocket, or by the Cti.unsubscribeFromAllPhoneHints() command.
You can subscribe to PhoneHintStatusEvents using Cti.subscribeToPhoneHints, allowing you to monitor state of the phone line with a given number.
PhoneHintStatusEvents has the following format:
The phone hint status code can be resolved to a name using the Cti.PhoneStatus object in the cti.js. E.g.,
the status 0 from the example above stands for “AVAILABLE”.
An agent can be logged in using Cti.loginAgent(agentPhoneNumber, agentId). For the moment, the phone number used for
agent login should be the same as the one used for user login, otherwise you will get many error messages
“LoggedInOnAnotherPhone”.
Following cases are handled:
agent is not logged and requests a login to a known line: the agent is logged in
agent is not logged and requests a login to an unknown line: an error is raised:
{"Error":"PhoneNumberUnknown"}
agent is already logged on the requested line: the agent stays logged
agent is already logged on another line: an error is raised and the agent stays logged (on the number where he was
logged before the new request). It’s up to the implementation to handle this case.
agent is not logged and requests a login to a line already used by another agent: the agent takes over the line and
the agent previously logged on the line is unlogged
Creates outgoing call to destination from some free Agent attached to queueId. Caller id on both sides is set
to callerId.
Variables must take the following form:
{var1:"value 1",var2:"value 2"}
USR_var1 and USR_var2 will be attached to the call and propagated to Phone Events
Limitations: Queue No Answer settings does not work - see No Answer. Except: when there is no free Agent to queue (none attached, all Agents on pause or busy), then No answer settings work (but Fail does not).
Note
Line should be configured with enabled “Ring instead of On-Hold Music” enabled (on “Application: tab in queue configuration - see Queues). Otherwise the queue will answers the call and the destination rings even if there are no agents available.
Subscribe to agent statistics notification. When called all current statistics are receive, and a notification is received for each updates. Both initial values and updates are transmitted by the Statistics events.
This message is sent upon connection to the xuc websocket. The profile can be one of: “Supervisor”, “Admin”, “NoRight”.
The rights property contains an array with additional rights:
“recording”: User has access to recording management settings on queues
“dissuasion”: User has access to dissuasion management settings on queues
{"uuid":"b0849ac0-4f4a-4ed0-9386-53ab2afd94b1","name":"Liste de test","queueId":1,"callbacks":[{"uuid":"a967da84-bc41-4bf4-a4fc-2bcc54e11606","listUuid":"b0849ac0-4f4a-4ed0-9386-53ab2afd94b1","phoneNumber":"0230210082","mobilePhoneNumber":"0789654123","firstName":"Alice","lastName":"O'Neill","company":"YourSociety","description":null,"agentId":null,"dueDate":"2016-08-01","preferredPeriod":{"default":false,"name":"Afternoon","periodStart":"14:00:00","periodEnd":"17:00:00","uuid":"d3270038-e20e-498a-af71-3cf69b5cc792"}}]}
This command subscribes to the queue statistics notifications. First, all actual statistics values are sent for
initialisation and then a notification is sent on each update. Both initial values and updates are transmitted
by the QUEUESTATISTICS events.
The handler is executed when a notification of new statistic values is received. Each message contains one or more
counters for one queue. The queue is identified by its queueId. See example below for reference.
The queue’s id can be used to retrieve queue’s configuration, see Queue Configuration.
Awaiting calls in a queue. Subscription to the events with : Cti.subscribeToQueueCalls(9) (9 being the queueId).
Unsubscription with: Cti.unSubscribeToQueueCalls(9).
Set the default membership for the given user id. Warning, the userId is not the same as the agentId.
‘membership’ should be an array of Queue membership like:
Set the default membership for the given array of user id. Warning, the userId is not the same as the agentId.
‘userIds’ should be an array of user id like :
[1,2,3]
‘membership’ should be an array of Queue membership like:
Apply the existing default configuration to a set of users. Warning, the userId is not the same as the agentId.
‘usersIds’ should be an array of userId like:
Mute all attendees except current user in the given conference. This method is restricted to conference organizer so you must enter the conference with an organizer pin.
Un-Mute all attendees in the given conference. This method is restricted to conference organizer so you must enter the conference with an organizer pin.
Mute an attendee by its index in the given conference. This method is restricted to conference organizer so you must enter the conference with an organizer pin.
Un-Mute an attendee by its index in the given conference. This method is restricted to conference organizer so you must enter the conference with an organizer pin.
Make an attendee deaf by its index in the given conference. This method is restricted to conference organizer so you must enter the conference with an organizer pin. After this command, the participant will not hear the conference but other participants can hear him.
Note
When a conference participant is deafened, a button will appear in the UC Assistant to undeafen him. This button is only available for conference organizers.
Make an attendee undeaf by its index in the given conference. This method is restricted to conference organizer so you must enter the conference with an organizer pin. After this command, the participant hear again the conference.
Kick an attendee out of the given conference by its index. This method is restricted to conference organizer so you must enter the conference with an organizer pin.
Close the given conference and hangup all participants. This method is restricted to conference organizer so you must enter the conference with an organizer pin.
Reset the participants state in the given conference to their default state. All muted or deaf participants are not muted or deaf anymore. This method is restricted to conference organizer so you must enter the conference with an organizer pin.
Allows user to send a text message to another user .
If xivo-chat-backend package is installed messages can be persisted (even if user is disconnected).
A sample of implementation is available in app/assets/javascripts/pages/sampleFlashText.js
and app/views/sample/sampleFlashText.scala.html
All chat methods contains sequence number that allows you setting any value to correlate your command with the answer.
Basically if you send 3 chat messages to 3 different users, you will be able to know which acknowledgment is related to which destination just by looking at this number.
{"msgType":"FlashTextEvent","ctiMessage":{"event":"FlashTextUserMessage","from":{"username":"bwillis","phoneNumber":"1001","displayName":"Bruce Willis","guid":"goegjutxyt8c5dmsqy6xk4f85w"},"to":{"username":"jbond","phoneNumber":"1000","displayName":"James Bond","guid":"eiifh5zietbi7k8ao6ndrzr7zo"},"sequence":145,"message":"How are you James ?","date":"2019-05-28T14:55:08.628+02:00",}
FlashTextSendMessageAck
The message sent to the user can be delivered to the user, means the user is connected to the server,
if the connected application is able to receive the message, message will be delivered.
Once logged on the sample page, you can init the webRTC through the init button, follow events shown in the webRTC section
and send and receive calls. You can terminate a call by the terminate button in the phone section. Attended transfer
can be performed using xfer buttons. Hold and DTMF features are available via the webRTC API. You can receive or make
up to 2 calls, answer and hold methods do their best to put other calls on hold when answering or hold the call which
is not held (or resume the one which is held), but currently the SIPml5 session ids are not exposed, so you have to
avoid getting in a situation where it’s not clear from the context what needs to be done, for example putting on hold
two calls in the same time.
If really you want to interact between SIPml5 session and XUC calls, you can use SIP_CALL_ID which is exposed in xc_webrtc and also in PhoneEvent than can be received in XUC websocket. See Phone Events
Current browsers doesn’t allow media sharing without secure connections - https and wss. The xivoxc_nginx docker image
contains the configuration required for loading the sample page over a secure connection using an auto-signed certificate.
This certificate is automatically generated by the installation script. It is meant to be used only for test purposes,
you should replace it by a signed certificate before switching to production. The sample page is available on the
following address: https://MACHINE_IP:8443/sample
Can be called when there’s one call on hold and one active, then it resumes the call on hold and starts a 3-party
conference hosted by the webrtc endpoint. It can be also used to resume a 3-party conference on hold.
Toggle hold on a webrtc call or a conference. A conference can be resumed either by new call of xc_webrtc.hold() or
by a new call of xc_webrtc.conference().
sipCallId is optional, but if you set it, you can explicitly hold a specific call.
At least one call will always be ongoing even if you try to have two established calls at a time.
Note
The library accepts as an optional parameter the SIP_CALL_ID, which are currently reported in
events. See Phone Events
Start an attendedTransfer to the destination. This method designed to work with the AMI based transfer implemented by the XUC
server, so it first puts current calls on hold and then starts a new call in an auto-answer mode.
List of associated events is defined in the xc_webrtc.General, xc_webrtc.Registration, xc_webrtc.Incoming, xc_webrtc.Outgoing.
See the xc_webrtc.js on https://gitlab.com/xivo.solutions/xucserver/blob/master/app/assets/javascripts/xc_webrtc.js.
The error state events contains a description in the reason field. Call establishment event contains caller or callee detail.
Use the sample page to see some examples.
Xuc post JSON formated events on URL eventUrl="http://localhost:8090/xivo/1.0/event/avencall.com/dropbox/"
configured in /usr/share/xuc/application.conf
If an error occurs while using API actions, error will always be raised with proper HTTP return code and will be wrapped in JSON object with following format
Will create and return object containing result of success/failure for each personal contact inserted (HTTP code 201)
{"created":[{"id":"e62ee672-f74a-498c-b138-86ac1b0ae429","lastname":"Wayne"},{"id":"d3a67f8e-3d8a-465a-9633-bde65a41f1bb","lastname":"Hawking"}],"failed":[{"line":3,"errors":["too many fields"]}]}
If an error occurs while using API actions, error will always be raised with proper HTTP return code and will be wrapped in JSON object with following format
If an error occurs while using API actions, error will always be raised with proper HTTP return code and will be wrapped in JSON object with following format
Will register mobile push notification token to wake up mobile application answer (HTTP code 201)
Warning
The following APIs are now deprecated.
You can re-enable them to specific client based on their IP address. To allow a client, add its IP address to the DEPRECATED_API_HOST key in the XiVO CCcustom.env file. You can add multiple address separated by comma (,).
Dial command automatically applies filters to the phone number provided to make it valid for Xivo. Especially, it removes invalid characters and handles properly different notations of international country code.
Some countries don’t follow the international standard and actually keep the leading zero after the country code (e.g. Italy). Because of this, if the zero isn’t surrounded by parenthesis, the filter keeps it [1].
Limitations: Queue No Answer settings does not work - see No Answer. Except: when there is no free Agent to queue (none attached, all Agents on pause or busy), then No answer settings work (but Fail does not).
Note
Line should be configured with enabled “Ring instead of On-Hold Music” enabled (on “Application: tab in queue configuration - see Queues). Otherwise the queue will answers the call and the destination rings even if there are no agents available.
These real time statistics are calculated nearly in real time from the queue_log table
Statistic are reset to 0 at midnight (24h00) can be changed by configuration
Total number of calls abandoned in a queue (not answered)
TotalNumberCallsAbandonnedAfter15
Total number of calls abandoned after 15 seconds
TotalNumberCallsAnswered
Total number of calls answered
TotalNumberCallsAnsweredBefore15
Total number of calls answered before 15 seconds
PercentageAnsweredBefore15
Percentage of calls answered before 15 seconds
over total number of calls entered
PercentageAbandonnedAfter15
Percentage of calls abandoned after 15 seconds
over total number of calls entered
TotalNumberCallsClosed
Total number or calls received when queue is closed
TotalNumberCallsTimeout
Total number or calls diverted on queue timeout
All queue statistics counters (except percentage) are also available for the sliding last hour by adding LastHour to the name
.i.e. TotalNumberCallsAbandonnedLastHour.
For percentage, there is no historical value (LastHour). If you need historical percentage, you should compute it using the historical total numbers.
You can configure xuc to add statistics for thresholds other than 15 seconds. In this case the xuc server will automatically
publish TotalNumberCallsAbandonnedAfterXX, TotalNumberCallsAnsweredBeforeXX, PercentageAnsweredBeforeXX, PercentageAbandonnedAfterXX.
XX will be replace by all the defined thresholds values.
If configured, these additional stats threshold will be automatically available in queue view of CC Manager, see Thresholds.
You need to include in the compose.yml file a link to a specific configuration file by adding in xuc section a specific volume
and an environment variable to specify the alternate config file location
Total number of inbound calls received internal and external
InbAcdCalls
Total number of inbound ACD calls received internal and external
InbCallTime
Total time for inbound calls received internal and external
InbAcdCallTime
Total time for inbound ACD calls received internal and external
InbAcdCallTime
Total time for inbound ACD calls received internal and external
InbAnsCalls
Answered inbound calls received internal and external
InbAnsAcdCalls
Answered inbound ACD calls received internal and external
InbUnansCalls
Unanswered inbound calls received internal and external
InbUnansAcdCalls
Unanswered inbound ACD calls received internal and external
InbPercUnansCalls
Percentage of unanswered inbound calls received internal and external
InbPercUnansAcdCalls
Percentage of unanswered inbound ACD calls received internal and external
InbAverCallTime
Average time for inbound calls received internal and external
InbAverAcdCallTime
Average time for inbound ACD calls received internal and external
OutCalls
Total number of outbound calls received internal and external
OutCallTime
Total time for outbound calls received internal and external
LoginDateTime
Last login date time
LogoutDateTime
Last logout date time
Terms:
inbound ACD calls
all calls received by an agent via ACD.
inbound calls
all calls received by an agent, internal, external or ACD calls.
oubound calls
all calls dialed by an agent, internal or external calls.
Agent statistics are calculated internaly on a daily basis and reset to 0 at midnight (default configuration). see javascript api
If some status are configured in xivo cti server with activate pause to all queue = true, additionnal statistics computing the total
time in not ready with this status are calculated. This statistics name is equal to the presence name configuration in XiVO.
The reporting is composed of four packages: pack-reporting, xivo-full-stats, xivo-reporting-db and xivo-db replication.
These packages will feed the tables of the xivo_stats database:
xivo-db-replication feeds the tables cel and queue_log in real time, and the configuration tables (dialaction, linefeatures, etc…) every 5 minutes
xivo-full-stats feeds in real time the tables call_on_queue, call_data, stat_queue_periodic, stat_agent_periodic and agent_position
xivo-reporting-db and pack-reporting work together to feed the tables stat_queue_specific, stat_agent_queue_specific and stat_agent_specific every 15 minutes
Third party web application integration is possible inside the XucMgt Agent application. Upon each call, you can display a custom panel next to the agent interface:
When a call is ringing on the agent phone, the Application will call the external web service (see Configuration below). The web service response will dictate the behaviour of the integration. For example, if the speficied action is to open the application when the call is hung up, a new panel will be created and opened inside the agent interface, showing the content specified by the web service response. (see Web Service API for available options).
When the work is complete in the integrated application, the application must post a message to terminate the third party application pane inside the agent application (see Completion).
You need to specify the third party application web service url to integrate this application inside the XucMgt Agent interface. This can be done by giving a value to the THIRD_PARTY_URL environment variable
in the /etc/docker/compose/custom.env file
The Web service must answer with an application/json content. For example:
{"action":"open","event":"EventReleased","url":"/thirdparty/open/6bd37819-b4a6-43d3-8fa3-6eb6489bb705","autopause":true,"autopauseReason:"backoffice","title":"Third Party Sample"}
or:
{"action":"none"}
action is one of
open: Will open the given url inside the integration pane
popup: Will open the given url in a popup
run: Will run the given url as an executable, only works in desktop assistant.
none: No action will be performed
event is one of EventRinging, EventEstablished, EventReleased. The third party application will be opened when one the specified event occurs
url should be the url to open inside the application. This url should point to a valid web application that can be specific for each call.
executableArgs can contain an array of argument for the run action.
autopause if set to true, the agent will be put on pause when the application pane is opened and back to ready when the application is completed.
autopauseReason an optional field allowing to set the type of the pause used while setting the agent on pause (see the line above).
multitab if set to true and action is set to popup, then the integration will be opened a in new popup window (or tab) each time instead of reusing the same window (or tab).
title will set the title of the tabs that will be opened.
Warning, when the XucMgt application and the integrated application are on different server, domain, url,… (which should be common case), You may get CORS errors. To workaround this issue, you should implement the OPTIONS request on your web service. This method will be called by the browser before issuing the POST request to ensure the target web server allows calls from the original application. You application must set at least the following headers in order to overcome the CORS errors:
Access-Control-Allow-Origin: * or the domain hosting the XucMgt application
Access-Control-Allow-Methods: POST, OPTIONS (at least)
Once the work is complete inside the third party application, it should post a completion message (closeThirdParty) to the application using the Web Messaging API.
For example, here is how to define a close method in javascript to send the message to the hosting application and bind it to a simple button:
You need to specify the third party application web service url to integrate this application inside the XucMgt Assistant and Agent interfaces.
This can be done by giving a value to the THIRD_PARTY_LOGIN_URL environment variable in the /etc/docker/compose/custom.env file
In the following, all urls are relative to the recording server base url and port. For example a relative URL
/recording/records/search is meant to be replaced by http://192.168.29.101:9400/recording/records/search
assuming the recording server is available on port 9400 at 192.168.29.101
To use the recording server API you need to add an additional header in every HTTP Request. The header name is X-Auth-Token
and its value must be the same as the PLAY_AUTH_TOKEN environment variable defined in the custom.env of the docker-compose environment hosting the recording server container (see Shared token).
This API gives the call history of a given agent number.
Description:
URL:
/recording/history/agent
Method:
POST
Url parameters:
size:
The maximum number of result to return (default: 10)
days:
The number of days to retrieve (default: 7)
Warning
Take care that the greater the number of days you ask to retrieve,
the heavier the request will be to the databvase (depending on the number of calls in the dababase).
Request Body:
A json object with a field named agentNum containing the agent number to search for.
This section describes XiVO Configuration server API. These APIs will replace old legacy apis and will be supported by
the configuration server dockerized component.
These are mainly REST APIs.
In the following, all url are relative to the config-mgt base url and port. For example a relative URL /callback_lists
is meant to be replaced by
To use the config-mgt api you need to add an additional header in the HTTP Request.
The header name is X-Auth-Token and its value must be the same as the PLAY_AUTH_TOKEN environment variable defined in the custom.env of the docker-compose environment hosting the configuration server container (see Shared token).
Following APIs allow the management of the users preferences.
List of preferences :
preferred_device : For unique account users, this property is the value of the default device used by the user with the applications. It can be either phone or webrtc.
The following API allow to define callbacks, a callback, is a shared note for agents in the same queue to know that he must call
his customer before a deadline.
It is used in CC Agent feature existing in Xivo solutions.
A what so called Callback is in fact splitted in four distinct entities:
Callback list: Container object used to define a set of callback requests
Callback request: Core object that contains firstname, lastname, phone number… of the customer to call back
Callback period: The preferred interval of time in which the call should be performed
Callback ticket: Once callback request is taken by an agent, a ticket is created to sum up actions made on the request, like the status of the call and if the request is now closed or not.
[{"uuid":"fea963f5-1920-468c-b52a-93dc88791ba8","name":"Mine","queueId":2,"callbacks":[{"uuid":"edb734e7-9d8f-403d-8cf6-d42ecf9e48d7","listUuid":"fea963f5-1920-468c-b52a-93dc88791ba8","phoneNumber":"0230210092","mobilePhoneNumber":"0689746321","firstName":"John","lastName":"Doe","company":"MyCompany","description":"Call back quickly","preferredPeriodUuid":"31f91ef6-ebda-4e0d-a9fa-5ebd3da30951","dueDate":"2017-09-27","queueId":2,"clotured":false,"preferredPeriod":{"uuid":"31f91ef6-ebda-4e0d-a9fa-5ebd3da30951","name":"Toute la journ\u00e9e","periodStart":"09:00:00","periodEnd":"17:00:00","default":true}}]},{"uuid":"75509ad3-3f81-40be-ad90-2c36d7a2c809","name":"another","queueId":2,"callbacks":[]}]
{"total":1,"list":[{"uuid":"7691e6c8-6ebc-4d8f-a41c-45c049ac0dd4","listUuid":"fea963f5-1920-468c-b52a-93dc88791ba8","phoneNumber":"1000","mobilePhoneNumber":"2000","preferredPeriodUuid":"a6119323-a793-4264-987b-c565ceac342b","dueDate":"2018-07-05","queueId":2,"clotured":false,"preferredPeriod":{"uuid":"a6119323-a793-4264-987b-c565ceac342b","name":"Toute la journ\u00e9e","periodStart":"09:00:00","periodEnd":"17:00:00","default":true}}]}
For the queue named sales with sound files sales_audio_file.wav and sales_audio_file_2
present in dir /var/lib/xivo/sounds/playback/, and the queue switchboard defined in custom.env:
are now returning an additional argument named “state_interface”, which is “the interface (e.g.
SIP/alice) that is used to determine if an agent is in use or not”.
REST API 1.1 for confd is currently evolving. New features and small fixes are regularly being added
over time. We invite the reader to periodically check the changelog
for an update on new features and changes.
The SIP API has been improved. options now accepts any extra parameter. However, due to
certain database limitations, parameters that appear in Supported parameters on SIP endpoints may only
appear once in the list. This limitation will be removed in future versions.
A new API for custom endpoints has been added: /1.1/endpoints/custom
A new API for associating custom endpoints has been added: /1.1/lines/<line_id>/endpoints/custom/<endpoint_id>
A new API for SIP endpoints has been added. Consult the documentation
on http://xivo/api/ for further details.
The /lines_sip API has been deprecated. Please use /lines and /endpoints/sip instead.
Due to certain limitations in the database, only a limited number of
optional parameters can be configured. This limitation will be removed
in future releases. Supported parameters are listed further down.
Certain fields in the /lines API have been modified. List
of fields are further down
All optional fields on a user are now always null (sometimes they were empty strings)
The caller id is no longer automatically updated when the firstname or lastname is modified. You must update the
caller id yourself if you modify the user’s name.
Caller id will be generated if and only if it does not exist when creating a user.
Function keys can be used as shortcuts for dialing a number, or accomplishing other menial tasks, by pushing a button on the phone. A function key’s action is determined by its destination.
Function keys can be added directly on a user, or in a template. Templates are useful for creating a set of common function keys that can be used by the same group of people.
This page only describes the data models used by the REST API. Consult the API documentation for further details on URLs.
A destination determines the number to dial when using a function key. Destinations are composed of a parameter named
type and any additional parameters required by its type.
Available destination types:
agent
An agent
bsfilter
Boss/Secretary filter
conference
Conference room
custom
A custom number to dial
forward
Forward a call towards another number
group
A group
onlinerec
Record a conversation during a call
paging
A paging
park
Park a call
park_position
Pick up a parked call
queue
Call queue
service
A call service
transfer
Transfer a call
user
A User
Here are the parameters required for each destination:
Files may be uploaded as usual through the web interface, or from a console by using HTTP utilities
and the REST API. When uploading through the API, the header Content-Type: text/csv charset=utf-8
must be set and the CSV data must be sent in the body of the request. A file may be uploaded using
curl as follows:
The API version 1.0 is no longer supported and has been removed. In most cases, code that used the old API can be
migrated to version 1.1 without much hassle by updating the URL. For example, in 1.0, the URL to list users was:
/1.0/users/In1.1,itis::/1.1/users
Please note that there are no trailing slashes in URLs for version 1.1.
For further details consult the documentation at http://<youxivo>.api
This section describes the REST API provided by the xivo-provd application.
If you want to interact with the REST API of the xivo-provd daemon that is executing as part of XiVO,
you should be careful on which operation you are doing as to not cause stability problem to other parts
of the XiVO ecosystem. Mostly, this means being careful when editing or deleting devices and configs.
By default, the REST API of xivo-provd is accessible only from localhost on port 8666. No authentication
is required.
The srv.install relation links to the plugin installation service.
Plugins usually provided this service to install/uninstall firmware and language files.
Reload the given plugin. This is mostly useful during plugin development, after changing the code of
the plugin, instead of restarting the xivo-provd application.
This resource represents an operation in progress and is used to follow the progress of an underlying
operation. Said differently, it is a monitor on an operation that can change over time.
This does not cancel the underlying operation; it only deletes the monitor. Every monitor that is
created should be deleted, else they won’t be freed by the process and they will accumulate, taking
memory.
HTTP/1.1200OKContent-Type:application/vnd.proformatique.provd+json{"params":[{"description":"The plugins repository URL","id":"plugin_server","links":[{"href":"/provd/configure/plugin_server","rel":"srv.configure.param"}],"value":"http://provd.xivo.solutions/plugins/1/stable"},{"description":"The proxy for HTTP requests. Format is \"http://[user:password@]host:port\"","id":"http_proxy","links":[{"href":"/provd/configure/http_proxy","rel":"srv.configure.param"}],"value":null},{"description":"The proxy for FTP requests. Format is \"http://[user:password@]host:port\"","id":"ftp_proxy","links":[{"href":"/provd/configure/ftp_proxy","rel":"srv.configure.param"}],"value":null},{"description":"The proxy for HTTPS requests. Format is \"host:port\"","id":"https_proxy","links":[{"href":"/provd/configure/https_proxy","rel":"srv.configure.param"}],"value":null},{"description":"The current locale. Example: fr_FR","id":"locale","links":[{"href":"/provd/configure/locale","rel":"srv.configure.param"}],"value":null},{"description":"Set to 1 if all the devices are behind a NAT.","id":"NAT","links":[{"href":"/provd/configure/NAT","rel":"srv.configure.param"}],"value":0}]}
For other services, see http://xivo/api/. This public instance does not allow you to directly test
the requests (i.e. the “Try it out!” button will not work), but you may use the embedded
version of your XiVO, where this button will work.
How to use the embedded REST API web interface (Swagger UI)
Every XiVO server embeds its own copy of the Swagger UI.
The instance embedded in the XiVO allows you to directly try the requests with the in-page buttons.
For the rest of this article, we will consider that your XiVO is accessible under the hostname
MY_XIVO.
You can get a token via Swagger UI (what else?). Choose the xivo-auth service
in the list of REST API. Under tokens, choose POST/tokens.
In the top-right text box of the page (left to the “Explore” button), fill “token” with the
string username:password where those credentials come from the Web Services Access you
created earlier.
Go back to the POST/tokens section and click on the yellow box to the right of the body
parameter. This will pre-fill the body parameter.
In the body parameter, set:
backend to xivo_service
expiration to the number of seconds for the token to be valid (e.g. 3600 for one hour). After
the expiration time, you will need to re-authenticate to get a new token.
Click “Try it out” at the end of the section
In the response, you should see a token attribute.
For more informations about the backends of xivo-auth, see xivo-auth plugins.
To use the authentication token, choose the service for which you want to try the REST API, then
paste the token in the top-right text box. You do not need to click “Explore” to apply the token
change, the new token will be used automatically at the next request you send.
You can now choose a REST API endpoint and “Try it out”.
# Get the list of userscurl--insecure \
-H'Accept: application/json' \
-H'X-Auth-Token: 17496bfa-4653-9d9d-92aa-17def0fa9826' \
https://xivo:9486/1.1/users# Create a user# When sending data, you need the Content-Type header.curl--insecure \
-XPOST \
-d'{"firstname": "hello-world"} \-H 'Accept:application/json' \-H 'Content-Type:application/json' \-H 'X-Auth-Token:17496bfa-4653-9d9d-92aa-17def0fa9826' \https://xivo:9486/1.1/users
For all REST APIs, the main way to authenticate is to use an access token obtained from
xivo-auth. This token should be given in the X-Auth-Token header in your request. For example:
The tokens delivered by xivo-auth have a list of permissions associated (ACL), that determine
which REST resources are authorized for this token. Each REST resource has an associated required
ACL. When you try to access to a REST resource, this resource requests xivo-auth with your token and
the required ACL to validate the access.
For compatibility reason, xivo-confd may accept requests without an access token. For this, you must
create a webservices user in the web interface (Configuration ‣ Management ‣ Web
Services Access):
if an IP address is specified for the user, no authentication is needed
if you choose not to specify an IP address for the user, you can connect to the REST API with a
HTTP Digest authentication, using the user name and password you provided. For instance, the
following command line allows to retrieve XiVO users through the REST API, using the login
admin and the password passadmin:
JSON is used to encode returned or sent data. Therefore, the following headers are needed:
when the request is supposed to return JSON:
Accept = application/json
when the request’s body contains JSON:
Content-Type = application/json
Note
Optional properties can be added without changing the protocol version in the main list or in the object list itself.
Properties will not be removed, type and name will not be modified.
Format returned is a list of properties. The object should always have the same attributes set, the
default value being the equivalent to NULL in the content-type format.
The XiVO REST server implements POST and PUT methods for item creation and update respectively.
Data is created using the POST method via a root URL and is updated using the PUT method via a root
URL suffixed by /<id. The server expects to receive JSON encoded data. Only one item can be
processed per request. The data format and required data fields are illustrated in the following
example:
Requestdataformat
{"id":"1","prop1":"test"}
When updating, only the id and updated properties are needed, omitted properties are not updated.
Some properties can also be optional when creating an object.
A request to the web services may return an error. An error will always be associated to an
HTTP error code, and eventually to one or more error messages. The following errors are common to all web services:
Error code
Error message
Description
406
empty
Accept header missing or contains an unsupported content type
415
empty
Content-Type header missing or contains an unsupported content type
500
list of errors
An error occured on the server side; the content of the message depends of the type of errors which occured
The 400, 404 and 412 errors depend on the web service you are requesting. They are separately described for each of them.
The error messages are contained in a JSON list, even if there is only one error message:
The preprocess subroutine allows you to enhance XiVO features through the Asterisk dialplan. Features that can be enhanced are :
User
Group
Queue
Meetme
Incoming call
Outgoing call
Intra MDS call
There are three possible categories :
Subroutine for one feature
Subroutine for global forwarding
Subroutine for global incoming call to an object
Subroutines are called at the latest possible moment in the dialplan, so that the maximum of variables have already been set: this way, the variables can be read and modified at will before they are used.
Here is an example of the dialplan execution flow when an external incoming call to a user being
forwarded to another external number (like a forward to a mobile phone):
If you want to add a new subroutine, we propose to edit a new configuration file in the directory /etc/asterisk/extensions_extra.d.
You can also add this file by the web interface.
Subroutines should always end with a Return(). You may replace Return() by a Goto() if
you want to completely bypass the XiVO dialplan, but this is not recommended.
To plug your subroutine into the XiVO dialplan, you must add myexample in the subroutine field
in the web interface, e.g. Services ‣ IPBX ‣ PBX Settings ‣ Users ‣ Edit ‣ tab General ‣ Preprocess subroutine.
There is predefined subroutine for this feature, you can find the name and the activation in the /etc/xivo/asterisk/xivo_globals.conf.
The variables are:
Some of the XiVO variables can be used and modified in subroutines (non exhaustive list):
XIVO_CALLOPTIONS: the value is a list of options to be passed to the Dial application, e.g.
hHtT. This variable is available in agent, user and outgoing call subroutines. Please note
that it may not be set earlier, because it will be overwritten.
XIVO_CALLORIGIN: the value is:
extern for calls coming from a DID
intern for all other calls
This variable is used by xivo-agid when selecting the ringtone for ringing
a user. This variable is available only in user subroutines.
XIVO_DSTNUM: the value is the extension dialed, as received by XiVO (e.g. an internal
extension, a DID, or an outgoing extension including the local prefix). This
variable is available in all subroutines.
XIVO_GROUPNAME: the value is the name of the group being called. This variable is only
available in group subroutines.
XIVO_GROUPOPTIONS: the value is a list of options to be passed to the Queue application, e.g.
hHtT. This variable is only available in group subroutines.
XIVO_INTERFACE: the value is the Technology/Resource pairs that are used as the first
argument of the Dial application.
This variable is only available in the user subroutines.
XIVO_MOBILEPHONENUMBER: the value is the phone number of a user, as set in the web interface.
This variable is only available in user subroutines.
XIVO_QUEUENAME: the value is the name of the queue being called. This variable is only
available in queue subroutines.
XIVO_QUEUEOPTIONS: the value is a list of options to be passed to the Queue application, e.g.
hHtT. This variable is only available in queue subroutines.
XIVO_SRCNUM: the value is the callerid number of the originator of the call: the internal
extension of a user (outgoing callerid is ignored), or the public extension of an external
incoming call. This variable is available in all subroutines.
Accessing the XiVO Configuration server API or the Recording server REST API requires a token. This token is used by the Xuc process but can also be used to access API from custom server processes. This token must remain on the server and should not be leaked as it would allow API access without restrictions.
To define or change it, you can add or update the value of the PLAY_AUTH_TOKEN environment variable defined in the custom.env of all the following docker environment (where applicable):
XiVO:
/etc/docker/xivo/custom.env
MDS:
/etc/docker/mds/custom.env
XiVO CC:
/etc/docker/compose/custom.env
XiVO UC-Addon:
/etc/docker/compose/custom.env
Warning
Remind that the value, if defined, must be the same across all XiVO components.
When the XiVO CC is splitted on separate server, the value must also be defined consistently.
Depending on the authentication mode you will require different kind of informations to access the Unified Communication Framework. To simplify and unify authentication, API access is based on a custom token that can be used one of the following way, depending of the API you access:
X-Auth-Token Header:
Adding a HTTP header with a valid token
Query string parameter:
Adding a token parameter with a valid token in the query string part of the API url.
The following sections explain how to get a valid token or trade an external token to a Unified Communication Framework token.
The top section of each file must be capitalized using the following rule:
capitalization of all words, except for articles, prepositions, conjunctions, and forms of to be.
Correct:
TheVitaminsareinMyFreshCaliforniaRaisins
Incorrect:
TheVitaminsAreInMyFreshCaliforniaRaisins
Use the following punctuation characters:
* with overline, for “file title”
=, for sections
-, for subsections
^, for subsubsections
Punctuation characters should be exactly as long as the section text.
Correct:
Section1========
Incorrect:
Section2==========
There should be 2 empty lines between sections, except when an empty section is followed by another
section.
It’s relatively straightforward to recompile the asterisk version of your XiVO with the
DEBUG_THREADS and DONT_OPTIMIZE flag, which make debugging an asterisk problem easier.
It is sometimes useful to produce a “vanilla” version of Asterisk, i.e. a version of Asterisk that
has none of the XiVO patches applied, to make sure that the problem is present in the original
upstream code. This is also sometimes necessary before opening a ticket on the Asterisk issue
tracker.
The procedure is similar to the one described above. Before calling dpkg-buildpackage, you just need to:
Make sure quilt is installed:
apt-getinstall-yquilt
Unapply all the currently applied patches:
quiltpop-a
Remove all the lines in the debian/patches/series file:
truncate-s0debian/patches/series
When installing a vanilla version of Asterisk on a XiVO 16.08 or earlier, you’ll need to stop monit,
otherwise it will restart asterisk every few minutes.
Edit /etc/asterisk/modules.conf so that asterisk doesn’t load unnecessary modules.
This step is optional. It makes asterisk start (noticeably) faster and often makes the
output of valgrind easier to analyze, since there’s less noise.
Edit /etc/asterisk/asterisk.conf and comment the highpriority option. This step
is optional.
Stop monit and asterisk:
monitquitserviceasteriskstop
Stop all unneeded XiVO services. For example, it can be useful to stop xivo-ctid, so that
it won’t interact with asterisk via the AMI.
Copy the valgrind.supp file into /tmp. The valgrind.supp file is located in the contrib
directory of the asterisk source code.
Note that when you terminate asterisk with Control-C, asterisk does not unload the modules before
exiting. What this means is that you might have lots of “possibly lost” memory errors due to that.
If you already know which modules is responsible for the memory leak/bug, you should explicitly
unload it before terminating asterisk.
Running asterisk under valgrind takes a lots of extra memory, so make sure you have enough RAM.
If you want your XiVO to speak in your language that is not supported by XiVO, and you don’t want to
record the whole package of sounds in a studio, you may generate them yourself with some
text-to-speech services.
The following procedure will generate prompts for pt_BR (portuguese from Brazil) based on the
Google TTS service.
Note
There are two sets of prompts: the Asterisk prompts and the XiVO prompts. This procedure
only covers the XiVO prompts, but it may be adapted for Asterisk prompts.
Create an account on Transifex and join the team of translation of XiVO.
Translate the prompts in the xivo-prompts resource.
Note that this last modification may be erased after running xivo-upgrade.
And that’s it, you can configure a user to use your new language and he will hear the prompts in
your language. You may also want to use the xivo-confd HTTP API to mass-update
your users.
Our current goal is to use only two means of communication between XiVO processes:
a REST API over HTTP for synchronous commands
a software bus (RabbitMQ) for asynchronous events
Each component should have its own REST API and its own events and can communicate with every other
component from across a network only via those means.
The current xivo-dao Git repository contains the basis of the future services Python API. The
API is split between different resources available in XiVO, such as users, groups, schedules… For
each resource, there are different modules :
service: the public module, providing possible actions. It contains only business logic and no
technical logic. There must be no file name, no SQL queries and no URLs in this module.
dao: the private Data Access Object. It knows where to get data and how to update it, such as SQL queries,
file names, URLs, but has no business logic.
model: the public class used to represent the resource. It must be self-contained and have almost no
methods, except for computed fields based on other fields in the same object.
notifier: private, it knows to whom and in which format events must be sent.
validator: private, it checks input parameters from the service module.
Avoid using parenthesis around if statements, unless the statement expands
on multiple lines or you need to nest your conditions.
Bad Examples:
if(x==3):print"condition is true"if(x==3andy==4):print"condition is true"
Good Examples:
ifx==3:print"condition is true"ifx==3andy==4:print"condition is true"if(extremely_long_variable==3andanother_long_variable==4andyet_another_variable==5):print"condition is true"if(2+3+4)-(1+1+1)==6:print"condition is true"
Consider refactoring your statement into a function if it becomes too long,
or the meaning isn’t clear.
Avoid throwing Exception. Use one of Python’s built-in Exceptions, or create
your own custom Exception. A list of exceptions is available on the Python documentation website.
Bad Example:
defget_user(userid):user=session.query(User).get(userid)ifnotuser:raiseException("User not found")
Good Example:
classUserNotFoundError(LookupError):def__init__(self,userid):message="user with id %s not found"%useridLookupError.__init__(self,message)defget_user(userid):user=session.query(User).get(userid)ifnotuser:raiseUserNotFoundError(userid)
Never use except: without specifying any exception type. The reason is that it will also catch important exceptions, such as KeyboardInterrupt and OutOfMemory exceptions, making your program unstoppable or continuously failing, instead of stopping when wanted.
Bad Example:
try:get_user(user_id)except:logger.exception("There was an error")
Both the ctispy, ctisave and ctistat tools work in a similar way. They both are
proxies that need to be inserted between the CTI client and the CTI server
message flow.
To do this, you first start the given tool on your development machine, giving
it the CTI server hostname as the first argument. You then configure your CTI
client to connect to the tool on port 50030 (notice the trailing 0). The tool
should then accept the connection from the client, and once this is done, will
make a connection to the server, thereby being able to process all the
information sent between the client and the server.
In the following examples, we suppose that the CTI server is located on the host
named xivo-new.
ctispy can be used to see the message flow between the client and the server in
“real-time”.
The simplest invocation is:
$ cti-proxy/ctispy xivo-new
You can pretty-print the messages if you want by using the --pretty-print
option:
$ cti-proxy/ctispy xivo-new --pretty-print
By default, each message is displayed separately even though more than one
message can be in a single TCP packet. You can also use the --raw option if you
want to see the raw traffic between the client and the server:
$ cti-proxy/ctispy xivo-new --raw
Note that when using the --raw option, some other option doesn’t work because
the messages are not decoded/analyzed.
If you want to remove some fields from the messages, you can use the --strip
option:
Finally, you can ignore all the messages from the client or the server by using
the --no-client or --no-server option respectively.
By default, ctispy will exit after the connection with the client is closed. You
can bypass this behavior with the --loop option, that will make the CTI proxy
continue, whether the client is connected or not.
The versions below indicate the xivo version followed by the protocol version.
Warning
The CTI server protocol is subject to change without any prior warning. If you are
using this protocol in your own tools please be sure to check that the protocol did not change
before upgrading XiVO
Once the network is connected at the socket level, the login process requires
three steps. If one of these steps is omitted, the connection is reset by the
cti server.
login_id, the username is sent as a login to the cti server, cti server answers by giving a sessionid
login_pass, the password is sent to the cti server, cti server answers by giving a capaid
login_capas, the capaid is returned to the server with the user’s
availability, cti server answers with a list of info relevant to the user
First message, describes all the capabilities of the client, configured at the server level
presence : actual presence of the user
userid : the user id, can be used as a reference
capas
userstatusa list of available statuses
status name
color
selectionnable status from this status
default action to be done when this status is selected
long name
services : list of availble services
phonestatus : list of available phonestatuses with default colors and descriptive names
capaxlets : List of xlets configured for this profile
appliname
{"class":"login_capas""presence":"available","userid":"3","ipbxid":"xivo","timenow":1361440830.99,"replyid":3,"capas":{"preferences":false,"userstatus":{"available":{"color":"#08FD20","allowed":["available","away","outtolunch","donotdisturb","berightback"],"actions":{"enablednd":"false"},"longname":"Disponible"},"berightback":{"color":"#FFB545","allowed":["available","away","outtolunch","donotdisturb","berightback"],"actions":{"enablednd":"false"},"longname":"Bient\u00f4t de retour"},"disconnected":{"color":"#202020","actions":{"agentlogoff":""},"longname":"D\u00e9connect\u00e9"},/* a list of other status depends on the cti server configuration */},"services":["fwdrna","fwdbusy","fwdunc","enablednd"],"phonestatus":{"16":{"color":"#F7FF05","longname":"En Attente"},"1":{"color":"#FF032D","longname":"En ligne OU appelle"},"0":{"color":"#0DFF25","longname":"Disponible"},"2":{"color":"#FF0008","longname":"Occup\u00e9"},"-1":{"color":"#000000","longname":"D\u00e9sactiv\u00e9"},"4":{"color":"#FFFFFF","longname":"Indisponible"},"-2":{"color":"#030303","longname":"Inexistant"},"9":{"color":"#FF0526","longname":"(En Ligne OU Appelle) ET Sonne"},"8":{"color":"#1B0AFF","longname":"Sonne"}}},"capaxlets":[["identity","grid"],["search","tab"],["customerinfo","tab","1"],["fax","tab","2"],["dial","grid","2"],["tabber","grid","3"],["history","tab","3"],["remotedirectory","tab","4"],["features","tab","5"],["people","tab","6"],["conference","tab","7"]],"appliname":"Client",}
Second message describes the current user configuration
The STARTTLS command is used to upgrade a connection to use SSL. Once connected,
the server send a starttls offer to the client which can reply with a starttls
message including the status field. The server will then send a starttls message
back to the client with the same status and start the handshake if the status is
true.
Server->Client
{"class":"starttls"}
Client->Server->Client
{"class":"starttls","status":true}
Note
a client which does not reply to the starttls offer will keep it’s
unencrypted connection.
These messages are received whenever one of the following corresponding event occurs: sheet message on incoming calls, or updatestatus when a phone status changes.
The register_agent_status_update command is used to register to the status
updates of a list of agent. Once registered to a agent’s status, the client will
receive all Agent status update events for the registered agents.
This command should be sent when an agent is displayed in the people xlet to be
able to update the agent status icon.
The register_endpoint_status_update command is used to register to the status
updates of a list of lines. Once registered to a endpoint’s status, the client will
receive all Endpoint status update events for the registered agents.
This command should be sent when a endpoint is displayed in the people xlet to be
able to update the agent status icon.
The register_user_status_update command is used to register to the status
updates of a list of user. Once registered to a user’s status, the client will
receive all User status update events for the registered users.
This command should be sent when a user is displayed in the people xlet to be
able to update the presence status icon.
data, a dictionary containing the following fields:
user_uuid, a string containing the UUID of the user.
user_id, an integer containing the ID of the user.
xivo_uuid: a string containing the UUID of the XiVO that sent the status update
status: a string containing the new status of the user based on the cti profile configuration
Note
When multiple XiVO share user statuses, the cti profile configuration for presences and phone statuses
should match on all XiVO to be displayed properly
In the git repository https://gitlab.com/xivo.solutions/xivo-ctid
cti_config handles the configuration coming from the WEBI
interfaces/interface_ami, together with asterisk_ami_definitions, amiinterpret and xivo_ami handle the AMI connections (asterisk)
interfaces/interface_info handles the CLI-like connections
interfaces/interface_webi handles the requests and signals coming from the WEBI
interfaces/interface_cti handles the clients’ connections, with the help of client_connection, and it often involves cti_command too
innerdata is meant to be the place where all statuses are computed and stored
The main loop uses select() syscall to dispatch the tasks according to miscellaneous incoming requests.
Requirements for innerdata:
the properties fetched from the WEBI configuration shall be stored in the relevant xod_config structure
the properties fetched from elsewhere shall be stored in the relevant xod_status structure
at least two kinds of objects are not “predefined” (as are the phones or the queues, for instance)
the channels (in the asterisk SIP/345-0x12345678 meaning)
the group and queue members shall be handled in a special way each
The purpose of the ‘relations’ field, in the various structures is to keep track of relations
and cross-relations between different objects (a phone logged in as an agent, itself in a queue,
itself called by some channels belonging to phones …).
Messages sent from the CTI clients to the server are received by the CTIServer class.
The CTIServer then calls interface_cti.CTI class manage_connection method.
The interface_cti uses his _cti_command_handler member to parse and run the command.
The CTICommandHandler get a list of classes that handle this message from the CTICommandFactory.
Then the the interface_cti.CTI calls run_commands on the handler, which returns a list of all commands replies.
To implement a new message in the protocol you have to create a new class that inherits the CTICommand class.
Your new class should have a static member caller required_fields which is a list of required fields for this class.
Your class should also have a conditions static member which is a list of tupples of conditions to detect that
an incoming message matches this class. The __init__ of your class is responsible for the initialization of
it’s fields and should call super(<ClassName>,self).__init__(msg). Your class should register itself to the CTICommandFactory.
Each CTI commands has a callback list that you can register to from anywhere. Each callback function will be called when
this message is received with the command as parameter.
Refer to MeetmeList.__init__ for a callback registration example and to MeetmeList.invite for the implementation of a callback.
fromxivo_cti.cti.commands.invite_confroomimportInviteConfroomclassMySuperClass(object):def__init__(self):InviteConfroom.register_callback(self.invite_confroom_handler)definvite_confroom_handler(self,invite_confroom_command):# Do your stuff here.ifok:returninvite_confroom_command.get_message('Everything is fine')else:returninvite_confroom_command.get_warning('I don'tknowyou,goaway', True)
Note
The client’s connection is injected in the command instance before calling callbacks functions.
The client’s connection is an interface_cti.CTI instance.
The files are updated with the command dhcpd-update, which is also run when updating the provisioning plugins. This commands fetches configurations files from the provd.xivo.solutions server.
Edit the files in the Git repo xivo-provd-plugins, directory dhcp/
Push your modifications
Go in dhcp/
Run makeupload to push your modifications to provd.xivo.solutions. There is no testing version of these files. Once the files are uploaded, they are available for all XiVO installations.
Most plugin-related files are available in the
xivo-provd-plugins repository.
Following examples are relative to the repository directory tree. Any modifications
should be preceeded by a git pull.
If the production version is 0.4, change the plugin version to 0.4.01, make your
changes and upload to testing (see below).
Next modification will change the plugin version to 0.4.02, etc. When you are
finished making changes, change the version to 0.5 and upload one last time.
Make your changes in provd-plugins, update the plugin version to the new one and upload to testing (see below). Now, every time you uninstall/install the plugin, the new plugin will be fetched from testing, instead of being cached, even without changing the version.
Before updating a plugin, it must be passed through the testing phase.
Once it has been approved it can be uploaded to the production server
Important
Before uploading a plugin in the testing provd repository, make sure to git pull the xivo-provd-plugins git repository.
To upload the modified plugin in the testing repo on provd.xivo.solutions,
you can execute the following command:
$ make upload
Afterwards, in the web-interface, you must modify the URL in section
Configuration ‣ Provisioning ‣ General to:
`http://provd.xivo.solutions/plugins/1/testing/`
You can then update the list of plugins and check the version number for the plugin that you modified.
Don’t forget to install the plugin to test it.
Mass-install all firmwares related to a given plugin
Using xivo-provd-cli on a xivo server, one can mass-install firmwares. Following
example installs all firmwares for xivo-snom 8.7.3.25.5 plugin
(note the auto-completion):
Once checked, you must synchronize the plugin from testing to stable. If applicable, you
should also update the archive repo.
To download the stable and archive plugins:
$ make download-stable
$ make download-archive
Go to the plugins/_build directory and delete the plugins that are going to be updated. Note
that if you are not updating a plugin but you are instead removing it “once and for all”, you
should instead move it to the archive directory:
$ rm -fi stable/xivo-cisco-spa*
Copy the files from the directory testing to stable:
$ cp testing/xivo-cisco-spa* stable
Go back to the plugins directory and upload the files to the stable and archive repo:
$ make upload-stable
$ make upload-archive
The file are now up to date and you can test by putting back the stable
url in the web-interface’s configuration:
Let’s suppose you have received a brand new SIP phone that is not supported by
the provisioning system of XiVO. You would like to know if it’s possible
to add auto-provisioning support for it. That said, you have never
tested the phone before.
This guide will help you get through the different steps that are needed to add
auto-provisioning support for a phone to XiVO.
Adding auto-provisioning support for a phone is mostly a question of finding answers
to the following questions.
Is it worth the time adding auto-provisioning support for the phone ?
Indeed. Adding quality auto-provisioning support for a phone to XiVO requires
a non negligible amount of work, if you don’t meet any real problem
and are comfortable with provisioning in XiVO. Not all phones are born equal.
Some are cheap. Some are old and slow. Some are made to work on proprietary
system and will only work in degraded mode on anything else.
That said, if you are uncertain, testing will help you clarifying your idea.
What is the vendor, model, MAC address and firmware version (if available) of
your phone ?
Having the vendor and model name is essential when looking for documentation
or other information. The MAC address will be needed later on for some tests,
and it’s always good to know the firmware version of the phone if
you are trying to upgrade to a newer firmware version and you’re having some
troubles, and when reading the documentation.
Is the official administrator guide/documentation available publicly on the
vendor web site ? Is it available only after registering and login to the
vendor web site ?
Having access to the administrator guide/documentation of the phone is also
essential. Once you’ve found it, download it and keep the link to the URL. If
you can’t find it, it’s probably not worth going further.
Is the latest firmware of the phone available publicly on the vendor web site ?
Is it available only after registering and login to the vendor web site ?
Good auto-provisioning support means you need to have an easy way to download the
latest firmware of the phone. Ideally, this mean the firmware is downloadable
from an URL, with no authentication whatsoever. In the worst case, you’ll need to
login on some web portal before being able to download the firmware,
which will be cumbersome to automatize and probably fragile. If this is the case, it’s
probably not worth going further.
Does the phone need other files, like language files ? If so, are these files
available publicly on the vendor web site ? After registering ?
Although you might not be able to answer to this question yet because you might not know
if the phone needs such files to be either in English or in French (the two officially
supported language in XiVO), you’ll need to have an easy access to these files if its
the case.
Does the phone supports auto-provisioning via DHCP + HTTP (or TFTP) ?
The provisioning system in XiVO is based on the popular method of using a DHCP
server to tell the phone where to download its configuration files, and a HTTP (or TFTP)
server to serve these configuration files. Some phones support other methods of
provisioning (like TR-069), but that’s of no use here. Also, if your phone is
only configurable via its web interface, although it’s technically possible to
configure it automatically by navigating its web interface, it’s an extremely bad
idea since it’s impossible to guarantee that you’ll still be able to provision the
phone on the next firmware release.
If the phone supports both HTTP and TFTP, pick HTTP, it usually works better with
the provisioning server of XiVO.
What are the default usernames/passwords on the phone to access administrator menus (phone
UI and web UI) ? How do you do a factory reset of the phone ?
Although this step is optional, it might be handy later to have these kind of information.
Try to find them now, and note them somewhere.
What are the DHCP options and their values to send to the phones to tell it where
its configuration files are located ?
Once you know that the phone supports DHCP + HTTP provisioning, the next
question is what do you need to put in the DHCP response to tell the phone where
its configuration files are located. Unless the admin documentation of the phone
is really poor, this should not be too hard to find.
Once you have found this information, the easiest way to send it to the phone
is to create a custom host declaration for the phone in the /etc/dhcp/dhcpd.conf
file, like in this example:
What are the configuration files the phone needs (filename and content)
and what do we need to put in it for the phone to minimally be able to
make and receive calls on XiVO ?
Now that you are able to tell your phone where to look for its configuration files,
you need to write these files with the right content in it. Again, at this
step, you’ll need to look through the documentation or examples to answer this
question.
Note that you only want to have the most basic configuration here, i.e. only
configure 1 line, with the right SIP registrar and proxy, and the associated
username and password.
Do basic telephony services, like transfer, works correctly when using the
phone buttons ?
On most phones, it’s possible to do transfer (both attended and direct), three-way
conferences or put someone on hold directly from the phone. Do some tests to
see if it works correctly.
Also at this step, it’s a good idea to check how the phone handle non-ascii
characters, either in the caller ID or in its configuration files.
Does other “standard” features work correctly on the phone ?
For quality auto-provisioning support, you must find how to configure and make
the following features work:
NTP server
MWI
function keys (speed dial, BLF, directed pickup / call interception)
timezone and DST support
multi language
DTMF
hard keys, like the voicemail hard key on some phone
non-ASCII labels (line name, function key label)
non-ASCII caller ID
backup proxy/registrar
paging
Once you have answered all these questions, you’ll have a good idea on how the
phone works and how to configure it. Next step would be to start the development
of a new provd plugin for your phone for a specific firmware version.
the host machine is used as a router, a NAT and a DHCP server for the phones
the phones are in a separate VLAN than the XiVO, and when they want to interact with it, they must pass
through the NAT
With this setup, we could also put some phones in the same VLAN as the XiVO. We would then have a
mixed environment, where some phones are behind the NAT and some phones aren’t.
Also, it’s easy to go from a non-NAT environment to a NAT environment with this setup. What you usually
have to do is only to switch your phone from the “XiVO” VLAN to the “phones” VLAN, and reconfiguring the
lines on your XiVO.
The instruction in this page are written for Debian jessie and VirtualBox.
1 VLAN network interface for the XiVO. In our example, this will be eth0.341, with IP 10.34.1.254/24.
1 VLAN network interface for the phones. In our example, this will be eth0.342, with IP 10.34.2.254/24.
On the guest machine, i.e. on the XiVO:
1 network adapter attached to the “XiVO” VLAN network interface. In our example, this interface inside
the virtual machine will have the IP 10.34.1.1/24.
Edit the DHCP server configuration file /etc/dhcp/dhcpd.conf. We need to configure the DHCP
server to serve network configuration for the phones (Aastra and Snom in this case):
ddns-update-style none;
default-lease-time 3600;
max-lease-time 86400;
log-facility daemon;
option space Aastra6700;
option Aastra6700.cfg-server-name code 2 = text;
option Aastra6700.contact-rcs code 3 = boolean;
class "Aastra" {
match if substring(option vendor-class-identifier, 0, 6) = "Aastra";
vendor-option-space Aastra6700;
option Aastra6700.cfg-server-name = "http://10.34.1.1:8667/Aastra";
option Aastra6700.contact-rcs false;
}
class "Snom" {
match if substring(option vendor-class-identifier, 0, 4) = "snom";
option tftp-server-name = "http://10.34.1.1:8667";
# the domain-name-servers option must be provided for the Snom 715 to work properly
option domain-name-servers 10.34.1.1;
}
subnet 192.168.32.0 netmask 255.255.255.0 {
}
subnet 10.34.1.0 netmask 255.255.255.0 {
}
subnet 10.34.2.0 netmask 255.255.255.0 {
authoritative;
range 10.34.2.100 10.34.2.199;
option subnet-mask 255.255.255.0;
option broadcast-address 10.34.2.255;
option routers 10.34.2.254;
option ntp-servers 10.34.1.1;
}
If you have many network interfaces on your host machine, you might also want to edit
/etc/default/isc-dhcp-server to only include the “phones” VLAN network interface in the
“INTERFACES” variable.
Start the isc-dhcp-server:
systemctlstartisc-dhcp-server.service
Add an iptables rules to do NAT:
iptables-tnat-APOSTROUTING-oeth0.341-jMASQUERADE
Make sure that IP forwarding is enabled:
sysctl-wnet.ipv4.ip_forward=1
Put all the phones in the “phones” VLAN on your switch
Activate the NAT and Monitoring options on the Services ‣ IPBX ‣ General settings ‣ SIP Protocol page of your XiVO.
Note that the iptables rules and the IP forwarding setting are not persistent. If you don’t make them
persistent (not documented here), don’t forget to reactivate them each time you want to recreate a NAT
environment.
Q. When is this *feature X* will be available?
A. The order in which we implement features is based on our client needs. Write
us an email that clearly explain your setup and what you would like to do and we
will see what we can do. We don't provide any timeline.
If you are using virtualbox and your guest interface is bridged to eth0.341, you’ll need to
change its configuration and bridge it with br0 instead, else it won’t work properly.
where <dev_host_ip> is the IP address of your machine where Eclipse is installed.
Restart spawn-fcgi:
servicespawn-fcgirestart
On your machine where Eclipse is installed:
Make sure you have Eclipse PDT installed
Create a PHP project named xivo-web-interface:
Choose “Create project at existing location”, using the xivo-web-interface directory
In the Window / Preferences / PHP menu:
Add a new PHP server with the following information:
Name: anything you want
Base URL: https://<xivo_ip>
Path Mapping:
Path on Server: /usr/share/xivo-web-interface
Path in Workspace: /xivo-web-interface/src
Create a new PHPWebApplication debug configuration:
Choose the PHP server you created in last step
Pick some file, which can be anything if you don’t “break at first line”
Uncheck “Auto Generate”, and set the path you want your browser to open when you’ll
launch this debug configuration.
Then, to start a debugging session, set some breakpoints in the code and launch your debug configuration.
This will open the page in your browser, and when the code will hit your breakpoints, you’ll be able to go
through the code step by step, etc.
Please note that these resources are provided on an “as is basis”. They have
not been reviewed by the XiVO team, therefore the information presented may be
innaccurate. We also accept resources provided in other languages besides
English.
This section lists experimental features.
When listed here, it means that they are not complete
and not for production. No support will be provided for these
features.
Currently there is no integration at all between XiVO users and Mattermost, if you want to use Mattermost as a chat solution, it is recommended to create your own team and create different users in Mattermost.
The XiVO Centralized User Management allows to manage several XiVO servers through a unique web interface.
Thanks to this interface, it becomes possible to quickly add users that are automatically routed across servers.
This documentation will describe the installation process of the interface, how to use the web interface and the REST API it exposes.
The XiVO Centralized User Management (XCU) is intended for multi-Xivo systems with centralized routing and user management.
Warning
Using XCU for other use-cases than the one described bellow is neither supported nor recommended.
If XCU routing schema or centralized user management does not fit your use case, XCU is not good solution for your
telephony system. Using XCU for user management only is not recommended.
Non-standard installations may be broken by update to future version without warning.
Routing supports heterogeneous numbering plan administration:
Centralized dialplan management.
Route incoming and outgoing calls, independently of the entry point to the target telephony subsystem hosting this number.
Simple configuration of dialplan richness (prefix, short numbers, numbers of different length, emergency calls, live destination modification).
Easily configurable protection against routing loops.
Routing is using concept of two layers:
“Logical” layer - based on contexts, users are routed using centralized database returning the context to be used
to reach the user, with extensions correctly routed irrespective to point of entry of call.
“Physical” layer - arbitrary connection (direct or indirect) via trunks is supported. Trunks are associated
to contexts to reflect the real network topology, there’s no need of full-mesh topology, a call can pass by
multiple Xivos before reaching the user.
Mapping between “Logical” and “Physical” layer is done by routing contexts. Every Xivo has routing context for every
other Xivo (attached to trunk it will use). Routing context with the same name on different Xivo will be configured
accordingly to the position of the Xivo in the network. Intervals can overlap between Xivos, therefore logical
structure of dialplan can be independent on physical location of users.
When there is dial request on some Xivo and destination number is not found locally, AGI script in the dialplan requests
a route from the routing database and gets:
A context used to process the call.
Rules to update the destination number.
Requests can be chained.
Note
Routing systems provides also the conversion of the direct incoming number to the user’s short number,
this conversion is done when the call enters the system, between Xivos only the short number is used.
This condition needs to be respected when creating a new system or integrating an existing one. When integrating
an existing one, you may need to create some routes manually.
Fault tolerance:
Local calls work, even when other network links and/or centralized user database are unreachable.
Routing server can be setup in High Availability master-slave mode. When master routing server is down, routing
requests are automatically processed by the slave.
User management allows centralized administration without knowledge of low-level telephony details:
Configuration is done from point of view of organization administrator, not telephony technician.
User creation is simplified by line templates.
Only relevant choices and options are presented.
Extension number for new user is checked to be unique among all Xivos.
Numbers proposed when creating a user are based on their availability.
XCU accounts can be restricted to manage only part of the system.
All configuration changes are logged for auditability.
Compatibility with configuration via Xivo WebUI:
Users added by Xivo WebUI before adding Xivo to XCU are imported, but they not reachable by centralized routing.
Combining user management by XCU and by Xivo WebUI is bad idea, which usually leads to misconfiguration.
Managing users by XCU and call-center configuration (Queues, Agents) via Xivo WebUI is possible, but queue numbers
are not reachable by centralized routing automatically, you need to add manual routes if needed.
Configuring conference rooms via Xivo WebUI is possible, but conference room numbers are not reachable by centralized
routing automatically, you need to add manual routes if needed.
Both freshly installed XiVO or an already configured XiVO can be added to the user management system.
Steps to be followed are:
When adding a freshly installed XiVO, you need to pass the XiVO Wizard and then follow steps described in
Create XiVO.
When adding an already configured XiVO (a XiVO used since a while with users etc.), you follow the same procedure as
for a freshly installed XiVO, but you must pay attention to following restrictions:
Existing users will be imported in the centralized management, but currently the system doesn’t create any route
and these users are not reachable automatically, you need to add manually required routes.
Existing internal contexts are converted to Entities and created in the management system.
Ensure to have considered the interval overlapping option described in the Configuration.
Please double-check these requirements to prevent unexpected behavior.
For each Xivo which will be added to XCU ensure:
Create an Incoming calls interval in the from-exten context with a did length equal to the internal number length for each interval managed by XCU.
SCCP devices are not supported an may trigger error in the Centralized User Management. You must remove them on your XiVO before using this application.
On any context, Users interval Number range start and Number range end from must be 1-6 six digits (no other characters are allowed).
If you are making circular inclusions of asterisk context the XCU can potentially load users for a while, you should be very careful with such deployment.
Create the xivo sources list file /etc/apt/sources.list.d/xivo-dist.list and add the following line
(replace VERSION with the current version, e.g. 2017.11):
A parameter called allowIntervalOverlap with default value false is available in
/etc/docker/interface-centralisee/application.conf. When set to false, the XCU does not allow use overlapping
intervals, when an interval is created or edited the XCU checks whether the interval overlaps with other intervals
on all XiVOs and if it does the action is rejected. This default setting helps you to preserve a coherent numbering plan.
If for some reason you need to allow interval overlapping, you just need to change the value in the configuration file
to true and restart the XCU. It can be useful when some existing XiVO servers with overlapping intervals were
imported or when you want to be able to migrate some user to another XiVO without changing its number.
General application log is in /var/log/interface-centralisee/application.log with daily rotation, historic logs
retained for 5 days.
User actions are logged to /var/log/interface-centralisee/user_actions.log with daily rotation, historic logs
retained for 366 days.
By default user_actions.log contains only brief information about which authorize XCU user did what action.
To log with more detail (including data of create and update actions), change in
/etc/docker/interface-centralisee/logback.xml line:
When you have checked the sources.list you can upgrade:
Execute with the following commands:
apt-getupdateapt-getinstallgcu-installer
If are using postgresql installed using sources from Postgresql Wiki,
upgrading gcu-installer may trigger installing new version of PostgreSQL (in parallel to curent one).
Suggested action is to disable this new version. If for example GCU use postgresql 9.5 and new version
9.6 was added:
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.
If you installed GCU version older than 2017.06, you can upgrade it by following Installation
instructions. Further instructions and notices:
It is strongly recommended you backup your PostgreSQL icx database and SSH keys before proceeding.
Installation will install new version of configuration files (like /etc/docker/compose/icdu.yml). If some file
already exists with different content, you be prompted to choose correctly version or merge differences.
Unless you are sure you need special version, use choice: install the package maintainer’s version.
Installation will reuse your SSH certificate stored in /etc/docker/interface-centralisee/ssh_key if exists.
Installation will reuse PostgreSQL user icx if exists - make sure it has password icx and access to database icx.
Installation will reuse PostgreSQL database icx if exists.
Check carefully output of apt-getinstallgcu-installer, you will be informed about each component reused and about any
manual checks or actions needed, if necessary.
When you add Xivo with configuration, basic Xivo configuration is done automatically. However there are still
some steps which have to be done manually on each Xivo using Xivo WebUI.
There must be a configuration file /etc/xivo_routage.conf with hosts=IP:9000 where IP is the IP address of XCU
server. If you have a backup routing server, there can be multiple IP:PORT couples separated by comma. Example:
Ensure there is (direct or indirect) trunk connection between every two Xivos -
see Interconnect two XiVO directly. This trunks must have Context set to Incall.
In each Xivo create routing contexts for every other Xivo. In Xivo WebUI go to: Services / IPBX / IPBX configuration
/ Contexts and click Plus icon. For example: if you have three Xivos A, B, C with routing contexts to_xivo_a,
to_xivo_b, to_xivo_c, then in Xivo B you create routing contexts to_xivo_a and to_xivo_c. Type of
routing context must be Outcall and it must not include any sub-contexts.
For each routing context in every Xivo you need to add Outgoing call. In Xivo WebUI go to: Services / IPBX / Call
management / Outgoing calls and click Plus icon. This outgoing call has:
usually the same name as respective routing context
Context set to respective routing context
Trunk set to trunk connecting (directly or indirectly) to target Xivo
in Exten tab single line with Exten = X. and Stripnum = 0
XCU stores some data in a PostgreSQL database. By default, application.conf is configured to connect to a local database named icx with the username icx and password icx. You can change these parameters if you wish. We will use the default parameters in this documentation.
First, we need to install PostgresSQL extensions to use UUID functions :
sudoapt-getinstallpostgresql-contrib
We can now create the user and the database associated :
sudo-upostgrespsql-c"CREATE USER icx WITH PASSWORD 'icx'"
sudo-upostgrespsql-c"CREATE DATABASE icx WITH OWNER icx"
We then have to enable UUID extension on the icx database. Connect as root on the icx database :
sudo-upostgrespsqlicx-c'CREATE EXTENSION IF NOT EXISTS "uuid-ossp";'
It is possible that PostgreSQL complains when you’re trying to connect. The solution is to modify the pg_hba.conf (in Debian, located in /etc/postgresql/X.X/main) and add the following line at the end :
The XiVO Centralized User Management (XCU) is managed through a web interface. In the following sections, we will highlight the main features of the system.
XCU uses a few concepts that are important to understand in order to use the interface correctly.
XiVO
The XiVOs servers that are managed by XCU. XCU will automatically retrieve the entities and the users from them and apply the configuration to them.
Entity
Entities, also called Contexts, are the parts of the dialplan. Users are attached to them.
Line template
Line templates are used to quickly create users : they define a few default options (ringing time, voice mail, etc.) that will be applied to the new user. A line template is required to create a user.
User
Actual users that are associated with a phone number
Administrators
Users that are able to connect to the XCU and manage the XiVOs.
The dashboard provides you some insights about your XiVO systems.
The left sidebar, displayed in every page of the application, gives you access to the various actions you can perform. The list of the configured XiVOs and their entities is shown to give a quick access to the one you want to manage.
The first step is to add the displayed SSH key to the authorized keys of your XiVO server. This will allow XCU
to connect and configure the XiVO server. You could do this kind of command :
Then, you have to provide the following informations :
Name : name of the XiVO server that will be displayed in XCU
Hostname : hostname or IP address of the XiVO server
You then have two options :
Create the XiVO and configure it now : XCU will save the information, try to connect to the XiVO server and
perform the configuration. XiVO services will be unavailable during the operation.
Warning
The configuration takes a while. Relax, go drink a coffee, XCU is doing the legwork for you :)
On the sidebar, each entity has its own link. This page allows you to :
Add a new user to this entity by clicking on the green button
Edit the entity by clicking on the yellow button with the wrench icon
See the users associated to this entity and perform some operations to them :
Edit one by clicking on the yellow button with the wrench icon
Delete one by clicking on the red button with the trash icon. At first click, the icon turns into a question mark. You have 5 seconds to click again to launch user deletion. This process prevents you from accidentally delete users.
This page allows you to add a new line template. You have to provide the following informations :
Name : name that will be be displayed on XCU
XiVO : select the XiVOs for which this template will be available
Entity : select the entities for which this template will be available. Only entities of the selected XiVOs are displayed
SIP peer name : Auto, Model, WebRTC or Unique Account
Ringing time : number of seconds before incoming call is rejected
Routed :
The text field allows you to provide the SDA prefix to call the phone
Uncheck the checkbox if you don’t want the phone to be called from the outside
Outgoing caller id : specify what number is displayed on outgoing call. Possible values are :
External number prefix
Anonymous
Customized : a text field appears to provide the custom number
Voicemail :
Activate voicemail : enable or not the voicemail
Voicemail number : specify what number is used to call the voice mail. Possible values are :
Short line number : use the default short number
Customized : a text field appear to provide the custom number
Voice to mail : whether or not to send an email when a new message is left, the email is the user’s email for
short line number box and the one configured in the customized voicemail for the customized box,
see Create user for details.
This page allows you to add a new user to an entity. You have to provide the following information :
Template : line template to use as a template to create the user. The main options of the template are displayed below
First name
Last name
Internal number : number that will be used to internally call the user. Only the available numbers are displayed
Email : shown in the directory and used when voice to mail feature is activated
Voicemail : Optional, activated only if present in the used template
When a private box is choosen (short line number), the box is created and the user’s email is obligatory when
Voice to mail feature is activated.
When a custom voicemail box is used, the interface will create it if the box doesn’t exist on XiVO, it will be
created with user’s email. Otherwise the existing one is used and the email is not changed.
Currently there’s a limitation due to a XiVO bug - when you update a user with associated custom voicemail, the
voicemail name is replaced with the user’s name.
CTI credentials : provide a login and a password to allow the user to connect through CTI interfaces
When saving the form, a confirmation is displayed on top of the user list with the name and
provisionning number of the user newly created.
{"items":[{"id":559,"entity":{"id":22,"combinedId":"default_analogique@15585b75-1d75-45b1-8678-520d1210ec59","name":"default_analogique","displayName":"default_analogique","xivo":{"id":2,"uuid":"15585b75-1d75-45b1-8678-520d1210ec59","name":"xivo-221","host":"192.168.29.221","remainingSlots":280},"intervals":[{"start":"3990000","end":"3999999"},{"start":"39990000","end":"39999999"}],"presentedNumber":"inbNo"},"firstName":"Sous sol Logistique","lastName":"CLF 88:40 P3","internalNumber":"6260","externalNumber":"\"Sous sol Logistique CLF 88:40 P3\"","mail":null,"ctiLogin":null,"ctiPassword":null,"provisioningNumber":"114133"}]}
{"id":559,"entity":{"id":22,"combinedId":"default_analogique@15585b75-1d75-45b1-8678-520d1210ec59","name":"default_analogique","displayName":"default_analogique","xivo":{"id":2,"uuid":"15585b75-1d75-45b1-8678-520d1210ec59","name":"xivo-221","host":"192.168.29.221","remainingSlots":280},"intervals":[{"start":"3990000","end":"3999999"},{"start":"39990000","end":"39999999"}],"presentedNumber":"inbNo"},"firstName":"Sous sol Logistique","lastName":"CLF 88:40 P3","internalNumber":"6260","externalNumber":null,"mail":null,"ctiLogin":null,"ctiPassword":null,"provisioningNumber":"114133"}
#!/usr/bin/env python3# -*- coding: utf-8 -*-fromurllib.parseimporturlencodefromurllib.requestimportRequest,urlopenimportjson,sysclassXCIApiExample:base_url=Nonecookie=Nonedef__init__(self,base_url,login,password):self.base_url=base_urlself.make_login(login,password)defmake_login(self,login,password):data={"login":login,"password":password}response=self.make_post_request("/login",data)self.cookie=response.info()["Set-Cookie"]defget_entities(self):response=self.make_get_request("/entities")returnself.handle_json_response(response)defget_available_numbers(self,entity):response=self.make_get_request("/entities/"+entity["combinedId"]+"/available_numbers")returnself.handle_json_response(response)defcreate_line_template(self,data):self.make_post_request("/templates",data)defget_line_templates(self):response=self.make_get_request("/templates")returnself.handle_json_response(response)defcreate_user(self,data):self.make_post_request("/users",data)defmake_get_request(self,method):request=Request(self.base_url+method,headers={"Cookie":self.cookie})response=urlopen(request)returnresponsedefmake_post_request(self,method,data):header={"Content-Type":"application/json","Cookie":self.cookieifself.cookieelse""}request=Request(self.base_url+method,json.dumps(data).encode(),header)response=urlopen(request)returnresponsedefhandle_json_response(self,response):returnjson.loads(response.read().decode())# Initialize APIapi_example=XCIApiExample("http://192.168.29.103:9001/api/1.0","admin","superpass")# Get an entity and its XiVOentities=api_example.get_entities()["items"]if(len(entities)==0):sys.exit("There isn't any XiVO configured yet or they don't have any entity !")else:entity=entities[1]xivo=entity["xivo"]print("Selected entity \"%s\" in XiVO \"%s\""%(entity["name"],xivo["name"]))# Create a line templatetemplate_data={"name":"My line template","xivos":[xivo["id"]],"entities":[entity["combinedId"]],"peerSipName":"auto","ringingTime":30,"routedInbound":False,"callerIdMode":"anonymous","voiceMailEnabled":False}api_example.create_line_template(template_data)line_template=api_example.get_line_templates()[0]print("New line template created")# Create a useruser_data={"entityCId":entity["combinedId"],"templateId":line_template["id"],"firstName":"Alice","lastName":"In Wonderland","internalNumber":api_example.get_available_numbers(entity)["items"][0]}api_example.create_user(user_data)print("New user created")
Internal number for a user can be now chosen by typing and narrowing the available numbers result. The number is selected by clicking on it or by pressing tab key.
The possibility to specify the channel (default or Local) for a user in a group or queue was removed.
All users in Groups and Queues are now added with interface Local/id-42@usercallback (for a user with user id 42)
All users that were Groups’ or Queues’ member will have the queue/group member interface changed from SIP/abcd or Local/1000@default to Local/id-42@usercallback during upgrade (for a user with SIP line abcd and number 1000 and user id 42).
Behavior change for XiVO unconditional forward (*21) and do not disturb (*25):
Group member
Before (<=Izar)
After (>= Jabbah)
Channel type
Channel type
is not applicable
default
Local
DND activated
User is called anyway
DND is followed
User is not called
UNC activated
User is called anyway
UNC is followed
User is called anyway
Queue member
Before (<=Izar)
After (>= Jabbah)
Channel type
Channel type
is not applicable
default
Local
DND activated
User is called anyway
User is not called
User is not called
UNC activated
User is called anyway
User is not called
User is called anyway
Directory Research: Lookup results are now ordered in way to prefer more relevant results (see default_json)
*8 is not anymore supported by asterisk core feature but xivo-feature. Pay attention that migration sets it back to *8
Meetingroom
MEETINGROOM_AUTH_DOMAIN should be updated from ‘avencall.com’ to either ‘*’ or ‘meet-jitsi’
LTS Deneb (2019.12): This version is no longer supported.
No bug fixes, no security update will be provided for this release.
Asterisk chan_sip is deprecated. It is still present in Jabbah release but will be removed from next LTS.
See ref:upgrade_chan_sip_pjsip_migration_guide
Asterisk chan_sccp is deprecated. It is still present in Jabbah release but is no longer tested
and will be removed from next LTS.
The xivo-solutions-VERSION no longer exists. The xivocc-installer package is now located in xivo-VERSION distribution.
You have to update your source list accordingly.
Accept new cel.conf: if you are asked by xivo-upgrade installer, you must choose to replace the cel.conf file or ensure
that its content correspond to these defaults.
Finish to remove xivo-ctid-ng and xivo-websocketd:
apt-getpurgexivo-websocketdxivo-ctid-ng
Add writetimeout parameter to the the /etc/asterisk/manager.d/02-xivocc.conf file:
Import new reports as described in SpagoBI post install step
Then, you should also remove old sample reports:
Go to Reports menu and delete all reports which are located under Racine -> Sample
Once all reports are deleted inside these folder you can go to Functionalities Management menu as shown in following
screenshot:
From here, you can delete empty folders by clicking on it
At the end you should have a report folder list, that contains only Rapports and Accueil folder as seen here (unless
you have some specific customer report):
If docker is installed (on XiVO PBX or XiVO CC), its custom start options may cause the upgrade to fail. Please check that /etc/systemd/system/docker.service.d
directory does not exist or it is empty. Otherwise see documentation on docker web.
Configuration files and dialplan subroutine for ACD outgoing calls for call blending
(See Polaris documentation)
was integrated to XiVO.
The configuration must be manually removed if it exists:
Then you MUST edit each object to reconfigure the changed destination.
All Outgoing call redirections can be replaced by an Extension redirection with the appropriate context.
For example an outgoing redirection towards “my_outcall (@to-extern)” to number “0123456789”
can be replaced by an extension redirection to “0123456789” with context “to-extern”
Callbacks: callback API URL was changed. It is now prefixed with configmgt. If you have any AGI calling the callbacks API
(for example api/1.0/callback_lists) you MUST add the prefix configmgt to it : configmgt/api/1.0/callback_lists.
ConfigMgt service was moved to XiVO PBX. Here’s how to migrate the ConfigMgt database:
On your XiVO CC (where the service pgxivocc is run) authorize user root to login with password via ssh,
Then on your XiVO CC, stop the services with xivocc-dcompstop
Then, on your XiVO PBX, run the migration script and follow the instruction:
xivo-migrate-configmgt-db
Finally, when migration is complete, relaunch the services on XiVO CC:
Known Upgrade Limitations: as of Borealis release these are the known limitations for upgrade.
These should be removed during the next bugfix releases of Borealis.
XiVO PBX / UC / CC is not installable or upgradable on XFS partition created withoutftype=1option.
If the partition is XFS, you MUST check if the option is enabled with the xfs_info command.
Upgrade for XiVO CC to Debian 9 is currently not supported.
Debian system will be upgraded to Debian 9 (stretch)
Warning
Please read carefully the Before the upgrade section in the Debian 9 (stretch) upgrade notes.
UC Add-on: during upgrade, UC database (pgxivocc container) will be removed.
Important
Thus all call history (in UC Assistant) will be lost.
The history will be computed again starting from the last call processed before the upgrade.
If you want to recompute all the calls present in the XiVO PBX database you must follow a manual procedure which is not described here.
Before launching upgrade, you MUST verify that replication (of tables cel, queue_log, callback_request and qualification_answers) was completed.
You can use these SQL commands to compare asterisk and xivo_stats databases:
Debian system will be upgraded to Debian 9 (stretch)
Warning
Please read carefully the After the upgrade section in the Debian 9 (stretch) upgrade notes.
Recording: recording for queues was entirely modified
The xivocc-recording package will be automatically installed or upgraded with XiVO if you don’t have xivo-gateway-recording
installed (to record on external server). These two packages are conflicting because they use the same dialplan subroutine names.
If you are using gateway recording and your XiVO is capable to record internally, you should replace the old package by running
apt-getinstallxivocc-recording. Then follow the Recording page. These features are available only with xivocc-recording:
Gateway recording was also removed from documentation and it is not available in XiVO repository.
If you are upgrading from older version than 2017.03.02 with recording installed, you must follow the XiVOCC Recording upgrade procedure.
In the file /etc/asterisk/extensions_extra.d/xivocc-recording.conf the ipbx_name was reset to its default value.
You need to set it back to its previous value.
You MUST edit the queues configuration and (1) remove the subroutine used to start the recording,
(2) and replace them by the correct configuration in the queue (see Recording).
Callbacks: callback API URL was changed. It is now prefixed with configmgt. If you have any AGI calling the callbacks API
(for example api/1.0/callback_lists) you MUST add the prefix configmgt to it : configmgt/api/1.0/callback_lists.
HTTPS certificate: it is required to have subjectAltName defined in the HTTPS certificate.
If you use the default HTTPS certificate, you must regenerate it. See Default Backend Certificate.
APT keyring lookup hashtable troubleshooting: this error can appear at the end of the upgrade before starting xivo services:
Your database MUST be in locale fr_FR.UTF-8 or en_US.UTF-8. Otherwise upgrade won’t be possible.
If your database is not in this locale you must first change it as documented here.
Old configuration parameters (e.g. in files /etc/postgresql/9.4/postgresql.conf or
or /etc/postgresql/9.4/pg_ha.conf) will be saved in during the upgrade in folder
/var/tmp/xivo-migrate-db-94-to-11/postgresql-94-conf-backup/ (see note After Upgrade below).
Postgresql: postgresql service now runs inside a container. During the upgrade the postgresql configuration
WAS NOT migrated (i.e. parameters in file postgresql.conf or connection authorizations in file pg_hba.conf).
But the old configuration was saved during upgrade in folder /var/tmp/xivo-migrate-db-94-to-11/postgresql-94-conf-backup/
postgresql.conf: if you have any specific parameters you should add them to the postgresql container configuration as documented in the
Custom database configuration section.
pg_hba.conf: specific authorization (for XiVO CC …) MUST be added again to new pg_hba.conf file
(now located in /var/lib/postgresql/11/main/pg_hba.conf). Follow the instrcutions below depending on your installation:
(XiVO CC) If you have XiVO CC installed, add this entry for xuc connection:
hostasteriskallXIVOCC_IP_ADDRESS/32md5
(XDS) Add entries for every Media Server:
hostasteriskallMDS_IP_ADDRESS/32md5
(High Availability) On slave XiVO, add entry for replication from master:
hostasteriskpostgresXIVO_MASTER_VOIP_IP/32trust
(XiVO) If you changed the xivo docker network (in factory.env), add this entry:
hostallallXIVO_DOCKER_NETWORK/NETMASKmd5
Apply the settings by command xivo-dcompreload-db. It will not restart db container despite the message “Killing xivo_db_1”.
High availibility: If you have XiVO CC installed, follow the Interconnection with XiVO CC procedure
to install DB Replic on the slave XiVO.
Asterisk HTTP server configuration security warning:
Warning
Security warning: Asterisk HTTP server (used for WebRTC and xivo-outcall) was reconfigured
to accept websocket connections from outside. See the Asterisk HTTP server documentation
and ensure that the configuration is secure.
XDS: if you had an XDS installation you MUST remove SIP trunks added for intra-mds routing
(that is the SIP trunks named default, and mdsX - e.g. mds0, mds1 …).
These trunks are now generated automatically.
You MUST upgrade todocker-cewith the manual procedure below.
Postgres database data will be moved outside the docker volume to the host.
When installing the new xivocc-installer package the XiVOCC services will be stopped.
Totem panels will be lost during upgrade. Please check ELK 7 Upgrade Notes page.
Postgres: database data will be moved from the docker volume to the host in /var/lib/postgresql/data.
This data migration will be almost instantaneous if the volume data is in the same partition.
To check if the volume data is on the same partition as the host destination /var/lib/postgresql/data:
Then check if it in the same partition as /var/lib/postgresql/data dir.
Docker: you MUST upgrade to docker-ce before upgrading xivocc-installer.
Check if you have docker-engine installed:
dpkg-l|grep'^ii'|grepdocker-engine-q&&echo-e"\n\tDocker is installed via docker-engine.\n\tYou MUST upgrade it, BEFORE updating xivocc-installer.\n"
If docker-engine is installed, you must upgrade to docker-cebefore updating xivocc-installer:
Switch the debian sources to the targetted LTS version (it should be located in the file /etc/apt/sources.list.d/xivo-dist.list).
For example, to switch to Deneb LTS version:
if you are upgrading from Aldebaran or lower, this step will trigger the upgrade of xivocc-installer package.
You MUST NOT do it if the XiVO IPBX upgrade is not finished - as stated in Aldebaran to Boréalis Upgrade notes in Manual steps for LTS upgrade.
Totem panels: during upgrade the ELK stack will be upgraded.
Old Elasticsearch/Kibana containers will be removed.
Previous data/dashboard won’t be upgraded to new version. Therefore they are saved in a folder /var/local/elasticsearch-1.7.
Be sure to have enough disk space in this folder partition. You should need at most 1GB of free disk space. The upgrade script checks the real required space and stops if the space is not available.
WebRTC accounts: lines created with webrtc option set to something else than yes will be set to yes.
Previously, whatever the value of the webrtc option, the line was created with the appropriate WebRTC option.
To see which lines were changed, check the migration output in postgresql logs:
Compose file version was upgraded to version 3.7.
See the Compose file version 3 reference.
If you have custom configurations, you should update them before starting the upgrade.
Some of the previously used options, like volumes_from, can’t be used anymore.
To share data between containers, suggested procedure is:
to init the volume with data from the container, remove the container before starting it with the new configuration.
Named volume can be only initialized once. If you want to re-initialize it or update with data from a newer container,
you will have to remove it with dockervolumerm and recreate it
to customize data in the volume, copy them with dockercp to the target container
All media servers must be stopped with xivo-servicestopall before upgrading XiVO.
The rabbitmq exchange “xivo” was changed from “topic” to “x-delayed-message” type.
If any media server is running, the exchange type may not be changed and XiVO will fail to start.
If this happens, the rabbitmq container on XiVO must be stopped, removed and created again.
you MUST be using Kibana in version 7 (the version that was released with Deneb LTS).
If you did not yet upgrade Kibana to version 7 and remained using v3 you MUST upgrade it before upgrading to Electra.
After upgrading Kibana (to version 7) you MUSTbackup Kibana configuration
(once more) before the XiVO CC upgrade. All configuration will be lost (it is stored in elasticsearch container).
After upgrade, you HAVE TO manually install the xivo-chat-backend package.
It must be done on your XiVO CC/UC server (or on UC Addon if you are in this setup).
With UC Addon installed on your XiVO PBX: for the Chat feature to work properly you have to manually install the xivo-chat-backend package. See note above.
Switchboard: to be able to use the new Switchboard application you MUST replace your old switchboard configuration with the new configuration.
The last 7 days of data will be re-replicated to Elasticsearch, see Data flow.
It may take some time if you have a huge amount of calls per week (more than 1 hour if you have 2 million of queue_log per week).
In this section is listed the manual steps to do when migrating from Electra to Freya.
Warning
For Freya Debian was upgraded to Debian 10 (Buster).
Therefore:
the upgrade to Freya will take longer than usual
upgrade from older version than XiVO Boréalis (2018.16) are not supported (you need first to upgrade
to a version above Boréalis before being able to upgrade to Freya).
Reporting: During upgrade all Kibana configuration (including the dashboard) will be lost (it is stored in elasticsearch container).
You MUSTbackup Kibana configuration before the upgrade.
install_device=$(debconf-showgrub-pc|grep'grub-pc/install_devices:'|cut-b3-|cut-f2-d' '|cut-d','-f1)if["$install_device"-a!-e"$install_device"];thenecho-e"\e[1;31mYou must install GRUB BEFORE rebooting\e[0m"fi
Debian system will be upgraded to Debian 10 (Buster)
Warning
Please read carefully the After the upgrade section in the Debian 10 (Buster) upgrade notes.
You must add additional permissions to already existing Webi administrators who should have access to
Users menu and the new User Labels menu. Follow the Webi admin users and User Labels documentation.
XDS:
You must configure the SMTP relay on XiVO Main to be able to have the email notification for voicemail on MDS (see MDS part below).
Database after the upgrade you MUST upgrade pgxivocc from 9.4 to version 11.
To do this, launch the script (it will restart the pgxivocc container).
On XiVO CC:
xivocc-migrate-db-94-to-11
Or on XiVO with UC addon:
xivouc-migrate-db-94-to-11
If you are installing the chat backend, you must upgrade pgxivocc first and then start the chat backend installation.
If the chat backend was already installed before the upgrade, delete channels between surveybot user
and other users. Messages from surveybot are not handled correctly and cause errors in logs.
Get channel ids from the mattermost database:
psql-hlocalhost-p5443-Upostgresmattermost-c"SELECT channelid FROM postsJOIN users ON users.id = posts.useridWHERE users.username = 'surveybot'"
Delete them safely from the mattermost CLI. For example:
Upgrade system to Debian 10 (Buster) with the following manual procedure:
Run upgrade
sed-i's/stretch/buster/'/etc/apt/sources.list/etc/apt/sources.list.d/docker.list
aptupdate
exportDEBIAN_FRONTEND=noninteractive
exportAPT_LISTCHANGES_FRONTEND=none
force_yes="--allow-downgrades --allow-remove-essential --allow-change-held-packages"echo"Executing XiVO CC minimal upgrade actions..."
aptupgrade--yes${force_yes}-oDpkg::Options::="--force-confnew"echo"Executing XiVO CC full upgrade actions..."
aptdist-upgrade--yes${force_yes}-oDpkg::Options::="--force-confnew"
aptautoremove--yes
Check GRUB before rebooting
install_device=$(debconf-showgrub-pc|grep'grub-pc/install_devices:'|cut-b3-|cut-f2-d' '|cut-d','-f1)if["$install_device"-a!-e"$install_device"];thenecho-e"\e[1;31mYou must install GRUB BEFORE rebooting\e[0m"fi
The last 7 days of data will be re-replicated to Elasticsearch, see Data flow.
It may take some time if you have a huge amount of calls per week (more than 1 hour if you have 2 million of queue_log per week).
XDS installation only: you need to update the nginx configuration for WebRTC on MDS if you had already followed the Enable WebRTC on MDS
On your XiVO CC hosting the nginx server, edit the file /etc/docker/nginx/sip_proxy/sip_proxy.conf
(if this file doesn’t exist on your server you can skip this)
Change the location location/ws-MDS_NAME to location/wssip-MDS_NAME (notice change from ws to wssip)
Inside the location,
add the directive auth_request/validatetoken;
and change the proxy_{connect,read,send}_timeout parameters as shown
Below is an example before/after with mds1 as MDS_NAME:
Reporting: During upgrade all Kibana configuration (including the dashboard) will be lost (it is stored in elasticsearch container).
You MUSTbackup Kibana configuration before the upgrade.
The last 7 days of data will be re-replicated to Elasticsearch, see Data flow.
It may take some time if you have a huge amount of calls per week (more than 1 hour if you have 2 million of queue_log per week).
File synchronization: after having initialized the file synchronization on Main (see above), execute the following commands on each MDS to get the public ssh key setup for rsync access from XiVO Main:
Reporting: During upgrade all Kibana configuration (including the dashboard) will be lost (it is stored in elasticsearch container).
You MUSTbackup Kibana configuration before the upgrade.
A new certificate was intalled for XiVO Nginx in /etc/docker/nginx/ssl/. This certificate will be used by the Webi. See HTTPS certificate for more information explanation.
Warning
If you had installed, on the XiVO PBX, a trusted certificate you must replace this new generated certificate by the one you installed previously.
Normally this means that you should copy /usr/share/xivo-certs/server.{crt,key} files into /etc/docker/nginx/ssl/xivoxc.{crt,key} files:
UC-Addon: A new certificate was installed for XiVO Nginx in /etc/docker/nginx/ssl/. This certificate will be used by the XiVO Webi and the UC application.
See HTTPS certificate for more information explanation.
Warning
You most probably had installed a trusted certificate to be able to use UC application. In this case you must replace this new generated certificate by the one you installed previously.
Normally this means that you should copy /usr/share/xivo-certs/server.{crt,key} files into /etc/docker/nginx/ssl/xivoxc.{crt,key} files:
The last 7 days of data will be re-replicated to Elasticsearch, see Data flow.
It may take some time if you have a huge amount of calls per week (more than 1 hour if you have 2 million of queue_log per week).
XDS installation only: you need to update the nginx configuration for WebRTC on MDS if you had already followed the Enable WebRTC on MDS
On your XiVO CC hosting the nginx server, edit the file /etc/docker/nginx/sip_proxy/sip_proxy.conf
(if this file doesn’t exist on your server you can skip this)
For Izar Debian was upgraded to Debian 11 (Bullseye).
Therefore:
the upgrade to Izar will take longer than usual
upgrade from older version than XiVO Freya (2020.18) are not supported (you need first to upgrade
to a version above or equal to Freya before being able to upgrade to Izar).
In short, you must check that the plugins installed on the XiVO are present in the new python3 compatible repo:
http://provd.xivo.solutions/plugins/2/stable
If not you will need some additional checks before upgrading.
All xivo python services were switched to python3, including xivo-provd our provisioning server.
It makes all python2 provisioning plugins incompatible.
During upgrade:
the provd plugin repository will be automatically switched from the python2 compatible repo to the python3 compatible repo
those in addons/stable are migrated to python3 and were tested
those in addons/testing were automatically migrated to python3 but not tested
Therefore, if the plugin installed by your XiVO:
is present in plugins/2/stable: then everything is automatic
is present in plugins/2/addons/stable: then you will need an additional manual step after the migration to configure this repo and update you’re installed plugin from this repo
is present in plugins/2/addons/testing: you should test this plugin on a lab on Izar version before doing the upgrade. If you find some problems, please fix them and open a Merge request on the xivo-provd-plugins-addons repository
Backend certificate re-generation: if you had followed the Install Trusted Certificate for Backend services procedure, then you MUST regenerate
the self-signed certificate used for the backend services:
Check if the backend certificate is self-signed
(opensslx509-in/usr/share/xivo-certs/server.crt-noout-issuer|grep-wqAvencall)&&echo"Certificate is self-signed"||echo"Certificate is not self-signed. You MUST re-generate the backend certificate"
If it is not self-signed, follow the Default Backend Certificate section to regerate a self-signed certificate.
Otherwise, if it is self-signed, you can skip the rest of this procedure.
Then remove the certificate configuration for xivo services:
the sysconfd custom template: /etc/xivo/sysconfd/custom-templates/resolvconf/hosts
the xivo custom template: /etc/xivo/custom-templates/system/etc/hosts
And update the configuration:
xivo-update-config
Also, you must replace the FQDN, in the definition of your directories in the web interface under Configuration ‣ Directories, by localhost.
Then, when done, you must re-save, the CTI Directories definition:
Go to Services ‣ CTI Server ‣ Directories ‣ Definitions
Edit each directory to re-select the new URI
And save it
And restart all the services:
xivo-servicerestartall
Removing xivo-ctid debian package leftovers: some lefovers of the xivo-ctid debian package should be cleaned manually.
You may want to backup these files before cleaning them.
# Clean config dir which is not used anymore
rm-rf/etc/xivo-ctid
# Clean old logs
rm-rf/var/log/xivo-ctid.log*
These steps are to be done after an upgrade from Helios to Izar on XiVO CC, Edge and Meeting Rooms:
Check GRUB before upgrading
install_device=$(debconf-showgrub-pc|grep'grub-pc/install_devices:'|cut-b3-|cut-f2-d' '|cut-d','-f1)if["$install_device"-a!-e"$install_device"];thenecho-e"\e[1;31mYou must install GRUB BEFORE upgrading\e[0m"fi
If it’s broken you can fix it this way before rechecking
#7318 - As i user i dont want the ini file to be taken in count after saving my settings
WebRTC
#7332 - As an admin I want to be able to configure the ICE gathering timeout
Important
Behavior change There is a new env variable for xucmgt ICE_GATHERING_TIMEOUT_MS to change the ICE Gathering timeout (defaults to 2s) (see XiVO CC configuration in Edge configuration)
Behavior change even on edge environment, XiVOCC’s environment variable XUC_HOST MUST be set to the xivocc ip during the installation (you have to manually change it to the fqdn at the end of the installation)
#6329 - As an admin I want to see SIP Call-Id in logs in order to simplify mobile app (and kamailio) debug
Important
Behavior change If you had a custom pre-dial handler when calling a user, you should ensure that it calls Gosub(xivo-user-predial,s,1) to have the default behavior.
Note: if your pre-dial handler called Gosub(xivo_header_mgr,set_headers_on_channel,1) it should be replaced by a call to Gosub(xivo-user-predial,s,1)
#6602 - CCagent do not resize to correct size at startup of desktop assistant
Reporting
#6295 - Duplicates in stat_agent_periodic when recompiling from db_replic
Visioconf
#6495 - When in a meeting room, if I receive another meeting room invitation I can’t quit my current MR to join the new invitation
Web Assistant
#6343 - UC assistant- Remove the star of favorites for users without contact-id
#6652 - History requests are sent multiple times to xuc when a call is ongoing
WebRTC
#6578 - Packet loss warning does not work with Chrome 110 and higher
#6590 - Opus is not activated for WebRTC users for Incoming call JABBAH
Important
Behavior change We now ensure Opus codec is selected for calls towards WebRTC users.
Given A a user
Given W a WebRTC user.
When A calls W, we ensure opus codec will be used on W’s channel (whatever the codec offered by A).
This implies potentially more transcoding load on asterisk.
Previously A’s codec was preferred (presumably G.711 A-Law) and then implying less transcoding by asterisk.
#6614 - Ice negociation timeout not working in scenarios where two calls are presented in quick succession
#6645 - Missing small NaN fix in audio quality for izar and jabbah
XUC Server
#6316 - [Doc] Roaming agent does not work with 2 webrtc lines - Relogging a wertc agent with default line on other webrtc line fails
#6317 - [Doc] Agent on pause is set back to ready status after refreshing page
#6517 - Fix the memory leak when a user is connecting to xuc
XiVO PBX
#6367 - (fix release )Since PJSIP, Asterisk charts in WebI are not rendered properly
#6386 - [Doc] UCAddon - wrong debian version in doc
#6555 - added rights and member management for agi located in /var/lib/asterisk/agi-bin/
#6642 - PJSIP config reload from Asterisk when using the exec & confgend mechanism is slow and delays SIP requests handling
Important
Behavior change PJSIP configuration change: from now on launching manually a modulereloadres_pjsip.so in asterisk CLI will not reload the pjsip configuration from the db.
#6244 - UC assistant - Search results are not all displayed on frontend side
XiVO PBX
#6206 - I can’t click on the + button to add a user to a group
#6222 - Upgrade from Izar to Jabbah breaks MDS replication for extensions table
Important
Behavior change If you come from a version lower than 2022.05.10 this upgrade will take more time to REINDEX the asterisk database.
Examples:
- with 1 000 000 cel and 75 000 queue_log and 50 000 call_log it takes 7 sec (on a high performance disk - Read:400MB/s, Write:500MB/s)
- with 3 600 000 cel and 15 000 000 queue_log and 4 000 000 call_log it takes 22 min (on a low performance disk - Read:80MB/s, Write:80MB/s)
#6240 - Secure xivo-upgrade loging off agents prior to launch real upgrade
#5211 - Translate Recording Server Interface in English
#5244 - [C] - Recording - Cannot download access logs when it is too big
Switchboard
#5389 - Calling using keyboard on switchboard and cc agent does not work - Jabbah
Web Assistant
#5108 - Can’t relogin when we get the new version message on login page
#5172 - History and presence status display as well as avatar
#5660 - When I search for a user without line number, I still see the dialing icon
#5700 - User with just email and no Number still have the chevron displayed near Email Icon
XiVO PBX
#5037 - [Webi - Device] Configuration model changes when we put a device in autoprov mode
#5055 - Outcall route in Webi are not displayed in order of select
#5255 - IVR Can’t access list of IVR scenarios from users edition
#5614 - UA - Make work UA account for call groups, group pickup, and boss secretary filter
Important
Behavior change Cannot switch to “Local” or “default” channel anymore in addition or edition of users in the “groups” tab. DND will now always apply to groups if feature is enabled for the user.
Comments
Redundant comments should be avoided. Instead, effort should be put on making the code clearer.
Bad Example:
Good Example: