Налаштування Observer-ів в Tariscope

Служба Tariscope Observer (або просто Observer) призначена для автоматичного отримання інформації про виконані виклики (CDR, SMDR, AMA та інші) від АТС або з файлів, що знаходяться в якійсь теці, первинної обробки цих даних, а також для виконання сценаріїв по окремим подіям.

Тобто Observer є ланкою, яка поєднує телефонну систему з системою Tariscope. Один Observer призначений для взаємодії з однією телефонною системою (АТС). Tariscope не має обмежень на кількість Observer-ів, з яких він може отримувати інформацію. Observer може бути налаштований на отримання CDR інформації з різних типів джерел даних, які описуються нижче. Вибір типу джерела даних в першу чергу залежить від типу телефонної системи, з якої отримуються CDR дані.

Observer можуть знаходитися як на тому ж сервері, де знаходиться система Tariscope, так і на віддаленому комп’ютері (сервері), який має зв’язок з сервером Tariscope через IP мережу. Будь-який, локальний чи віддалений Observer повинен мати IP зв’язок з сервером Tariscope (служба TS.MAIN) та Microsoft SQL Server-ом (надалі “SQL сервер”), на якому встановлена база даних Tariscope. При запуску Observer-а він зв’язується з сервером Tariscope, отримує від нього рядок підключення до бази даних, після чого підключається до бази даних Tariscope. Якщо у вас використовуються міжмережевий екран або інші системи безпеки, ви повинні налаштувати їх так, що забезпечити IP доступ Observer-у до серверу Tariscope (IP порт: 8001) та SQL серверу (IP порт: 1433, 1434).

У якості подій, на які може реагувати Observer виконанням конкретного сценарію можуть бути:

• Підключення джерела даних.
• Відключення джерела даних.
• Зміна класу абонента. Ця подія актуальна, якщо ліцензія Tariscope включає функцію обмеження для абонентів.
• Зміна класу груп. Ця подія актуальна, якщо ліцензія Tariscope включає функцію обмеження для груп або груп і абонентів.
• Періодична подія.
• Новий виклик опрацьовано. Сценарій по цій події дозволяє виконати якусь додаткову обробку даних по інформації про отриманий виклик. Наприклад, можна перевіряти, чи не належить набраний номер до якоїсь конкретної групи телефонних номерів.
• Помилка підключення бази даних. Ця подія може бути актуальна, якщо Observer і Microsoft SQL Server знаходяться на різних серверах. При втрачанні зв’язку з базою даних можна надсилати повідомлення адміністратору.

Незалежно від того ви налаштовуєте локальні Observer-и чи віддалені, треба виконати налаштування в додатку Tariscope. Ці налаштування однакові для обох типів Observer-ів. В подальшому буде розглянуте особливості доналаштування віддалених Observer-ів.

В меню Tariscope виберіть: Збір даних/Observer → Керування збором даних. З’явиться сторінка, приклад якої наведений на малюнку 1.

Малюнок 1

Додаємо новий Observer. Клацніть по іконці Додати на панелі інструментів. З’явиться меню, в якому виберіть Новий Observer. З’явиться вікно, яке наведено на малюнку 2.

Малюнок 2

В позиції Назва введіть назву профайлу Observer-а. Рекомендуємо називати профайл ім’ям телефонної системи, з якої цей Observer буде приймати дані. Наприклад, треба отримувати дані з CUCM (Cisco). В цьому разі краще і назвати профайл: CUCM. Назва не повинна містити будь-яких символів, окрім літер і цифр. Клацніть Зберегти. В підтвердження створення профайлу відобразиться вікно (Малюнок 3).

Малюнок 3

Клацніть Налаштування. З’явиться вікно Налаштування Tariscope Observer (назва профайлу), приклад якого показаний на малюнку 4.

 Малюнок 4

Клацніть по посиланню ‘тут’ і виберіть існуючу в системі телефонну систему. Для нашого прикладу це повинно бути саме CUCM.

В переліку Джерело даних виберіть відповідне джерело. Для нашого прикладу якщо CUCM налаштований як FTP клієнт, то в якості джерела даних повинен бути FTP сервер. Для інших типів телефонних систем у якості джерела даних можуть бути: FTP клієнт, TCP клієнт або сервер, локальна або віддалена папка та інші, в залежності від того, яким чином телефонна система віддає CDR дані. Для налаштування параметрів джерела даних клацніть по кнопці, яка знаходиться праворуч від переліку Джерело даних і виконайте налаштування. Опис налаштування конкретного джерела даних дивіться в документації.

Позиція Місце зберігання оброблених CDR призначена для вибору теки для зберігання первинних CDR даних, які отримуються з телефонної системи. Ці дані можуть бути використані при необхідності повної переобробки даних про виклики. За замовчуванням вони зберігаються в теці C:\ProgramData\Tariscope. Журнали CDR мають розширення CDR, а назва файлу включає назву профіля Observer-а та дату.

В переліку Період створення виберіть період для створення журналів з первинними CDR даними. Період створення залежить від активності виконання викликів. Чим вона вище, тим краще вибирати менший період. За замовчування пропонується в якості періоду один місяць.

В переліку Ведення журналу виберіть рівень деталізації журналу роботи профілю Observer-а. Найменш детальний рівень – це Статус, найбільш детальний рівень – Налагодження.

На цьому налагодження локального Observer-а закінчується. Якщо ви виконуєте налагодження віддаленого Observer-а, то увімкніть перемикач Віддалений збір даних.

Клацніть по кнопці Зберегти. Сторінка Збір даних прийме вигляд подібний до того, що показаний на малюнку 5.

Малюнок 5

Якщо ви створили локальний Observer, то його можна запустити, для чого клацніть по іконці Управління і виберіть пункт Запустити.

В тому випадку, коли ви налаштовували профайл для віддаленого Observer-а, виконайте наступні дії.

Робота на віддаленому сервері

Перед виконанням налаштувань на віддаленому сервері ви повинні:

