This connection provides a data collection service for the 3CX communications platform. It provides call data modelling to enable usage of call analytics (Dashboards/Wallboards) on Self-Hosted 3CX installations.

This page outlines how to install the 3CX Remote Collector service on a 3CX PBX

The following requirements must be met in order to deploy ~.Dimensions.~ on a 3CX installation.

• Self-hosted 3CX running 18.0 or later¹ on Linux
• Dedicated Administrator user account on the 3CX system

info

Full 3CX release version support information here.

The ~.Dimensions.~ 3CX collector will run on the 3CX host machine to collect data and pass it to the main ~.Dimensions.~ cloud solution for storage and analytics. The collector uses minimal CPU resource but does have an impact on the memory requirements for the 3CX host.

The table below provides a guide to memory usage of the collector.

note

Memory requirements are affected by the number of devices, users and call rate. Please be prepared to deploy more memory if required.

Please create a 'System Owner' account (with a complex password) for ~.Dimensions.~ on the customer's 3CX instance:

This account is used by the ~.Dimensions.~ Collector software to query configuration and licence information from the 3CX that is needed to model call traffic correctly.

tip

Ensure that 'Enable 2FA' is disabled.

tip

The User Credentials for this account will be needed in Step 2.

In the ~.Dimensions.~ reseller portal, create a new PBX connection, entering in the 3CX Licence Key and the username/ext and password from the previous step

Now that the ~.Dimensions.~ Customer account has been created, the Dimensions collector can be installed on the customer's 3CX instance. Once it has been installed, it will automatically connect back to the ~.Dimensions.~ Customer account using the licence key information and will begin modelling call and user activity.

• SSH into the 3CX instance.

• Ensure you are starting in the users home folder

cd $home

• Download the installer script from the clients website for that region (na, uk, eu or au)

wget -O install.sh https://clients.{region}.myreports.cloud/3cx/install.sh

info

Replace {region} with na (North America), uk (United Kingdom), eu (European Union) or au (Australia/New Zealand), depending on your region.

warning

The -O flag overwrites any existing script in that folder

• Make the script executable

chmod +x ./install.sh

• Run the script providing the version number you want to install e.g.

sudo ./install.sh latest

This should show that the installation path was not found and perform a clean install to /opt/RemoteCollector.ThreeCx/

The collector should now be installed and should start passing call and user information back to the server to enable analytics features.

If you are using a non-standard port on your 3CX system, you will need to update a local 'settings.json' file with the correct details in order for the ~.Dimensions.~ 3CX Collector to connect to the 3CX system successfully.

Modify the following file:

/opt/RemoteCollector.ThreeCx/settings.json

Change the following two parameters:

 "AutoDetectHost": false,
 "ThreeHostPort": {CUSTOMVALUE}

info

The 'settings.json' file is created by the collector after it is installed.

An example of the full 'settings.json' file:

{
  "PersistedSettings": {
    "TenantId": "",
    "LicenseKey": "",
    "InstrumentationConnectionString": "",
    "EnableAutoUpdate": true,
    "AutoUpdateTime": "02:00:00",
    "AutoDetectHost": false,
    "ThreeHostProtocol": "https",
    "ThreeHost": "127.0.0.1",
    "ThreeHostDisableSslValidation": true,
    "ThreeHostPort": 1234
}

Run the script with the new version number and it will automatically upgrade the software:

sudo ./install.sh 1.87.2

The message should show that an installation was found and that it is upgrading

Run the script with remove as the parameter

sudo ./install.sh remove

This will prompt if you want to remove the connector

Press Y to continue, this will remove the service, all files and logs.

Stop the service

systemctl stop RemoteCollector.ThreeCx.service

Start the service

systemctl start RemoteCollector.ThreeCx.service

Get the state of the service

systemctl status RemoteCollector.ThreeCx.service

See service logs

View logs

journalctl -xeu RemoteCollector.ThreeCx.service

Follow logs live:

journalctl -xefu RemoteCollector.ThreeCx.service

By default logs are installed to

/opt/RemoteCollector.ThreeCx/logs

These are zipped into an archive folder on a daily basis.

Logs can be retrieved from the client by using the push logs button in the Edit PBX screen on the reseller portal:

To view the installed version of 3CX when connected via SSH:

apt-cache policy 3cxpbx

This will return the version installed, and the latest version available.