Interaction of Tariscope with 3CX v20

This article is intended for users of Tariscope Enterprise or Tariscope Provider licenses, with the restriction function used to manage the 3CX v20.

Starting with Tariscope 4.6.7, a new script has been developed for the Tariscope Observer application, which transmits commands to restrict subscribers or remove these restrictions to a separate TSconnector application. This application is installed on the server with 3CX v20, and it directly sends commands to this PBX. There are separate applications for Windows and Linux, depending on which operating system 3CX runs on. The diagram of the interaction of the Tariscope billing system (call accounting system) with 3CX is shown in Figure 1.

 Figure 1

All settings of the restriction system in Tariscope are performed as before, except for selecting a script and installing the TSconnector application.

Download the appropriate application from the Tariscope website:

for Windows (tsconnector.zip) or Linux (tsconnector.tar.gz), depending on which operating system you have 3CX installed on.

For the TSconnector application to work, you need a configuration file from 3CX: 3CXPhoneSystem.ini

On Windows, this file should be in the folder: C:\ProgramData\3CX\Bin

On Linux, this file should be in the directory: /var/lib/3cxpbx/Bin/

You also need to allow access from other computers to the PostgreSQL server where the 3CX database is installed. Tariscope and TSconnector do not work with the 3CX database, but use their own database.

To do this, you need to make changes to the pg_hba.conf file.

On Windows, this file should be in the folder: C:\ProgramData\3CX\Data\DB

On Linux, this file should be in the directory: var/lib/postgresql/<version>/main/

Add new lines to allow access from other IP addresses.

For example, to allow connections from any IP address:

host all all 0.0.0.0/0 password

To allow from a specific IP address, for example, 192.168.1.100, where Tariscope is installed:

host all all 192.168.1.100/32 password

Installing the application for Windows

Unzip the tsconnector.zip archive to a folder, for example: C:\TSconnector

Copy the 3CXPhoneSystem.ini file to this folder.

TSconnector performs actions to set or remove restrictions, depending on what commands it receives from Tariscope, with a period specified in the config.json file in seconds. By default, this period is 30 seconds. If necessary, open this file and change the period.

Open Command Prompt with administrator rights.

Create a Windows service with the following command:

sc create TSconnector binpath= [шлях до файлу tsconnector.exe]

For example, if you unzipped the archive to the C:\TSconnector folder, this command should look like this:

sc create TSconnector binpath= C:\TSconnector\ tsconnector.exe

Start this service with the following command:

sc start TSconnector

If the service starts successfully, the TS_restrictions.log file will be created in this folder. Check its contents to make sure it does not contain any errors.

Installing the application for Linux

Unzip the tsconnector.tar.gz archive to a directory, for example: /home/softpi/TSconnector (softpi here is the username you logged in to the system with).

Copy the 3CXPhoneSystem.ini file to this directory.

Create a unit file for the Linux service, for example, with the name ts-connector.service

This file should contain the following lines:

[Unit]
Description=Tariscope restrictions

[Service]
Type=notify
ExecStart=/home/softpi/TSconnector/TSconnector

[Install]
WantedBy=multi-user.target

Comments on the file content:
Description can be arbitrary.

ExecStart is a path to the TSconnector file from the archive.

Copy this file to the /etc/system/system directory:

sudo cp /home/softpi/TSconnector/ts-connector.service /etc/system/system

Restart Linux services. Please note that all services will be restarted, including 3CX services. Therefore, choose the appropriate time for this.

sudo systemctl daemon-reload

Check the status of the ts-connector daemon (if you create a unit file for the service with a different name, use that name in the next command):

sudo systemctl status ts-connector

If the service is inactive, start it.

sudo systemctl start ts-connector

If everything is done correctly, the status should be "active". In this case, a service log will be created. The service log of TS_restrictions.log will be in the directory where you unpacked the archive.

Configuring the Tariscope script

In Tariscope, select Data Collection/Observer -> Observer management.