• Виконати налаштування, які вказані вище на сервері Tariscope;
• Якщо на сервері Tariscope працює файревол, додайте правила, які забезпечать доступ до IP портів: 8001 (на ньому працює сервер Tariscope), 1433, 1434 (порти SQL серверу).
• Перевірте, що сервер, де встановлений Tariscope, доступний по мережі з віддаленого серверу, де встановлюється віддалений Observer.

На віддаленому сервері (комп’ютері) виконайте інсталяцію Tariscope.

При виконанні інсталяції на етапі Компоненти Tariscope (малюнок 1.1.5 в статті за наведеному вище посиланню) виберіть Observer сервер. За замовчування інсталяція виконується в теку: C:\Program Files (x86)\SoftPI\Tariscope

Для запуску віддаленого Observer-а ви повинні знати:

• IP адресу сервера, де встановлений сервер Tariscope. Наприклад, IP адреса сервера Tariscope: 10.10.0.148
• а також назву профайлу, який там був створений саме для цього Observer-а. В нашому прикладі це: CUCM

Відкрийте Командний рядок з правами адміністратора Windows. Виконайте там наступні команди:

1. Перехід то теки з програмним забезпеченням. Якщо ви встановлювали в теку за замовчуванням, то це буде команда:

cd C:\Program files (x86)\SoftPI\Tariscope\Microservices

2. Далі запустіть віддалений Observer, в якості параметрів його вкажіть назву профайлу (параметр name) та URL серверу Tariscope (параметр main). Приклад такої програми наведений нижче:

.\Tariscope.Observer.exe /name=CUCM /main=”http://10.10.0.148:8001”

В цьому прикладі назва профайлу CUCM, а URL серверу Tariscope: http://10.10.0.148:8001 , де 10.10.0.148 – це IP адреса серверу, а 8001 – IP порт, на якому працює сервер.

Приклад такого вводу даних показаний на малюнку 6.

Малюнок 6

Якщо всі налаштування виконані правильно і мережа забезпечує доступ від віддаленого Observer-а до серверу Tariscope, то буде виконане підключення Observer-у до Tariscope та SQL Server-у.

Перевірити результат підключення Observer-у можна у його журналі. Журнали роботи Observer-ів, як локальних так і віддалених, ведуться в теці C:\ProgramData\Tariscope\Logs\Observer відповідно на сервері Tariscope або на віддаленому сервері. Журнал має назву [Назва профайлу].log. Для нашого прикладу це буде файл: CUCM.log

Цей журнал створюється тільки після успішного підключення віддаленого Observer-а до серверу Tariscope. Якщо журнал відсутній, це означає, що підключення не відбулося.

Приклад журналу показаний на малюнку 7.

Малюнок 7

Впевнитися в підключенні віддаленого Observer-у до Tariscope можна також в Tariscope на сторінці Observer-ів (малюнок 8). Як видно на малюнку, в стовпці Стан сервісу відображається значення В мережі.

Малюнок 8

Ви повинні залишити відкритим вікно Командний рядок з працюючим віддаленим Observer-ом. Закриття Командного рядку призведе до завершення роботи Observer-а. І для повторного запуску треба буде знову завантажити Командний рядок і повторити вказані вище команди.

Для створення інших віддалених Observer-ів треба повторити всі вказані вище дії: створити в Tariscope профайл, запустити віддалений Observer з відповідною назвою профайлу.

Ви можете запустити віддалені Tariscope Observer-и в якості Windows служб. Для цього можна скористатися, наприклад, сторонньою програмою nssm.

Для створення служби для віддаленого Observer запустіть програму nssm наступною командою:

nssm install TS.Observer,

де TS.Observer – назва служби, яка створюється. Якщо ви створюєте декілька служб, то вони повинні мати різні назви.

Як наслідок виконання команди з’явиться вікно, наведене на малюнку 9.

 Малюнок 9

В позиції Path введіть шлях до файлу Observer-а:

C:\Program files (x86)\SoftPI\Tariscope\Microservices\Tariscope.Observer.exe

В позиції Arguments введіть параметри Observer: назву профайлу і URL серверу Tariscope. Для нашого прикладу це буде:

/name=CUCM /main=http://10.10.0.148:8001

Клацніть Install service. Буде створена відповідна служба Windows, яку треба запустити з Windows вікна Служби (малюнок 10).

Малюнок 10

Імпорт кодів та тарифів в Tariscope

Якщо ви користувач системи Tariscope будь-якої редакції Enterprise або Provider, і вас цікавить вартість викликів, виконаних абонентами ваших телефонних систем, то ви повинні додати у Tariscope дані по тарифам, за якими будуть тарифікуватися виклики.

Якщо ваша АТС має зв’язок з телефонною мережею загального користування (ТМЗК) через одного оператора телефонного зв’язку, то всі виклики з вашої АТС будуть тарифікуватися за тарифами тільки цього оператора. Якщо ж АТС має з’єднання з різними операторами зв’язку, то тарифікація виклику на один і той же телефонний номер буде залежати від того, через якого оператора був виконаний цей виклик. Тому тарифи у Tariscope прив’язані до конкретного оператору зв’язку.

Для користувачів Tariscope Provider, які самі є операторами телефонного зв’язку, також слід мати на увазі, що ви можете мати різні тарифні плани, які призначаються абонентам, тому у абонентів з різними тарифними планами можуть бути різні вартості виклику на один і той же номер з однаковою тривалістю. Для виконання цього вартість конкретного тарифу прив’язується до тарифного плану.

Щоб система Tariscope знала, за яким тарифом розраховувати вартість конкретного виклику, вона виявляє телефонний код в набраному номері і знаходить відповідний цьому коду тариф. Тому тариф повинен бути прив’язаний до конкретного телефонного коду. Звичайно, що один тариф може бути прив’язаний до багатьох телефонних кодів.

Tariscope містить дані за декількома операторами. Тому ви може вибрати якогось з цих операторів або створити нового оператора зв’язку на базі існуючого, щоб в подальшому внести в нього правки в перелік тарифів, їх вартість і прив’язку до конкретних телефонних кодів.

Крім цього ви також можете просто створити нового оператора зв’язку, створити для нього необхідний перелік тарифів і прив’язати ці тарифи до телефонних кодів.

І, нарешті, дані по тарифам і телефонним кодам можна імпортувати із зовнішніх файлів. Саме цей варіант ми розглянимо в цій статті.

Отже для імпорту тарифів і кодів у систему Tariscope ви повинні мати файл одного із наступних форматів:

• Microsoft Excel 2007 (.xlsx).
• Microsoft Excel 2003 (.xls).
• Microsoft Access (.mdb).
• Microsoft Access 2007 (.accdb).
• Розділені комою (.csv).

Зазвичай використовуються файли формату Excel. Тому далі ми розглянемо імпорт саме із цього формату файлу. Але для інших форматів імпорт нічим не відрізняється.

Перелічимо мінімально необхідні поля для імпорту телефонних кодів та тарифів:

• Назва для телефонного коду та тарифу. Зазвичай це назва країни або міста, або оператора мобільного зв’язку.
• Телефонний код або коди. Якщо задається декілька кодів, то вони повинні розділятися комами.
• Вартість тарифу.
• Дата. Дата, починаючи з якої тариф є дійсним. Якщо дата буде відсутня, то при імпорті буде підставлятися поточна дата, встановлена на комп’ютері.

Додатково можуть ще бути вказані і інші поля, які ми згадаємо далі.

Приклад файлу формату Excel для імпорту кодів та тарифів показаний на малюнку 1.

Малюнок 1

В ньому стовпець A містить назву для коду та тарифу, стовпець B - вартість тарифу у доларах, стовпець C – телефонні коди, стовпець D – дату, з якої діє тариф, стовпець E - тип виклику. Тип виклику задається кодом, який використовується в Tariscope:

4 - Міжміські виклики;
5 - Міжнародні виклики;
6 - Мобільні виклики.

За необхідністю перелік усіх типів викликів, які використовуються в Tariscope, дивиться в документі Tariscope 4.6. Каталог бази даних, таблиця 2.16.3.

Перед початком імпорту ви повинні мати тарифний план, до якого буде виконуватися імпорт тарифів.

Давайте створимо нового оператора зв’язку і виконаємо до нього імпорт даних з файлу формату Excel.

Щоб створити нового оператора зв’язку, виберіть у меню Оператори та тарифи -> Керування операторами. З’явиться сторінка Оператори, приклад якої наведений на малюнку 2.

Малюнок 2

Клацніть по іконці Додати на панелі інструментів. З’явиться вікно Новий оператор, де в позиції Назва введіть назву оператора зв’язку. Ми створимо оператора Test 001. При необхідності додати якийсь коментар до цієї назви, введіть її в позиції Опис. Клацніть Зберегти. Новий рядок з’явиться на сторінці Оператори. Після цього перейдіть на сторінку Загальні телефонні коди, приклад якої наведений на малюнку 3.

Малюнок 3

Клацніть по іконці Майстер імпорту на панелі інструментів. З’явиться сторінка Майстер імпорту, приклад якої наведений на малюнку 4.

Малюнок 4

Клацніть по кнопці Старт. В наслідок чого сторінка прийме вигляд, який показано на малюнку 5.

Малюнок 5

У переліку Тип файлу, оберіть тип вашого файлу з кодами та тарифами. Клацніть по кнопці Обрати і виберіть цей файл. Після чого клацніть Далі.

Якщо ви обрали файл типу Excel, то наступне крок (Малюнок 6) дозволить вам в переліку Доступні таблиці вибрати аркуш, який містить необхідні дані в цьому файлі.

Малюнок 6

Клацніть Далі, і сторінка майстра імпорту прийме вигляд, як показано на малюнку 7.

Малюнок 7

На цьому кроці імпорту користувач повинен зв’язати поля бази даних Tariscope з найменуваннями стовпців файлу, з якого виконується імпорт. Для швидкого визначення стовпців файлу вони відображаються внизу сторінки.

В переліку Код треба обрати стовпець, який містить телефонний код або коди. В наведеному прикладі це стовпець з назвою Numbering plan.

Перелік Назва використовується для назви населеного пункту або мобільного оператора зв’язку, якому належать телефонні коди. В наведеному прикладі це стовпчик з назвою Destination.

В переліку Назва тарифу в більшості випадків слід обрати те ж саме значення, що і в попередньому. Для нашого прикладу це стовпчик з назвою Destination.

В переліку Тариф слід обрати стовпчик, який містить вартість тарифу. Для нашого прикладу це стовпчик з навою Rates in USD per minute.

Якщо у файлі для імпорту є стовпець, який містить інформацію про тип виклику: коди, які відповідають міжнародним, міжміським, мобільним та іншим, то виберіть цей стовпець в переліку Тип виклику. Це необов’язковий параметр.

Будь-який телефонний код можна прив’язати до заздалегідь створеної категорії викликів. Наявність категорії може дозволити фільтрувати виклики по ним, створювати спеціальні звіти, а також встановлювати обмеження для абонентів, якщо ліцензія на Tariscope містить функцію обмеження. Для встановлення категорії для телефонного коду виберіть її в переліку Категорія. Це необов’язковий параметр. Файл прикладу немає відповідного стовпчика.

В переліку Діє з виберіть стовпчик з датою, з якої починає діяти телефонний код. В наведеному прикладі це стовпчик Effective Date. Якщо в файлі для імпорту немає такого стовпчика, то при імпорті буде встановлена поточна дата у якості дати початку дії телефонного коду.

Якщо файл для імпорту містить стовпець з датою, до якої діє телефонний код, то оберіть цей стовпець в переліку Діє по. Це необов’язковий параметр.