On the Data Collection/Observer page, select the row from the Observer that works with 3CX v20.

On the toolbar, click the Edit icon and select Observer Scripts.

In the Event list, select the required one, for example, Change class of service, which meets the terms of the Tariscope license.

In the Script list, select: setcos-subscriber-3cx-v20.cs 

Click the Edit icon. The Edit window will appear where the script text will be displayed. Find the following lines there and make the appropriate changes:

const string DBHost = "127.0.0.1";   //IP address of PostgreSQL server
const string DBPort = "5432";        //IP port of PostgreSQL server
const string MasterDBUser = "phonesystem";   //Database username
const string MasterDBPassword = "pLvjPg8IKUo";   //Database username password

For the DBhost constant, specify the IP address where 3CX is installed.

For the next 3 script constants, replace the values with those used in the 3CXPhoneSystem.ini file in the CfgServerProfile section.

Save the changes in the script.

After that, if all other settings for the restriction system in Tariscope are made, you can run Observer.

Additional analyze of calls

In some cases, receiving information about calls processed in Tariscope is not enough and additional data analysis is required, which we would like Tariscope to perform automatically. For example, a company's security service would like to promptly know about all calls made by employees from departmental PBX phones to the fire department, police, or ambulance. Another example is when it is desirable to know about all outgoing calls, the cost of which is above a certain amount, or about calls to (from) phones from the "blacklist". You can think of a whole range of other cases when it is necessary to promptly receive notifications about certain calls.

Of course, it would not be the best solution to such tasks to put an employee behind a monitor with Tariscope to monitor such calls. But this is not necessary if you use all the capabilities of Tariscope. Tariscope can be configured so that after each call it will automatically perform additional analysis of the call data for compliance with pre-set conditions, for example, as we mentioned earlier, the execution of a call to some specific phone numbers by any employee of the company.

A special case that requires operational tracking is the detection of telephone fraud. Telephone fraud refers to a certain type of fraud, when unauthorized calls, usually international, are made by various means at the expense of the company. In 2023, according to the international association CFCA (Communications Fraud Control Association), losses from telephone fraud will amount to about 38.95 billion US dollars [1].

Fraud detection is significantly more difficult than, for example, detecting calls to specific phone numbers, since it is not known in advance which numbers are called, when, and for how long. To detect fraud, it is usually recommended to use special systems, which in most cases are based on comparing a specific call with the behavior model of a specific subscriber, group of subscribers, and the company as a whole. Tariscope has such a fraud detection subsystem, but this subsystem is not included in the basic license for Tariscope and must be purchased in addition to the basic license.

At the same time, even without purchasing such a subsystem, Tariscope makes it possible to detect suspicious calls that may be fraudulent. In this article, we will consider how to do this.

First, we will consider only outgoing international calls costing more than a given amount, since fraud is much less common for long-distance and even more so for city calls.

Secondly, of the specified calls in the first condition, the most suspicious calls with signs of fraud should be considered those that are made during non-working hours, on weekends and holidays.

Thirdly, you can evaluate the countries where the call was made. It is believed that the largest number of fraudulent calls are made to countries in the Caribbean, as well as Asia and Africa.

And, finally, you can evaluate calls for fraud from subscribers whose data is not available in the Tariscope database.

Now let's look at how the search for calls with some of the above features can be implemented in the Tariscope system.

In the Tariscope Observer service settings, there is a feature to execute scenarios when certain events occur. To do this, in the Data Collection/Observer menu branch of the Tariscope system, select the Observer Management menu item. The Data Collection/Observer page appears, an example of which is shown in Figure 1.

Figure 1

Select the row of the required Observer, if you have several, and click on the Edit icon on the toolbar. In the menu that appears, select the Observers’ scripts item. As a result, the Observers’ scripts page appears, an example of which is shown in Figure 2.

Figure 2

This window contains a list of events, upon the occurrence of which Tariscope can launch the script associated with this event. Possible reaction to such events:

• Data source connected.
• Data source disconnected.
• Change class of service.
• Group state changed.
• Periodic action.
• New call.
• Database unavailable.

To analyze calls for fraud, select the New call event in the Event list, and select the file containing the fraud analysis script in the Script list. Scripts supplied with Tariscope are installed by default in the C:\ProgramData\Tariscope\ObserverScripts folder.

After selecting the desired scenario, save the settings (Figure 2).

Scripts must be written in C#. Among the scripts supplied with Tariscope is the fraud.cs file. It allows you to send a message either to the email address specified in the script or to the email address specified in the Tariscope settings, about outgoing international calls lasting more than 150 seconds, which are made in the time period: from 19:00 to 08:00 or on weekend. These parameters can be changed, deleted or added by the Tariscope administrator.

To write new scripts or edit existing ones, it is desirable to have an understanding of C# programming, as well as of creating SQL queries

If you are not confident in your abilities, contact SoftPI technical support, as an incorrectly written script can damage the Tariscope system. Script writing by SoftPI is not included in warranty or post-warranty support services and is performed for a separate fee.

The structure of all scripts used in Tariscope is the same. Each script implements the IScript interface.

There are two methods in this interface:

1. Init method. This method is called once during script startup, when the Tariscope Observer service compiles and initializes this script.
2. Main method. It performs operations related to a specific event. The Parameters object is passed to the Main method.
3. When a script is initialized, it is passed the IScriptHost interface, which allows the script to perform some operations. For example, send an email message.

The fraud.cs script listing is below:

using Microsoft.Data.SqlClient;
using SoftPI.Tariscope.WebAdministration.Observer.Scripting.Interfaces;
using SoftPI.Tariscope.WebAdministration.Observer.Scripting.Models;
using System;
using SoftPi.Tariscope.DAL;

public class FraudScanner : IScript
{

    private IScriptHost Host;
    private bool NeedFinish = false;

  //     
                                                                                                                                                //
********************************************************************************************

  //

  private int MAX_CALL_DURATION_S = 150;
  private int CALLTYPE_INTERNATIONAL = 5;
  private TimeSpan BEGINNING_OF_WORK = TimeSpan.Parse("08:00:00");
  private TimeSpan END_OF_WORK = TimeSpan.Parse("19:00:00");
//     
                                                                                                                                                //
*********************************************************************************************

// 
  public void Init(IScriptHost host)
   {
     this.Host = host;
     host.Close += OnClose;
     NeedFinish = false;
   }

  private void OnClose(ref bool Cancel)
  {
    return;
  }

  public void Main(object Parameters)
  {
     NewCallActionParameters actionParameters = (NewCallActionParameters)Parameters;

try
  {
     this.Host.AddEvent("New call processing, ID= " + actionParameters.Id);

     using (SqlConnection cn = new SqlConnection(this.Host.DatabaseConnectionString))
  {

       cn.Open();
       CallItems CallItems = CallItems.Instance(cn);
       SqlCommand cmd = CallItems.GetCommand("SELECT ID, Originator, Dialnumber,
                                                    CallDateTime, CallSeconds, CallType FROM viCalls WHERE ID=@callid>");
cmd.Parameters.AddWithValue("@callid", actionParameters.Id);
       using (SqlDataReader rs = cmd.ExecuteReader())
        {
           if (rs.Read())
           {
              if (rs.GetInt16(5) == CALLTYPE_INTERNATIONAL &&
                  rs.GetInt32(4) > MAX_CALL_DURATION_S &&
                 (((rs.GetDateTime(3).TimeOfDay > END_OF_WORK ||
                    rs.GetDateTime(3).TimeOfDay < BEGINNING_OF_WORK)) ||
                    (rs.GetDateTime(3).DayOfWeek == DayOfWeek.Sunday ||
                    rs.GetDateTime(3).DayOfWeek == DayOfWeek.Saturday)))
             this.Host.SendMail("", "Fraud Detection system", "Suspicious call detected. ID=" + actionParameters.Id + " CallDateTime=" + rs.GetDateTime(3) + " Call duration=" + rs.GetInt32(4));
                       }
                     }
                 }
               }
               catch (Exception ex)
               {
                  this.Host.AddEvent("Error running script: " + ex.ToString());
               }
           }
       }

For someone who is not familiar with programming, the above script code may seem completely incomprehensible. In fact, this is not entirely true. In the code, those lines that can be changed if necessary are highlighted in red.

Consider the first four highlighted lines:

  private int MAX_CALL_DURATION_S = 150;
  private int CALLTYPE_INTERNATIONAL = 5;
  private TimeSpan BEGINNING_OF_WORK = TimeSpan.Parse("08:00:00");
  private TimeSpan END_OF_WORK = TimeSpan.Parse("19:00:00");

These lines declare four variables:

• MAX_CALL_DURATION_S. This is the duration of the call, which is 150 seconds, or 2 minutes and 30 seconds. You can change this value to any positive integer or 0.
• CALLTYPE_INTERNATIONAL. This is the call type for international calls used in Tariscope. Its value is 5. If you are only going to consider international calls, do not change this value. If you are interested in other calls, you can determine their value from the document Tariscope 4.6. Database schema.
• BEGINNING_OF_WORK. This is the start time of the workday, which here is 8 a.m. You can change this value to any other real-world start time.
• END_OF_WORK. This is the end time of the workday, which here is 7 PM. You can change this value to any other real-world end time value.

The next highlighted line:

SELECT ID, Originator, Dialnumber, CallDateTime, CallSeconds, CallType FROM viCalls WHERE ID=@callid>

This is a SQL query to the viCalls view to retrieve from it the current call specified by the condition ID=@callid, where @callid is a parameter that contains the ID of the last call that was processed in the Observer. This SQL query allows you to retrieve the following fields:

• ID. Record ID.
• Originator. The phone number from which the call was made.
• Dialnumber. The phone number to which the call was made.
• CallDateTime. Date and time of the call.
• CallSeconds. Call duration in seconds.
• CallType. Call type.

If necessary, it is possible to obtain other call parameters from the list of viCall view fields.

The following highlighted part of the script analyzes the data for compliance with the specified conditions:

 (rs.GetInt16(5) == CALLTYPE_INTERNATIONAL &&
 rs.GetInt32(4) > MAX_CALL_DURATION_S &&
(((rs.GetDateTime(3).TimeOfDay > END_OF_WORK ||
rs.GetDateTime(3).TimeOfDay < BEGINNING_OF_WORK)) ||
(rs.GetDateTime(3).DayOfWeek == DayOfWeek.Sunday ||
rs.GetDateTime(3).DayOfWeek == DayOfWeek.Saturday)))

This code is used in the if statement as a condition for matching data. It consists of the following conditions:

rs.GetInt16(5) = CALLTYPE_INTERNATIONAL
The value of the 5th field of the query is taken (this is the CallType field in the SQL query). The field count starts from 0. The field value is compared with the value of the CALLTYPE_INTERNATIONAL variable. That is, this condition allows you to detect whether this call is international.

rs.GetInt32(4) > MAX_CALL_DURATION_S
The value of the 4th field of the SQL query (the CallSeconds field) is taken. The value count starts from 0. The field value is compared with the value of the MAX_CALL_DURATION_S variable.

(rs.GetDateTime(3).TimeOfDay > END_OF_WORK ||
rs.GetDateTime(3).TimeOfDay < BEGINNING_OF_WORK))

This condition uses the value of the 3rd query field, the CallDateTime field. It checks whether the call time falls between the end of a business day and the beginning of the next business day.

(rs.GetDateTime(3).DayOfWeek == DayOfWeek.Sunday ||
rs.GetDateTime(3).DayOfWeek == DayOfWeek.Saturday)

This is an alternative call time condition that all international calls longer than 150 seconds that are made on Saturday or Sunday must meet.