Tariscope може тарифікувати як вихідні, так і вхідні виклики. Для кожного із них використовуються окремі тарифи. Відповідно ви повинні вибрати, для якого типу викликів будуть імпортуватися тарифи: для вихідних (в файлі для імпорту повинно бути значення 0) або вхідних (в файлі для імпорту повинно бути значення 1). Якщо такого поля в файлі немає, то не вибирайте нічого в позиції Напрямок тарифу. В цьому випадку будуть розумітися вихідні виклики.

В переліку Діє з (тариф) виберіть стовпчик з датою, з якої починає діяти тариф. В наведеному прикладі це стовпчик Effective Date. Якщо у файлі для імпорту немає такого стовпчика, то при імпорті буде встановлена поточна дата у якості дати початку дії тарифу.

Таким чином, для нашого прикладу треба виконати вибір, як показано на малюнку 8.

Малюнок 8

Клацніть Далі. Сторінка майстра прийме вигляд, приклад якого наведений на малюнку 9.

 Малюнок 9

Це останні налаштування імпорту.

Якщо треба імпортувати як телефонні коди, так і тарифи, то перемикач Імпортувати тільки коди треба вимкнути.

В переліку Оператор слід вибрати оператора, до якого буде виконувати імпорт тарифів. Ми створили оператора Test 001, якого і вибрали.

В переліку План за замовчуванням слід вибрати той, до якого будуть відноситися вартість тарифів.

В позиції Валюта виберіть ту, в якій задані тарифи в файлі для імпорту. В нашому файлі, це долари США (USD).

Якщо ви оператор зв'язку (використовуєте Tariscope Provider), і бажаєте, щоб виклики за усіма тарифам, які будуть створені, нараховувались на особовий рахунок абонента за місяць під однією назваю, наприклад, "Міжнародні виклики", то введіть цю назву в позиції Опис про рахунки.

Якщо треба, щоб виконувалась тарифікація з точністю до секунд, то слід вимкнути перемикач Округлення до хвилин.

Перемикач Оновити тарифи є актуальним, коли ви оновлюєте дані по раніше введеним тарифам. В цьому випадку слід увімкнути цей перемикач. Якщо він вимкнений, то будуть додаватися тільки нові телефонні коди і їх тарифи, які є в файлі для імпорту.

Клацніть Імпортувати.

По закінченню імпорту з’явиться інформація про кількість доданих телефонних кодів, а також тарифів.

Якщо ви оновлюєте тарифи для вже існуючих в базі телефонних кодів, то вони додаватися повторно не будуть.

Якщо повернутися до сторінки тарифів конкретного оператора, для якого виконувався імпорт даних, і там вибрати відповідний тарифний план, то побачимо всі імпортовані тарифи (малюнок 10).

Малюнок 10

Тільки імпорту кодів і тарифів до системи Tariscope недостатньо, щоб правильно виконувалася тарифікація викликів. Є ще деякі налаштування, які повинні бути виконані. Про ці налаштування є окрема стаття. Відмітимо тільки, те, що відноситься до кодів і тарифів конкретного оператора зв’язку. Цей оператор повинен бути прив’язаний до маршрутів (груп ліній зв’язку), шлюзів телефонної системи.

У випадку, коли ви тільки створили нового оператора зв’язку і при імпорті кодів і тарифів щось виконали неправильно, ви можете просто видалити цього оператора і потім створити його заново. Для цього скористайтеся сторінкою Оператори (малюнок 2).

Якщо ви оператор зв’язку і ви маєте декілька тарифних планів, в яких різна вартість тарифів, яка становить якийсь відсоток від вартості основного тарифного плану, то можна легко в Excel файлі створити додаткові стовпці для цих тарифних планів. А потім слід повторити імпорт тарифів для цих тарифних планів.

Ще є одна особливість для користувачів редакції Tariscope Provider, яку слід мати на увазі. При імпорті тарифів для кожного телефонного коду або групи телефонних кодів, які задані в одному рядку, створюється окремий тариф. При обробці інформації про виклики в таблиці особистих рахунків абонентів буде створюватися окремий запис за звітний період для кожного тарифу, і всі виклики по цьому тарифу підсумовуються в цьому записі. Наприклад, якщо абонентом були виконано виклики в 20 країн на протязі місяця, то в особистому рахунку цього абонента буде створено 20 записів. В більшості випадків це непотрібно, а достатньо одного запису, наприклад, з назвою Міжнародні виклики, який би об’єднував нарахування за всі міжнародні виклики. В тарифах є налаштування, яке дозволяє об’єднати всі нарахування за виклики якогось типу з різними тарифами в одному запиту особистого рахунку. Для цього використовується позиція Опис на вкладці Особисті рахунки конкретного тарифу (малюнок 11).

Малюнок 11

Тобто, якщо в усіх тарифах, які відносяться до викликів в інші країни, в цій позиції ввести, наприклад назву Міжнародні виклики, то усі нарахування за виклики за кордон на протязі місяця будуть нараховані на один запис.

Додати такий опис можна одночасно для групи тарифів, якщо на сторінці Тарифи увімкнути перемикачі Показати всі введені дати та Вибрати кілька (малюнок 12).

Малюнок 12

Вибір необхідних рядків виконується за допомогою клацання по необхідному рядку таблиці тарифів.

Але при великій кількості тарифів їх вибір може зайняти багато часу. Тому пропонуємо скористатися виконанням SQL запиту. Припустимо ми бажаємо встановити назву Міжнародні виклики для занесення на особисті рахунки для усіх тарифів, які починають дію з 01.01.2022. Для цього виберіть в меню Додаткові опції -> SQL-запити, де ввести наступний запит:

UPDATE TarifSettings SET AccountsDescription = 'Міжнародні виклики' WHERE RecDate = '20220101'

В ньому змініть дату 01.01.2022 (‘20220101’) на необхідну для вас дату, а значення ‘Міжнародні виклики’ на потрібну для вас назву.

Клацніть по іконці Виконати на панелі інструментів. Після цього всі виклики, які будуть оброблятися за цими тарифами будуть нараховуватися на один запис з назвою ‘Міжнародні виклики’.

Наведемо ще кілька SQL запитів, які можуть статися у нагоді.

Зміна дати тарифів.

Наприклад, треба змінити дату початку дії усіх тарифів на 01.02.2022, які зараз мають дату 01.01.2022. Для цього на сторінці SQL-запити слід виконати наступний запит:

UPDATE TarifSettings SET RecDate = '20220201' WHERE RecDate = '20220101'

Видалення тарифів від конкретної дати.

Наприклад, треба видалити всі тарифи, які діють з 20220201. Для цього слід виконати наступний запит:

DELETE FROM TarifSettings WHERE RecDate = '20220201'

Пов’язані статті

1. Параметри операторів зв’язку. 

2. Налаштування тарифікації викликів в системі Tariscope. 

3. Тарифні плани. 

4. Маршрути та шлюзи. 

Робота з новими методами Tariscope АРІ

Для тестування функції Tariscope API може використовуватися будь-яка самостійно написана програма або стороні програми, які призначені для цього. В цій статі використовувалась програма Postman.

Для роботи з Tariscope API в першу чергу треба створити відповідного користувача і надати йому права на всі або окремі методи API.

Для створення API користувача, в меню Tariscope виберіть Додаткові опції → Інтеграція. Клацніть по кнопці Tariscope API. З’явиться відповідна сторінка.

Клацніть по Користувачі АРІ. На панелі інструментів клацніть по іконці Додати.

З’явиться вікно Новий АРІ користувач, де слід ввести необхідні параметри та клацнути Зберегти.

В переліку користувачів АРІ виберіть того, що створили та клацніть по іконці права на методи. З’явиться сторінка Налаштування прав користувача, приклад якої показаний на малюнку 1.

 Малюнок 1

На малюнку виділені методи, які були додані у версії Tariscope 4.6.4. Ці методи мають наступне призначення:

• accounts.charges. Це GET метод, який дозволяє отримати всі нарахування конкретного абонента за вказаний період.
• accounts.payment. Це POST метод, що дозволяє занести в базу даних Tariscope інформацію щодо оплат від абонента за надані послуги зв’язку.
• accounts.payments. Це GET метод, який дозволяє отримати інформацію з бази даних Tariscope щодо оплат від конкретного абонента за заданий період.
• subscriber.create. Це POST метод, який дозволяє створити нового абонента без переліку телефонних номерів, що йому належать. Для додання телефонних номерів слід використовувати наступний метод.
• subscriber.dnadd. Це POST метод, який дозволяє додати абоненту телефонний номер.

Робота з Tariscope API повинна починатися з авторизації АРІ користувача в системі, яка виконується за допомогою методу api.auth. В наслідок виконання цього методу ви повинні отримати токен, який потрібно застосовувати при виконанні всіх інших АРІ методів. Строк дії токена 6 годин. Після чого слід отримати новий токен.

1. Отримання токена

Для виконання будь-яких методів API необхідно авторизуватися в системі. Виконайте метод /api/auth.

Як згадувалося вище робота з Tariscope API методами буде показана з використанням програми Postman.

Оберіть метод Post, та введіть запит для підключення до комп’ютера, де встановлений Tariscope (малюнок 2).

 Малюнок 2

Приклад запиту: http://localhost:7000/api/auth

localhost використовується тільки у випадку, коли програма, з якої виконується API запит, знаходиться на тому ж сервері, де знаходиться ПЗ Tariscope. В інших випадках використовуйте IP адресу серверу Tariscope.

7000 в цьому прикладі – це IP порт, на якому працює Tariscope. За замовчування при встановленні Tariscope пропонується IP порт 8085.

/api/auth – це метод для авторизації в системі.

Перед відправкою запиту в тілі (Body) запиту слід вибрати row, задати JSON формат та ввести в цьому форматі ім’я API користувача (username) та його пароль (password).

На вкладці Authorization вибрати Bearer token.

Після цього натиснути на кнопку Send. Якщо всі параметри задані правильно, то ви отримаєте відповідь в JSON форматі, звідки слід копіювати токен.

Для виконання всіх інших методів Tariscope API цей токен слід вставити на вкладці Authorization в позицію Token. Нагадаємо ще раз, що токен має дію на 6 годин.

2. Отримання нарахувань абонента

Отримання нарахувань виконується за допомогою GET методу /api/accounts/charges Параметри методу:

• id – ідентифікатор абонента в системі Tariscope;
• fromdate – дата, починаючи з якої треба отримати нарахування. Дата задається у форматі: рррр-мм-дд, наприклад: 2023-05-01.
• todate – дата, закінчуючи якою треба отримати нарахування. Дата задається у форматі: рррр-мм-дд, наприклад: 2023-05-31.

Наприклад, нас цікавлять нарахування абонента з ідентифікатором 6169 за травень 2023 року. Тобто в цьому випадку маємо:

id = 6169, fromdate = 2023-05-01, todate = 2023-05-31. Відповідно задаємо рядок GET запиту:

http://localhost:8085/api/accounts/charges/?id=6169&fromdate=2023-05-01&todate=2023-05-31

Приклад такого запиту в програмі Postman показаний на малюнку 3. Слід не забувати, що як і в попередньому запиті в його тілі (Body) повинно бути вказані ім’я та пароль API користувача.

Малюнок 3

Якщо всі параметри вказані вірно, то Tariscope поверне інформацію про нарахування абонента. Перелік параметрів по кожному нарахуванню:

• id – ідентифікатор абонента в системі Tariscope;
• recdate – дати занесення нарахування в Tariscope;
• fromdate – дата початку періоду нарахування послуги;
• todate – дата закінчення періоду нарахування послуги;
• servicename – назва послуги;
• charge – нарахована сума;
• numberofservices – кількість нарахованих послуг. Для викликів це кількість секунд.

Приклад відповіді сервера показаний на малюнку 4.

Малюнок 4

У випадку, коли рядок запиту вказаний невірно або невірно вказані параметри запиту, то Tariscope повертає повідомлення (message) про це. Приклад цього наведений на малюнку 5.