Using the logical operators && and ||, you can consider the call's compliance with the required conditions differently.

If the result of the check is true, then the command to send an email notification about this call is executed.

this.Host.SendMail("", "Fraud Detection system", "Suspicious call detected. ID=" + actionParameters.Id + " CallDateTime=" + rs.GetDateTime(3) + " Call duration=" + rs.GetInt32(4));

this.Host.SendMail() – This is a function that sends an email message. This function has three parameters, which are enclosed in parentheses and separated by commas:

• The first parameter specifies the email address to which the message is sent. If this parameter is empty (""), as indicated in the above expression, then the email address specified on the Notification and mailing setting page is used. If you want to send messages to a different address than the one specified on this settings page or you have not configured this parameter in Tariscope, then you should specify this address in quotes, for example, "This email address is being protected from spambots. You need JavaScript enabled to view it.".
• The second parameter is the subject of email. In this scenario, this parameter is "Fraud Detection system". If desired, you can replace this parameter with, for example, "Received a call with signs of fraud" or some other.
• The third parameter is the content of the message text. In this scenario, it is:
  
  "Suspicious call detected. ID=" + actionParameters.Id + " CallDateTime=" + rs.GetDateTime(3) + " Call duration=" + rs.GetInt32(4) .

You can change the text of this line.

The SQL query line discussed above contains a request for two more parameters: Originator and Dialnumber. Accordingly, their values ​​can also be displayed in the body of the email. To do this, add the following line:

“ The call was made from ” & rs.GetInt32(1) “ to telephone number “ & rs.GetInt32(2)

If you modify the SQL query, then in the message it is possible to display information about the subscriber from whose number the call was made, the name of the settlement where the call was made, and other information.

Now let's return to our conditions for detecting calls that can be suspected of being fraudulent. First, let's add an analysis of the call cost. To do this, in the place of the script where the variables discussed above were set, we will add the variable MAX_CALL_COST, for which we will set the value of the call cost, starting from which the call can be considered suspicious. For example, let it be a value of 5.0 USD. That is, the script should react to any call whose cost is more than 5.0 USD.

private decimal MAX_CALL_COST = 5.0;

Now you need to modify the SQL query to get information about the cost of the call. To do this, use the description of the viCalls view in the document of Tariscope 4.x. Database schema to find the required field. This is the Cost field. Then the query should look like this:

SELECT ID, Originator, Dialnumber, CallDateTime, CallSeconds, CallType, Cost FROM viCalls WHERE ID=@callid>

If we are not interested in the duration of the call, then we can exclude the CallSeconds field from the query. And now, having received the data on the call using this SQL query, we should analyze it for compliance with the conditions that interest us: an international call with a cost of more than 10 hryvnias. To do this, the line where the analysis is performed should be written as follows:

(rs.GetInt16(5) = CALLTYPE_INTERNATIONAL &&
rs.GetInt32(4)> MAX_CALL_DURATION_S &&

rs.GetDecimal(6) > 5.0) &&
(((rs.GetDateTime(3).TimeOfDay > END_OF_WORK ||
rs.GetDateTime(3).TimeOfDay < BEGINNING_OF_WORK)) ||
(rs.GetDateTime(3).DayOfWeek == DayOfWeek.Sunday ||
rs.GetDateTime(3).DayOfWeek == DayOfWeek.Saturday))

This line assumes that the CallSeconds field query remains. If it is removed, the value in parentheses in the data analysis line will change, indicating the field number in the query, starting from 0.

Similarly, you can further complicate the conditions for detecting fraudulent calls.

When using scripts for additional call data processing, you should always remember that this use increases the load on the server and can lead to slower processing.

In addition, if call data arrives in Tariscope with a delay, for example, when received via an FTP server, then suspicious call messages will also be generated with a delay.

If the above information is not enough for you to create the necessary script, please contact SoftPI technical support.

Links

1. https://cfca.org/telecommunications-fraud-increased-12-in-2023-equating-to-an-estimated-38-95-billion-lost-to-fraud/