Малюнок 5

3. Занесення в Tariscope інформацію про оплату

Занесення інформації про оплату від абонента виконується POST запитом: /api/accounts/payment

Параметри POST запиту до системи Tariscope:

• id – ідентифікатор абонента в системі Tariscope;
• paymentday – дата виконання оплати у форматі: рррр-мм-дд;
• payment – сума платежу за послуги зв’язку;
• paymenttype – тип платежу (не вказано – 0, готівка – 1, за квитанцією – 2, по рахунку – 3);
• bank – банк, через який виконувалася оплата.

Приклад.

Абонент з ідентифікатором 6193 оплатив 17/05/2023 по рахунку через ПриватБанк послуги зв’язку на суму 370,00 грн. Це означає:

id=6193,

paymentday=2023-05-17,

payment=370.00,

paymenttype=3,

bank=ПриватБанк

Тобто рядок POST запиту буде наступний:

http://localhost:8085/api/accounts/payment/?id=6193&paymentday=2023-05-17&payment=370.00&paymenttype=3&bank=ПриватБанк

Якщо параметри запиту вірні, то Tariscope поверне наступні дані:

• subscriberid – ідентифікатор абонента в системі Tariscope;
• paymentid – ідентифікатор запису по оплаті.
• paymentday – дата виконання оплати у форматі: рррр-мм-дд.

Приклад відповіді наведений на малюнку 6.

Малюнок 6

4. Отримання інформації щодо оплат від абонента за період

Отримання такої інформації виконується GET запитом: /api/accounts/payments

Параметри цього запиту:

• id – ідентифікатор абонента в системі Tariscope;
• fromdate – дата, починаючи з якої треба отримати платежі. Дата задається у форматі: рррр-мм-дд, наприклад: 2023-05-01.
• todate – дата, закінчуючи якою треба отримати платежі. Дата задається у форматі: рррр-мм-дд, наприклад: 2023-05-31.
• paymentid – ідентифікатор запису по оплаті. Якщо цей ідентифікатор вказаний у запиті, то дати ігноруються, а перевіряється наявність такого запису в БД Tariscope. Якщо цей ідентифікатор = 0, то АРІ повинне повернути всі платежі за вказаний період.

Приклад.

Отримати інформацію щодо оплат від абоненту з ідентифікатором 6169 за період з 01.04.2023 по 31.05.2023. Це означає, що треба задати наступні параметри: id=6169, fromdate=2023-04-01, todate=2023-05-31, paymenеtid=0

Тобто весь GET запит буде наступним:

http://localhost:8085/api/accounts/payments/?id=6169&fromdate=2023-04-01&todate=2023-05-31&paymenеtid=0

Якщо всі параметри вказані вірно, то Tariscope поверне наступні дані:

• subscriberid – ідентифікатор абонента в системі Tariscope;
• paymentid – ідентифікатор запису по оплаті.
• paymentday – дата виконання оплати у форматі: рррр-мм-дд.
• payment – сума оплати.

Приклад результату виконання такого запиту показаний на малюнку 7

Малюнок 7

5. Створення нового абонента

Створення нового абонента виконується за допомогою POST запиту: /api/subscriber/create

Цей запит має наступні параметри:

• fullname – повне ім’я юридичної, фізичної особи, або співробітника оператору зв’язку.
• departmentid – ідентифікатор групи, до якої належить абонент. Якщо абоненти не поділяються на групи, то вони належать до кореневої групи, яка має назву як і вузол зв’язку.
• subscribertype – тип абонента: 0 -фізична особа, 1 – юридична особа, 2 – службовий, 3 – бюджетний, 4 – пільговий.
• connectiondate - дата, з якої абонент вважається підключеним у форматі: рррр-мм-дд.
• contactnumber – номер контракту з абонентом.
• contractdate - дата контракту у форматі: рррр-мм-дд.
• accountnumber -номер особистого рахунку абонента, якщо він створюється не автоматично в Tariscope.
• personalcode – індивідуальний податковий номер для фізичних осіб.
• edrpou – код ЄДРПОУ для юридичних осіб.
• taxcode – податковий код для платників ПДВ.
• bankcode – код банку для юридичних осіб.
• bankname – назва банку.
• bankaccount – номер банківського рахунку.
• rateplanid – ідентифікатор тарифного плану, який призначений абоненту.

Приклад.

Створити абонента юридичну особу з ім’ям JSC ABC, ЄДРПОУ 55667788, ІПН 123456789, з датою підключення з 02.06.2023, з якою укладений контракт на надання послуг зв’язку за номером 247-23 від 01.06.2023.

Ця компанія обслуговується у Кредобанку, код банку 325365, рахунок в банку UA125438790123456. Цей абонент буде обслуговуватися за тарифним планом ‘Базовий’, який має ідентифікатор 43 в Tariscope. Абонента включити до групи абонентів з ідентифікатором 419.

Абоненту призначити особовий рахунок 8640-fo.

Для цих параметрів треба виконати наступний POST запит:

http://localhost:8085/api/subscriber/create/?fullname=JSC_ABC&departmentid=419&subscribertype=1&connectiondate=2023-06-02&contractnumber=247- 23&contractdate=2023-06-01&accountnumber=8640-fo&personalcode=&edrpou=55667788&taxcode=&bankcode=361234
&bankname=Кредобанк&bankaccount=UA125438790123456&rateplanid=43

При правильно заданих параметрах Tariscope повертає наступну інформацію:

• id – ідентифікатор абонента в системі.
• accountnumber -номер особистого рахунку абонента. Якщо він створюється автоматично в Tariscope, він буде збігатися з id.
• fullname – повне ім’я юридичної, фізичної особи, або співробітника оператору зв’язку.

Приклад отриманої від Tariscope інформації на цей запит, наведений на малюнку 8.

Малюнок 8

6. Додання абоненту телефонного номеру

Для додання абоненту телефонного номеру треба виконати POST запит: /api/subscriber/dnadd

Цей запит має наступні параметри:

• SubscriberId. Ідентифікатор абонента, якому додається телефонний номер.
• DN. Телефонний номер, який призначається абоненту.
• description. Опис до телефонного номеру. Необов’язковий параметр.
• fromdate. Дата, з якої цей номер належить абоненту.
• pbxid. Ідентифікатор АТС, до якої належить телефонний номер.

Приклад.

Абоненту з ідентифікатором 7334 треба призначити телефонний номер 2001 з 02.06.2023. Номер належить до АТС з ідентифікатором 292.

Для цих параметрів треба створити наступний POST запит:

http://localhost:8085/api/subscriber/dnadd/?SubscriberId=7334&DN=2001&description=&fromdate=2023-06-02&pbxid=292

Якщо параметри запиту буди вказані вірно, то Tariscope поверне наступну інформації:

• id. Ідентифікатор телефонного номеру в Tariscope.
• subscriberid. Ідентифікатор абонента, якому доданий телефонний номер.
• pbxid. Ідентифікатор АТС, до якої належить телефонний номер.
• dn. Телефонний номер.

Приклад отримання інформації про додання номеру показаний на малюнку 9.

Малюнок 9

Інсталяція Tariscope під Linux

Система Tariscope 4.6.х обох редакцій Enterprise і Provider створена на основі програмної платформи .Net 5.0 та використовує Microsoft SQL Server. Тому вибір Linux дистрибутівів для Tariscope залежить від підтримки ними цих двох компонентів.

Tariscope підтримує роботу з будь-якою редакцію Microsoft SQL Server 2022 або 2019, або 2017. Згідно з документацією компанії Microsoft, SQL Server 2022 або 2019 можуть бути встановлені на:

• Red Hat 7.7 - 7.9 для SQL Server 2019 або 8.0 - 8.6 для SQL Server 2022 та 2019.
• SUSE 12 (SP3 - SP5) для SQL Server 2019 або 15 (SP1 -SP3) для SQL Server 2022 та 2019.
• Ubuntu 16.04, 18.04 для SQL Server 2019 або 20.04 для SQL Server 2022 та 2019.

Вимоги до системи для встановлення Linux для обох версій MS SQL сервера однакові:

• пам'ять: 2 ГБ;
• файлова система: XFS або EXT4;
• місце на диску: 6 ГБ;
• частота процесору: 2 ГГц;
• тип процесора: сумісний з х64.

Tariscope потребує .Net 5.0, тому якщо Tariscope встановлюється тільки сам без Microsoft SQL сервера, а останній буде встановлений десь на іншому сервері, то платформу .Net 5.0 можна встановити на наступні дистрибутиви Linux:

• Alpine
• CentOS
• Debian
• Fedora
• openSUSE
• SLES Snap-пакети
• Ubuntu.

Якщо ж Tariscope встановлювати на одному фізичному (віртуальному) сервері разом з Microsoft SQL сервером, то дистрибутиви Linux, які для цього підходять є Ubuntu і SUSE.

Ми тестували Tariscope під Ubuntu 20.04.

Порядок встановлення Microsoft SQL Server-у, платформи .Net 5.0 та ряду програмних додатків, необхідних для роботи Tariscope, можна виконувати в довільному порядку.

1. Встановлення Microsoft SQL Server 2022

Встановлення цього SQL серверу слід виконувати згідно з інструкціями, наведеними у статті - How to install Microsoft SQL Server on Ubuntu 20.04 LTS.

2. Встановлення програмної платформи .Net 5.0

Встановлення повинно виконуватися з правами root. Тому перед кожною командою слід вказувати sudo або, щоб не вказувати це кожного разу, можна виконати команду: sudo -i

Платформа .Net 5.0 може встановлювати в одному із варіантів:

• .Net Runtime.
• .Net SDK, який містить в собі і .Net Runtime.

Для перевірки, які .Net Framework вже встановлені в системі слід ввести команди: 

dotnet --list-runtimes

dotnet --list-sdks

Існують різні варіанти для встановлення платформи .Net 5.0.

Інструкції щодо встановлення .Net Runtime наведені у статті Microsoft.

Інструкції Microsoft для встановлення .Net SDK або .Net Runtime за допомогою Snap. Наприклад, згідно цих рекомендацій для встановлення .Net SDK версії 5.0 слід виконати наступну команду:

sudo snap install dotnet-sdk --classic --channel=5.0

Далі рекомендується зареєструвати в системі аліас для dotnet-sdk.dotnet:

sudo snap alias dotnet-sdk.dotnet dotnet

Якщо встановлення .Net 5.0 виконувалось за допомогою Snap, слід зробити symlink наступною командою:

ln -s /snap/bin/dotnet /usr/bin/dotnet

3. Встановлення додаткових додатків

Для роботи Tariscope треба встановити наступні додатки:

• cpuid,
• inxi,
• libgdiplus,
• wkhtmltopdf.

Для їх встановлення виконайте наступні команди:

apt-get install cpuid

apt-get install inxi

apt-get install libgdiplus

apt-get install wkhtmltopdf

4. Встановлення і запуск Tariscope

Завантажте інсталяцію Tariscope та два скріпта:

http://softpiua.com/files/tariscope46.tar.gz

http://softpiua.com/files/ts-install.sh

http://softpiua.com/files/rrun.sh

Розпакуйте архів tariscope46.tar.gz, наприклад, в теку Tariscope, попередньо створивши її.

Перенесіть до цієї теки скріпт ts-install.sh

Припустимо, що ви користувач з ім’ям softpi.

Треба перейти до теки Tariscope за допомогою команди:

cd /home/softpi/Tariscope

та виконати наступну команду:

sh ts-install.sh -p/home/softpi/Tariscope

Ключ ‘-p’ вказує теку, куди встановлюється Tariscope.

Підключення бази даних Tariscope до Microsoft SQL серверу.

Microsoft SQL Server потрібен, щоб на ньому працювала база даних Tariscope. Тому треба її туди встановити. Якщо інсталяційний пакет Tariscope інсталювався в теці Tariscope, то резервна копія бази даних Tariscope буде знаходитися в теці …/Tariscope/www/Database/Database