SMDR processing from Mitel MiVoice Business in Tariscope

SMDR data processing from Mitel MiVoice Business in the Tariscope telephone call accounting system is performed for the following SMDR parameter settings in this type of PBX:

We recommend configuring the Mitel MiVoice Business PBX in this way.

Mitel MiVoice Business (3300) uses data transfer from IP port 1752. On the Tariscope side, to receive SMDR data, you should use Tariscope Observer, which uses a TCP client as the data source.

A feature of the Mitel 3300 (MiVoice Business) parser is that the Project Code field for calls using transfer contains the following information: for the first stage of transfer the field contains information about the extension to which the call was transferred, and for the second stage of transfer the field contains information about the extension from which the call was received. An example of this can be seen in the figure below.

This figure shows the stages of a call using a transfer. If you select a row in the view for calls that contains one of the transfer stages and click the Show related records icon on the toolbar, the view will display all stages of that call, as shown in the figure above.

Working with SBC 1000 and SBC 2000 gateways in Tariscope

The ability to collect and process CDR information from the SBC 1000 and SBC 2000 gateways from the Ribbon Communications company has been added to the Tariscope billing system.

These gateways transmit CDR data only to the Radius accounting server. Therefore, a new data source, the Radius accounting server, was added to the Tariscope Observer service. Data packets transmitted to the Radius accounting server are of two types: Start and Stop. Generalized information about the completed call is contained only in Stop packets, therefore only their processing is performed in Tariscope. Both Start and Stop packets are generated in the SBC for each call participant. Only one Stop packet is processed to avoid data duplication in the Tariscope system.

Next, we will present the Tariscope configuration features that are specifically related to the SBC 1000 and SBC 2000 gateways.

First of all, you need to create a suitable telephone system in Tariscope. To do this, select from the menu: Communication nodes → your node → Equipment → Equipment management. The Equipment page appears, an example of which is shown in Figure 1.

Figure 1

Click the Add icon on the toolbar. In the New equipment window that appears, enter any name. We recommend that you enter a name that matches the phone system, for example, SBC 1000. Click Save. The Edit page shown in Figure 2 will appear.

Figure 2

In the Equipment list, select the Ribbon SBC 1000, 2000 item. For these gateways, no further settings for CDR processing are required.

Just add the necessary parameters in the Codes and location section and click Save.

For the correct tariffication of calls, you must perform settings on the pages: Numbering plan and Routes and gateways, as well as add subscribers of this telephone system.

And finally, you need to create a Tariscope Observer service that will receive CDR data from SBC gateways and process this data.

Select Data collection/Observer → Observers management from the menu. The corresponding page will appear, where on the toolbar click Add → New Observer. A corresponding window will appear where you can enter the name of the Observer profile. For example, it could be: SBC 1000. Click Save. A window will appear confirming the creation of a new Observer profile, click on the Settings button. The Tariscope Observer configuration page will be displayed, an example of which is shown in Figure 3.

Figure 3

The Equipment item is "not selected", which means that you must specify the telephone system from the previously created ones for which this Observer is intended. Click on the "here" link and select the desired network and phone system.

In the Data source list, select Radius accounting server. Click on the Data source configuration button to the right of the Data Source list. The Data source configuration window will appear, an example of which is shown in Figure 4.

Figure 4

In the Port textbox, enter the IP port on which the Radius accounting server will work. By default, the port for this server is 1813. If you have multiple phone systems that need to transmit CDR data to Tariscope through the Radius accounting server, use port 1813 for the first Radius accounting server, and other IP ports for the other Radius servers, which free on your system.

In the Shared secret textbox, enter the value of the shared secret. The same value should be in the settings of the telephone system that will transmit CDR data.

Click Done.

This concludes the settings that are specific to the SBC 1000 and 2000 gateways. Perform all other settings in Tariscope according to the recommendations given in the Tariscope 4.6 document. Administrator's Guide.