Файл резервної копії Tariscope має назву: Tariscope_clear.bak

Для того, щоб встановити на MS SQL Server базу даних Tariscope з резервної копії потрібно або підключитися до цього SQL Server-а з комп’ютера з ОС Windows з встановленою на ньому SQL Server Management Studio (SSMS), або встановити інструменти командного рядка на Linux для роботи з MS SQL Server.

Як встановити інструменти командного рядка для роботи з MS SQL Server можна подивитися в статті компанії Microsoft.

Далі, підключаємося до SQL серверу, виконавши команду:

sqlcmd -s localhost -U SA -P Tariscope123

Ця команда означає, що виконується підключення до локального SQL Server-у (localhost). Підключення виконується від імені системного адміністратора (sa). Пароль до SQL серверу: Tariscope123. Ви повинні вказати той пароль, який задавався на етапі встановлення Microsoft SQL Server.

При виконанні підключення до SQL server в терміналі з’явиться символ: ‘>’, що означає, що можна вводити SQL команди. Для виконання SQL команди треба вводити команду GO. Для перевірки роботи можна задати команду для отримання назв баз даних, які є на SQL сервері:

1>select name from sysdatabases

2>go

І ви повинні отримати десь таку відповідь:

master

tempdb

model

msdb

Після цього введіть quit, щоб вийти з режиму керування SQL сервером.

Як встановити базу даних з резервної копії можна прочитати, наприклад, у статті. 

Тобто маючи права root ви повинні перейти до теки /var/opt/mssql, виконавши команду:

cd /var/opt/mssql/

Далі створити нову теку backup:

mkdir backup

Перемістити файл резервної копії до створеної теки:

mv/home/softpi/Tariscope/www/Database/Database/Tariscope_clear.bak/var/opt/mssql/backup

У вашому випадку замість тек /softpi/Tariscope/ можуть бути інші в залежності від того, які ви створили на попередніх кроках.

Знову підключитися до SQL серверу за допомогою команди наведеної вище. Для відновлення БД Tariscope з резервної копії виконайте команду:

RESTORE DATABASE Tariscope FROM DISK=’/var/opt/mssql/backup/Tariscope_clear.bak’

WITH MOVE ‘Tariscope’ TO ‘/var/opt/mssql/data/Tariscope.mdf’.

MOVE “Tariscope_log’ TO ‘/var/opt/mssql/data/Tariscope_log.ldf’

GO

Буде виконано встановлення БД Tariscope. Впевнитися, що вона встановлена можна, наприклад, виконавши команду, яка вже наводилася вище:

select name from sysdatabases

До переліку баз даних повинна буде додана база даних Tariscope.

Вийдіть із режиму керування SQL сервером.

Перемістить скріпт rrun.sh до теки www, яка знаходиться в теці Tariscope.

Перейдіть до цієї теки:

cd /home/softpi/Tariscope/www

Знайдіть файл appsettings.json. Відкрийте його на редагування. Приклад цього файлу показаний на малюнку.

 Малюнок

У рядку підключення (DefaultConnection) після Data Source вкажіть IP адресу сервера, де встановлений Microsoft SQL Server. В прикладі на малюнку 1.2.1 це IP адреса: 10.10.0.133. В цьому ж рядку у якості користувача, від якого виконується робота системи Tariscope, вказаний системний адміністратор, ‘sa’, з паролем ‘Tariscope123’. Замість користувача ‘sa’ ви можете використовувати будь-якого іншого, який має усі права (owner) на базу даних Tariscope.

Робота Tariscope виконується на сервері Kestrel. За замовчуванням цей сервер веде журнал запитів до нього. Це відображено у рядку:

“KestrelLogger”: true

Для відмови від ведення цього журналу змініть true на false. Ми рекомендуємо вести цей журнал.

Рядок “KestrelLoggerPeriod”: 1 визначає період створення нового журналу Kestrel: 0 – щоденно, 1 – щотижнево, 2 - щомісяця. При необхідності змініть період створення журналу.

IP порт, на якому буде працювати Tariscope задається у рядку:

“Http”: “8085”

Тобто за замовчуванням буде використовуватися порт 8085. За необхідністю змініть його на інший.

Якщо ви бажаєте щоб Tariscope працював по захищеному протоколу HTTPS, ви повинні мати SSL сертифікат і задати його параметри у цьому файлі.

У рядку “SSLCertificate”: “” вкажіть шлях, де знаходиться файл цього сертифікату.

У рядку “SSLPassword”: “” вкажіть пароль для цього сертифікату.

IP порт для роботи за протоколом HTTPS вкажіть у рядку:

“Https”: “”

Для включення протоколу HTTPS змініть значення false на true у рядку:

“HttpsEnabled”: false

Якщо ви бажаєте перенаправляти усі запити, які виконані до Tariscope по незахищеному протоколу, на захищений порт, то змініть значення false на true у рядку:

“HttpsRedirect”: false

Збережіть налаштування цього файлу.

Виконайте запуск Tariscope:

sh rrun.sh

Перевірити, чи запущена система Tariscope можна за допомогою команди:

systemctl status TS.MAIN.service

Якщо система запущена і працює ви отримаєте відклик на кшталт наступного:

TS.MAIN.service - Tariscope daemon

  Loaded: loaded (/etc/systemd/system/TS.MAIN.service; disabled; vendor pres>

  Active: active (running) since Sat 2022-12-24 23:14:32 EET; 3min 8s ago

  Main PID: 35886 (dotnet)

 Tasks: 0 (limit: 4648)

 Memory: 732.0K

CGroup: /system.slice/TS.MAIN.service

    ‣ 35886 /snap/dotnet-sdk/167/dotnet /home/softpi/Tariscope/www/Sof>

Після цього в браузері ви можете підключитися до системи Tariscope і почати її налаштування згідно з документом “Tariscope 4.6. Керівництво адміністратора”.