Универсальная биллинговая система BGBilling 6.2


Содержание

1. Описание основной части программы BGBilling
1. Как построено данное руководство
2. Логическая структура биллинга
3. Программная структура биллинга
4. Особенности установки под различные платформы
4.1. Linux
4.2. Windows
5. Установка вспомогательного ПО
5.1. MySQL-сервер
5.2. JDK
5.3. ActiveMQ-сервер
6. Установка сервера биллинга
7. Установка и первый запуск клиента биллинга
8. Описание интерфейса клиента биллинга
9. Настройка подсистем биллинга
9.1. Конфигурации
9.2. Логирование
9.3. RADIUS-протокол
10. Настройка сервера биллинга
10.1. Конфигурация
10.2. Почтовая подсистема
10.3. Система оповещения
10.4. Закрытый период
11. Модули
12. Плагины
13. Установка обновлений биллинга
14. Установка лицензии биллинга
15. Настройка SSL между сервером и клиентом
16. Настройка планировщика
17. Справочники
17.1. Общие сведения
17.2. Адрес - страны, города, районы, кварталы, улицы, дома
17.3. Договоры - параметры
17.4. Договоры - группы параметров
17.5. Договоры - группы
17.6. Договоры - шаблоны комментариев
17.7. Договоры - именованные номера шаблонов
17.8. Договоры - значения списков
17.9. Договоры - обслуживание
17.10. Договоры - скрипты поведения
17.11. Типы платежей
17.12. Типы расходов
17.13. Типы времени
18. Договор
18.1. Общие сведения, создание договора
18.2. Обзор карточки договора
18.3. Параметры договора
18.3.1. Общие сведения
18.3.2. Копирование параметров
18.3.3. Параметры типа "Текст", "Флаг", "Дата", "E-Mail"
18.3.4. Параметр типа "Адрес"
18.3.5. Параметр типа "Список"
18.3.6. Параметр типа "Мультисписок"
18.3.7. Параметр типа "Телефон"
18.3.8. История изменения параметра
18.4. Группы договоров
18.5. Поиск договоров
18.6. Баланс
18.7. Лимит договора, режимы договора, управление лимитом
18.8. Режимы баланса договора
18.9. Статус договора
18.10. Тариф и группа тарифов
18.11. Примечания
18.12. Дополнительные действия
18.13. Подключение модулей и их услуг к договору
18.14. Карты регистрации договора
18.14.1. FOP-карточки
18.14.2. Полная карта договора
18.15. Шаблоны договоров
18.15.1. Шаблон имени
18.15.2. Лимит, лицо, режим, время жизни, статус
18.15.3. Модули
18.15.4. Прочие параметры
18.15.5. Создание договора по шаблону
18.16. Субдоговоры
18.16.1. Добавление субдоговоров
18.16.2. Зависимые субдоговоры
18.16.3. Независимые субдоговора
18.17. Переоформление договоров
18.18. Удаление договоров, архив договоров
19. Тарифные планы
19.1. Общие сведения
19.2. Редактирование тарифного поддерева
19.3. Расширение тарифных планов
19.4. Персональные тарифные планы
19.5. Порядок просмотра тарифных планов
19.6. Стандартные узлы тарифных планов
19.6.1. Услуга
19.6.2. Мультиуслуга
19.6.3. Период
19.6.4. Фильтр по времени
19.6.5. Фильтр по типу времени
19.6.6. Параметры тарификации
19.6.7. Использовать карту зон
19.6.8. Зона
19.6.9. Часть префикса и Диапазон префиксов
19.6.10. Стоимость минуты
19.6.11. Множитель цены
19.6.12. Элемент каталога
19.7. Тарифные опции
20. Объекты
21. Web-интерфейс пользователя
21.1. Общие сведения
21.2. Настройка доступа к статистике
21.3. Настройка страницы статистики
21.4. Новости
21.5. Просмотр баланса, истории платежей, расходов и наработки
21.6. Смена пароля на доступ к статистике
21.7. Смена тарифных планов
21.8. Тарифные опции
21.9. Карточки
21.10. Управление лимитом
21.11. Управление статусом
21.12. Дополнительные действия
21.13. Параметры договора
21.14. Примечания
22. Разграничение прав доступа
22.1. Пользователи, группы, права
22.2. Настройка дерева действий
22.3. Доступность пунктов меню в клиенте BGBillingClient
23. Сервис
23.1. Общие сведения
23.2. Журналы
23.2.1. Ошибки обработки логов
23.2.2. Ошибки периодических процессов
23.2.3. Журнал запросов
23.2.4. Журнал Web-запросов
23.3. Загрузка платежей и расходов из файла
23.3.1. Автоматическая загрузка реестров платежей
23.4. Групповые операции над договорами
23.4.1. Общие сведения
23.4.2. Операция "Изменение статуса"
23.4.3. Операция "Добавление группы тарифов"
23.4.4. Операция "Открытие тарифных планов"
23.4.5. Операция "Закрытие тарифных планов"
23.4.6. Операция "Добавление (Удаление) модулей"
23.4.7. Операция "Добавление разрешённых услуг"
23.4.8. Операция "Удаление(Прерывание на период) разрешённых услуг"
23.4.9. Операция "Смена тарифа"
23.4.10. Операция "Добавление скрипта"
23.4.11. Операция "Установка шаблона комментария договору"
23.5. Сообщения пользователям
23.6. Индикатор лицензии
23.7. SQL Редактор
24. Администрирование и оптимизация
24.1. Конфигурация базы данных, память
24.2. Поддержка репликации
24.3. "Мусорные" базы данных
24.4. Настройка типа хранения помесячных и подневных таблиц в MySQL
24.5. Параметры запуска клиента
2. Расширение функциональности BGBilling
1. Назначение
2. Управление динамическим кодом
3. Скрипты поведения
3.. Общие сведения
3.2. Создание скрипта поведения
3.3. Привязка динамически загружаемых Java-классов к скриптам поведения
3.4. Написание функций скрипта поведения на языке BGBS
3.5. Привязка скриптов поведения к договору
4. Скрипты поведения глобальных событий
5. Глобальные скрипты
5.1. Глобальные скрипты с использованием динамических классов Java
5.2. Глобальные скрипты на языке BGBS
5.3. Периодическое выполнение глобальных скриптов
6. Резервные копии
7. Скрипты предобработки RADIUS запросов
8. Интеграция с внешними системами
3. Модуль Card
1. Назначение модуля
2. Настройка модуля
3. Дилеры
4. Работа с карточками
5. Генератор логинов и паролей для модуля "Карточки"
5.1. Установка генератора
5.2. Использование генератора
6. Web-интерфейс
7. Web-активация
8. Суперкарты
9. IVR-Система
10. Удалённые платежи
10.1. Настройка модуля
10.2. Настройка дилера
10.3. Web-клиент
10.4. Сверка платежей
4. Модуль Enaza
1. Назначение модуля
2. Базовые понятия и алгоритм работы модуля
3. Установка и настройка модуля
4. Инструкции по активации услуг компании Enaza
5. Клиентская часть
5. Модуль Gorod
1. Назначение модуля
2. Настройка модуля
3. Работа с реестрами
4. Использование модуля
6. Модуль RentSoft
1. Назначение модуля
2. Базовые понятия и алгоритм работы модуля
3. Установка и настройка модуля
4. Инструкции по активации услуг компании Рентсофт
5. Клиентская часть
6. Работа с юридическими лицами
7. Web интерфейс
7. Модуль TrayInfo
1. Назначение модуля
2. Конфигурация модуля
3. Создание типов логинов
4. Активация TrayInfo клиентом
5. Настройка утилиты TrayInfo
6. Настройка утилиты TrayInfo3
7. Настройка утилиты TrayInfo для Mac Os
8. Отображение в утилите произвольной информации вместо баланса
8. Модуль Assist
1. Назначение модуля
2. Настройка модуля
3. Оплата через систему Assist
4. Мониторинг и администрирование платежей
5. Настройка автоматической установки статусов платежей
6. Настройка сети, фаервола и т.д.
7. Важные замечания
9. Модуль Bill
1. Назначение модуля
2. Краткий алгоритм работы модуля
3. Настройка модуля
3.1. Настройка позиций
3.1.1. Экстакторы
3.1.2. Детализация по тарифу
3.2. Номерной пул
3.3. Типы документов
3.4. Настройка банков
4. Настройка параметров договора
5. Выставление счетов и счетов-фактур администратором
6. Работа со счетами
6.1. Первичная подготовка для курьерской службы
7. Работа со счетами-фактурами
8. Панель просмотра документов
9. Генерация печатных форм
10. Отчёты договора модуля
11. Web-интерфейс пользователя
12. Тонкости интеграции с внешними (1С) системами
13. Групповые операции над договорами
13.1. Операция "Добавление ( Удаление ) типов документов"
10. Модуль Buyemoney (beta-версия)
1. Назначение модуля
2. Структура и настройка модуля
3. Настройка gpg-подписи для Yandex.Деньги
4. Настройка WebMoney
5. Использование модуля
11. Модуль BVCom
1. Назначение модуля
2. Настройка модуля
3. Оплата через систему BVCom
4. Мониторинг платежей
5. Возврат платежей
12. Модуль CerberCrypt
1. Назначение модуля
2. Настройка модуля
2.1. CerberCrypt
2.2. Pisys Irdeto
2.3. NordE/CTI
2.4. Conax
2.5. Gospell
2.6. Тестовый
2.7. Настройка каналов/пакетов
3. Настройка клиентов
4. Дополнительные возможности для Irdeto Pisys, CTI/NordE итд
5. Типы оборудования
6. «Мультирум»
7. Настройка задач планировщика
7.1. Сопоставление договоров картам
7.2. Установка актуальных статусов пакетов в картах договоров
7.3. Начисление CerberCrypt
7.4. Блокировка должников
7.5. Обновление подписок
7.6. Постепенное продление подписок
7.7. Контроль синхронизации
8. Настройка тарифных планов
9. Возможности Web-интерфейса модуля
10. Создание договоров пользователем через Web
11. Виртуальный кинозал
12. Лог синхронизаций
13. Модуль DBA
1. Назначение модуля
2. Установка и настройка модуля
3. Использование модуля
14. Модуль DialUp
1. Назначение модуля
2. Базовые понятия и алгоритм работы модуля
2.1. SNMP и NetFlow
2.2. Режимы работы RADIUS сервера
2.3. Статус соединения
2.4. Работа с соединением
2.5. Порядок тарификации
2.6. RADIUS атрибуты
3. Настройка модуля
4. REALMы
5. Наборы атрибутов
6. Выдача атрибутов соединения и выделение IP адресов
7. Настройка NASов
7.1. Скрипт предобработки запроса
7.2. Пересылка RADIUS Accounting
8. Настройка RADIUS-сервера для DialUp
8.1. Установка BGRadiusDialup на Linux-платформу
8.2. Установка BGRadiusDialup на Windows платформу
8.3. Настройка radius.properties
8.4. Администрирование BGRadiusDialup
8.4.1. Управление BGRadiusDialup
8.4.2. Расширение словаря RADIUS
8.4.3. Антиспам
8.4.4. Поведение BGRadiusDialup при критических нагрузках
8.4.5. Оптимизация работы с базой данных
8.4.6. Reject-To-Accept
9. Настройка встроенного коллектора
9.1. Переобработка NetFlow трафиков
10. Настройка клиентов
10.1. Вкладка "IP-адрес"
10.2. Вкладка "Атрибуты RADIUS"
10.3. Вкладка "Ограничения"
10.4. Вкладка "Логи"
10.5. Вкладка "Пароль"
10.6. Перенос логинов
11. Настройка тарифных планов
11.1. Простейший тариф
11.2. Разделение стоимости по времени суток
11.3. Учётные периоды
11.4. Зависимость стоимости от объема
11.5. Комбинированные зависимости
11.6. Детализация по тарифу
11.7. Использование узла "Мультиуслуга"
11.8. Указание в тарифе свойств соединения
11.9. Уровни
11.10. Тарифные опции
11.11. Тарифы с переоценкой всего потребленного трафика
11.12. Ограничение по NASам
11.13. Узел "Конфигурация тарифа"
11.13.1. Блокировка отправки атрибутов REALMа
11.13.2. Фильтр по RADIUS-атрибутам пакета авторизации
12. Переобсчёт соединений
13. Монитор соединений
14. Интеграция с модулем "Карточки"
15. Отчёты
15.1. Отчёт по сессиям, детализация
15.1.1. Детализация трафика за сессию
15.1.2. Детализация трафика за месяц
15.2. Отчёт по наработке логинов
16. Web-интерфейс
17. Начисление наработки за максимальные трафики
18. Динамическое управление DNS-сервером
18.1. Пример настройки DNS сервера
18.2. Пример настройки модуля
18.3. Пример настройки логина
19. Настройка автозакрытия соединений
20. Поддержка CallBack
21. Настройка RADIUS-сервера с различными шлюзами CISCO
22. Настройка WiFi-агента для работы с модулем Dialup
22.1. Описание WiFi-агента
22.2. Установка, настройка и запуск
22.3. Связь WiFi-агента с модулем "Карточки".
22.4. Защита WiFi-сети от ARP-спуффинга
22.5. Настройка ограничения скорости (шейпинг) для трафика WiFi-сети.
22.6. Настройка REALMов
22.7. Web-интерфейс
15. Модуль DrWeb
1. Назначение модуля
2. Базовые понятия и алгоритм работы модуля
3. Установка и настройка модуля
4. Управление подписками
5. Web-интерфейс
6. Настройка тарифных планов
16. Модуль E-Mail
1. Назначение модуля
2. Установка и настройка модуля
2.1. Домены
2.2. Настройка конфигурации
2.3. Хранилище почтовых аккаунтов
2.3.1. LDAP база
2.3.2. SQL база
2.4. Настройка планировщика
3. Использование модуля
17. Модуль Inet
1. Назначение модуля
2. Базовые сведения о модуле
3. Настройка модуля
4. Трафики
5. Ресурсы
5.1. IP ресурсы
5.2. VLAN-ресурсы
5.3. Ресурсы интерфейсов.
6. Типы устройств
6.1. Обработчик активации сервисов
6.2. Обработчик процессора протокола
6.3. Обработчик управления устройством
7. Устройства
7.1. Корневые устройства
7.2. Интерфейсы
8. Опции
9. Типы сервисов
10. Сервисы
10.1. Шаблоны договоров
10.2. Дочерние сервисы
10.3. Поиск сервиса.
11. Тарифные планы
12. Сессии
13. Общий алгоритм модуля, установка и принципы настройки серверов
13.1. Установка серверов.
13.1.1. Установка Access-сервера.
13.1.2. Установка Accounting-сервера.
13.2. Общая часть конфигурации
13.3. Слушатель InetRadiusListener
13.3.1. Процессор ru.bitel.bgbilling.modules.inet.radius.InetRadiusProcessor
13.3.1.1. Посервисный аккаунтинг
13.3.1.2. Пример конфигурации устройства-NAS'а
13.4. Слушатель InetDhcpListener
13.4.1. Процессор ru.bitel.bgbilling.modules.inet.dhcp.InetDhcpProcessor
13.4.2. Процессор ru.bitel.bgbilling.modules.inet.dhcp.InetDhcpHelperProcessor
13.5. Слушатель InetFlowListener
13.6. Настройка BGInetAccess сервера
13.7. Настройка BGInetAccounting сервера
13.8. Общий алгоритм настройки
13.8.1. Пример настройка VPN доступа(PPPoE/PPPtp).
13.8.2. Пример настройки IPoE, управление доступом.
13.8.. Сбор netlow.
14. Монитор соединений.
15. Личный кабинет (web-статистика)
16. Интеграция с модулем Card
17. Переобработка логов.
18. Переобсчет.
19. Отчеты модуля Inet.
20. Коды ошибок авторизации
21. Настройка WiFi-агента для работы с модулем Inet
21.1. Описание WiFi-агента
21.2. Установка, настройка и запуск
21.3. Связь WiFi-агента с модулем "Карточки".
21.4. Защита WiFi-сети от ARP-спуффинга
21.5. Настройка ограничения скорости (шейпинг) для трафика WiFi-сети
21.6. Настройка REALM'ов
21.7. Web-интерфейс
18. Модуль IPN
1. Назначение модуля
2. Настройка модуля
3. Базовые понятия и алгоритм работы модуля
4. Привязки услуг (категории трафика)
5. Создание источников и интерфейсов
6. Управление ресурсами IP-адресов
7. Добавление адресов абонентам
7.1. Настройка выделения адресов в шаблоне договора
8. Настройка сбора и обработки логов
8.1. Настройка коллектора в автономном режиме
8.2. Настройка коллектора в связке с flow-tools
8.3. Запуск коллектора
8.4. Наладка приёма данных коллектором в автономном режиме
8.5. Настройка обработки данных
9. Подсистема аудита
10. Тарификация
10.1. Создание тарифных планов
10.1.1. Простейший тариф
10.1.2. Тариф с зависимостью стоимости от объема
10.1.3. Использование узла "Мультиуслуга"
10.1.4. Детализация по тарифу
10.1.5. Комбинированный тариф
10.1.6. Тарифные опции
10.2. Запуск начисления
10.3. Начисление наработки за максимальные трафики
11. Установка типа правила в тарифе.
12. Настройка шлюзов
12.1. Настройка типов шлюзов
12.2. Настройка шлюза
12.3. Типы правил
12.4. Добавление шлюза в договор.
12.5. Выделение ресурса VLAN на шлюз.
12.6. Настройка портов шлюза.
12.7. Настройка шлюзов типа Manad
12.7.1. Спецификация Manad
12.7.2. Обработка команд Manad.
12.7.3. Настройка шлюзов типа Manad под FreeBSD
12.7.4. Настройка шлюза типа Manad под Linux
12.8. Настройка шлюзов типа Switch
12.9. Настройка шлюза BGRadiusIPN
12.10. Настройка шлюза CISCO
12.11. Настройка шлюза DLINK 35xx, 38xx
12.11.1. Настройка в связке с DHCP шлюзом.
12.12. Настройка сервера/шлюза DHCP
12.13. Настройка шлюза Mikrotik RouterOS
12.14. Настройка шлюза Cisco2 c коммутаторами
12.14.1. Настройка шлюза Cisco2
12.14.2. Настройка шлюза коммутатора Zyxel
12.14.3. Настройка шлюза DHCP в связке с Cisco2.
12.15. Реализация шлюза на языке BeanShell
13. Отчёты модуля, детализация
13.1. Детализация трафика за час
13.2. Детализация трафика за период
14. Web-интерфейс модуля
19. Модуль MOBI.Деньги
1. Назначение модуля
2. Настройка модуля
3. Проведение платежей
4. Мониторинг платежей
20. Модуль MPS
1. Назначение модуля
2. Настройка модуля
2.1. ОСМП, Empay, Pegas, Rapida, Comepay
2.2. CyberPlat
2.3. XPlat
2.4. Eport
2.5. SFOUR PayBox Alternative
2.6. ОПТИМА plus
2.7. Elecsnet
2.8. Юникасса
2.9. Quickpay
2.10. Sberbank
2.11. Сбербанк (sbrf)
2.12. Bisys
3. Сертификаты
4. Менеджер платежей
5. Сверка платежей
6. Web-интерфейс
21. Модуль MTSBank (шлюз МТСБанк)
1. Назначение модуля
2. Настройка модуля
22. Модуль NPay
1. Назначение модуля
2. Настройка модуля
3. Привязка абонплат к клиентам
4. Алгоритм начисления, примеры тарифов
4.1. Абонплаты, не зависящие от других модулей
4.2. Абонплаты, зависящие от наработки по объёму в других модулях
4.3. Абонплаты, зависящие от денежной наработки в других модулях
4.4. Абонплаты, пропорциональные количеству телефонов, логинов и сервисов
4.5. Абонплаты, зависящие от тарифных опций
5. Методики построения тарифных планов
6. Начисление
7. Дебетовые абонплаты
8. Групповые операции
8.1. Групповая операция "Добавление/прерывание абонплат"
23. Модуль Paylinks
1. Назначение модуля
2. Настройка модуля
3. Использование модуля
24. Модуль Paymaster
1. Назначение модуля
2. Настройка модуля
3. Оплата через систему Paymaster
4. Мониторинг платежей
25. Модуль PayOnline
1. Назначение модуля
2. Настройка модуля
3. Оплата через систему PayOnline
3.1. Простой платеж
3.2. Автоплатеж
4. Мониторинг платежей
5. Сверка платежей
26. Модуль Payture
1. Назначение модуля
2. Настройка модуля
3. Проведение платежей
4. Мониторинг платежей
5. Возврат платежей
27. Модуль Phone
1. Назначение модуля
2. Настройка модуля
3. Подготовка логов
4. Настройка загрузки и обработки логов
5. Географические коды, карты зон и цен
5.1. Карта зон
5.2. Карта цен
6. Управление ресурсами номеров
6.1. Добавление ресурсов
6.2. Слежение за ресурсами
7. Учёт абонентского трафика
7.1. Тарифы на местную связь
7.2. Тарифы на МГМН-связь
7.2.1. Тарификация по префиксам
7.2.2. Тарификация по зонам
7.2.3. Тарификация по карте цен
7.2.4. Тарификация с несколькими МГМН-операторами
7.2.5. Импорт и экспорт тарифных планов голосовых модулей
7.3. Специфичные тарифные узлы модуля
7.3.1. Стоимость минуты
7.3.2. Фильтр по портам
7.3.3. Установка услуги
7.3.4. Диапазон наработки
7.4. Отчёты в клиенте
7.4.1. Сессии
7.4.2. Наработка
7.4.3. Направления
7.4.4. Услуги
7.4.5. Детализация
7.4.6. Входящие сессии
7.5. Отчёты в Web-интерфейсе
8. Учёт операторского трафика
8.1. Редактирование правил
8.2. Отчёты операторов
8.3. Транзитные операторы
8.4. Операторские отчеты
8.4.1. Общие сведения
8.4.2. Совинтел (ВымпелКом)
8.4.3. МТТ
8.4.4. Комстар
9. Тарификация при работе по агентской схеме
9.1. Составление тарифов при агентской схеме
9.2. Отчетность
10. Отключение абонентов.
11. Web-интерфейс
12. Черно-белые списки.
28. Модуль PSB (Промсвязьбанк)
1. Назначение модуля
2. Настройка модуля
29. Модуль Qiwi
1. Назначение модуля
2. Настройка модуля
3. Оплата через кошелек Qiwi
4. Мониторинг платежей
30. Модуль RBK.Money
1. Назначение модуля
2. Настройка модуля
3. Оплата через систему PayOnline
4. Простой платеж
5. Мониторинг платежей
31. Модуль Reports
1. Установка и настройка модуля
2. Отчёты основного модуля
3. Отчёты модуля DialUP
4. Отчёты модуля IPN
5. Отчёты модуля IP Телефония
6. Отчёты плагина CRM.
7. Отчёты модуля Телефония (Phone).
8. Отчёты модуля Карточки
9. Отчёты модуля RSCM
10. Отчёты модуля CerberCrypt
10.1. Отчет "Количество абонентов"
10.2. Отчет "Наработка пакетов"
11. Создание собственных отчетов
11.1. Настройка фильтра
11.2. Отчёты JasperReports.
11.3. Табличные отчёты.
12. Мобильные отчеты
12.1. Настройка сервера
12.2. Собственные отчеты.
32. Модуль RSCM
1. Назначение
2. Установка и настройка модуля
3. Использование модуля
4. События модуля
33. Модуль RuRuPay
1. Назначение модуля
2. Настройка модуля
3. Использование модуля
34. Модуль Subscription
1. Назначение модуля
2. Настройка модуля
3. Привязка подписок к клиентам
4. Примеры тарифных планов модуля
5. Групповые операции
35. Модуль Sberbank
1. Назначение и настройка модуля
36. Модуль TV
1. Назначение модуля
2. Базовые сведения о модуле
3. Настройка модуля
4. Продукты, Сервисы, Каналы
4.1. Продукты
4.2. Сервисы
4.3. Каналы
5. Типы аккаунтов
6. Типы устройств
7. Устройства
8. Аккаунты
9. Тарифы
10. Переобсчет
11. Интеграция
11.1. IPTV Портал (iptvportal.ru)
11.2. FrontStage Middleware (TelecomTV, BCC)
11.3. Middleware Stalker (infomir)
11.4. CTI TVEngine
11.5. Модуль Inet
37. Модуль Vidimax
1. Назначение модуля
2. Настройка модуля
3. Принцип работы модуля
4. Мониторинг платежей
38. Модуль VoiceIP
1. Назначение модуля
2. Базовые понятия и алгоритм работы модуля
3. Настройка модуля
4. Настройка режимов поиска и типов логинов
5. Настройка NASов
5.1. Скрипт предобработки запроса
6. Монитор
7. Настройка RADIUS-сервера для VoiceIP
7.1. Установка BGRadiusVoip на платформу Linux
7.2. Установка BGRadiusVoip на платформу Windows
7.3. Настройка radius.properties
7.4. Управление BGRadiusVoip
8. Настройка клиентов
9. Интеграция с модулем "Карточки"
10. Настройка тарифных планов
10.1. Тарификация по префиксам
10.2. Тарификация по зонам.
10.3. Тарификация по карте цен.
10.4. Смешанный режим
10.5. Модификация стоимости звонка
10.6. Импорт/экспорт тарифов
11. Работа с операторами
11.1. Старая схема
11.2. Новая схема
11.3. Оценка операторов
12. Отчёты
13. Web-интерфейс
14. Переобсчёт сессий
15. Создание договоров пользователем через Web
39. Модуль WebMoney
1. Назначение модуля
2. Настройка модуля
3. Оплата через Merchant WebMoney Transfer
4. Безопасность
5. Слежение за платежами
6. Коды ошибок
40. Модуль Yandex.Деньги
1. Назначение модуля
2. Настройка модуля
3. Оплата через Yandex.Деньги
4. Слежение за платежами
41. Плагин CashCheck
1. Назначение и структура плагина, архитектура системы
2. CashCheck-сервер (сервер печати)
2.1. Установка rxtx-библиотеки.
2.2. Настройка сервера печати и оборудования, поддерживаемые устройства.
2.2.1. Фискальный регистратор Штрих-ФР-К для использования его в BGBilling
2.2.2. Эмулятор принтера, подразумевающегося к использованию в BGBilling
2.2.3. Любой системный принтер для печати на нём XSL-FO шаблонов.
2.2.4. Устройства с протоколом от компании АТОЛ
2.3. Запуск сервера печати
2.4. Запуск двух копий сервера
2.5. Тестирование
2.6. Анализ ошибок и логгирование
3. Настройка плагина
3.1. Настройка плагина в биллинге
3.2. Настройка внешнего вида чеков (скрипты, устаревший метод)
3.3. Настройка внешнего вида чеков (динамический код)
3.4. Разделение по отделам в ККМ
4. Использование плагина
4.1. Очередь печати
4.2. Лог распечатанных платежей
4.3. Выбор принтера, отчёты, сервис
4.4. Печать чека
4.5. Настройка галочки в диалоге прихода платежа
42. Плагин КЛАДР
1. Назначение плагина
2. Установка и настройка плагина
3. Использование плагина
43. Плагин CRM
1. Введение
2. Настройка плагина
3. Справочники
4. Журнал звонков
5. Журнал проблем
6. Журнал задач
7. Журнал работ.
44. Плагин Dispatch
1. Назначение плагина
2. Настройка плагина
3. Использование плагина
3.1. Общий обзор
3.2. Типы контактов
3.3. Поиск по контактам
3.4. Методы отправки
3.5. Создание и редактирование рассылки
3.6. Подписка на рассылки
3.6.1. Контакты
3.6.2. Рассылки
3.6.3. Автоматизация подписки на рассылки с помощью групповой операции
3.7. Создание и редактирование сообщений
3.7.1. Модуль Inet
3.7.2. Модуль VoiceIp
3.7.3. Модуль DialUp
3.8. Условия отправки
3.8.1. Отправка по событию
3.8.2. Отправка по балансу
3.8.3. Ограничение частоты отправки
3.8.4. Ограничение по группе договора
3.8.5. Ограничение по адресу подписчика
3.8.6. Указание сервиса модуля Inet
3.8.7. Указание логина модуля VoiceIP
3.8.8. Указание логина модуля DialUp
3.9. Пользовательские классы сообщений
3.10. Web-интерфейс
3.10.1. Мои контакты
3.10.2. Мои рассылки
3.11. Конвертирование рассылок с версии 5.1
45. Плагин Documents
1. Назначение плагина
2. Установка и настройка плагина
3. Использование плагина
4. Шаблоны документов
5. Web-Интерфейс
46. Плагин HelpDesk
1. Назначение плагина
2. Алгоритм работы
3. Установка и настройка плагина
4. Работа с сообщениями
5. Работа с пакетами обращений
6. Web-интерфейс клиента
47. Плагин Organizer
1. Назначение плагина
2. Настройка плагина
3. Использование плагина
3.1. Общий обзор
3.2. Добавление задания
3.3. Просмотр текущих заданий
3.4. Поиск заданий
3.5. Выполнение заданий
3.6. Журнал
48. Плагин SBPilot
1. Назначение плагина
2. Структура и настройка плагина
3. Настройка утилиты sb_pilot
3.1. Донастройка в Linux
3.2. Донастройка в windows
4. Использование плагина
49. Плагин Bonus
1. Назначение плагина
2. Бонусные приходы
3. Бонусные расходы
4. Бонусный баланс
5. Бонусные программы
5.1. Операционная программа
5.2. Динамические программы
6. Настройка плагина
7. Web-интерфейс клиента
8. Шаблоны договоров
9. Групповые операции

Глава 1. Описание основной части программы BGBilling

1. Как построено данное руководство

Данное руководство в пошаговом режиме описывает развёртывание системы BGBilling.

Мы настоятельно рекомендуем вам прочитать раздел 1 Описание основной части программы в полном объёме и последовательно. Это поможет вам лучше представить общую идеологию системы и не теряться в главах-описаниях модулей и плагинов. Последующие за первым разделы вы можете читать в зависимости от тех модулей/плагинов, которые вы будете использовать.

В руководстве принято несколько простых соглашений:

  1. Все названия файлов, пунктов меню, частей графического интерфейса, пути файловой системы, URL и т.п. выделены жирным шрифтом;

  2. Названия пунктов меню выглядят так: Меню 1=>Пункт 1;

  3. Всё заключённое в скобки <текст>, либо {тест} следует трактовать как (подставьте вместо этих скобок то, что описано в тексте);

  4. Иногда названия скриптов указывается таким образом: radius.sh(.bat) ps, что следует трактовать как: запустите radius.sh ps для Linux-платформы, либо radius.bat ps для Windows-платформы.

Вам также потребуются навыки запуска консольных приложений с набором аргументов. Для пользователей Linux это не составит проблемы, для Windows мы рекомендуем сразу установить и использовать консольные оболочки, например, FAR Manager, либо пользоваться пунктом меню Пуск=>Выполнить, где сначала запускать командный интерпретатор cmd (чёрное окно с командной строкой), а далее в нем вводить команды.

Данное руководство описывает вопросы настройки непосредственно биллинга, вопросы настройки вспомогательного ПО, примеры тарифов и более подробные описания решений на базе биллинга вы можете найти в WiKi. Вы также можете описать там ваши интересные разработки.

2. Логическая структура биллинга

В системе BGBilling можно выделить следующие основные подсистемы:

  • ядро системы;

  • плагины ядра;

  • модули.

Ядро системы выполняет следующие функции:

  • подключение модулей и плагинов;

  • ведение перечня услуг;

  • ведение справочников;

  • ведение базы договоров;

  • ведение базы объектов;

  • ведение баланса договоров, истории приходов/расходов;

  • СРД - система разграничения доступа пользователей к функциям ядра, плагинов и модулей;

  • некоторые дополнительные функции.

Плагины - это программные компоненты, расширяющие функционал ядра.

Плагины инсталлируются в систему и могут быть активированы/деактивированы администратором в меню Плагины=>Настройка плагинов. После инсталляции в систему плагины нельзя удалить, можно только деактивировать. Потребность в отключении плагина может возникнуть, например, при истечении тестового периода лицензии на плагин.

При отсутствии лицензии на активный плагин система будет выдавать предупреждения.

Модули - это программные компоненты, расширяющие функционал ядра и предоставляющие, обычно, функционал связанный с тарификацией тех или иных услуг в биллинге.

Экземпляры модулей и перечни услуг в них создаются администратором в меню Модули=>Редактор модулей и услуг. Экземпляры модулей могут быть впоследствии удалены вместе со всеми данными.

Отличия плагинов и модулей в следующем:

  1. плагины никогда не предоставляют функционала по тарификации услуг, соответственно, услуг в плагинах нет;

  2. плагины не подключаются к договору в явном виде посредством услуг как модули, они существуют глобально в системе;

  3. один и тот же модуль, в отличие от плагина, может быть создан в биллинге в нескольких экземплярах (например, вы можете создать DialUp и VPN модули как 2 экземпляра модуля DialUp).

Услуга - способ разделения наработки договора по типам. Например, в модуле DialUp могут быть определены услуги: Входящий трафик, Исходящий трафик, Время. Наработка в договоре будет начислена с разбиением по данным услугам.

Договор - это ключевое понятие системы. В терминах BGBilling договор - это отдельная сущность, содержащая набор параметров, подключённых к нему модулей и тарифного плана, по которым услуги модулей тарифицируются. Каждый договор обладает отдельным балансом.

Баланс представляет из себя остаток на счету договора, историю его платежей и расходов (списаний). Подключённые к договору модули начисляют в баланс наработку по различным услугам, уменьшая исходящий остаток. Баланс в системе ведётся помесячно для всех договоров, т.е. по истечении каждого месяца исходящий остаток баланса переходит на следующий месяц.

Биллинг работает в единой валюте, мультивалютность не поддерживается.

3. Программная структура биллинга

Данная биллинговая система выполнена в клиент-серверном варианте. Общая структура изображена на рисунке.

На представленной схеме цветами выделены следующие виды компонентов:

Зелёным - отдельный процесс в операционной системе, запущенная программа;
Синим - библиотеки модулей, плагинов, либо ядра (серверные или клиентские части);
Жёлтым - часть базы данных;
Серым - визуальное отображение в клиентском приложении.

Можно выделить несколько основных частей:

Cерверная часть (BGBillingServer) - обрабатывает запросы клиента и Web-запросы;
Клиентская часть (BGBillingClient) - визуализирует работу с сервером, AРМ-оператора и администратора биллинга;
Web интерфейс пользователя (Web браузер клиента) - позволяет пользователям просматривать и модифицировать свои параметры, а также получать оперативные отчёты по модулям (просмотр сессий, звонков и т.д.);
Сервер ActiveMQ - сервер для обмена событиями между серверными приложениями биллинга;
База данных MySQL - единое хранилище и связующее звено компонентов биллинговой системы.

Можно заметить, что приложения BGBillingServer, BGScheduler, BGDataLoader используют общие библиотеки (BGBillingServer/lib), но физически являются разными процессами.

Связь клиента с сервером биллинга осуществляется через HTTP-протокол, также к серверу может обращаться браузер клиента провайдера для получения доступа к странице статистики. К серверу биллинга могут одновременно обращаться большое число клиентских приложений. Более того, под видом клиента для получения данных или их модификации к серверу могут обращаться сторонние приложения (например, бухгалтерское ПО). При этом сервер биллинга также производит авторизацию и контроль прав доступа этого клиентского приложения.

Все приложения, за исключением BGBillingClient, называются серверными приложениями биллинга, либо просто приложениями биллинга. Связь между всеми серверными приложениями осуществляется через базу данных и сервер ActiveMQ.

Также на схеме изображено, что экземпляр модуля (отдельный пункт в меню Модули) является ничем иным, как обособленным блоком данных в БД.

Преимущества клиент-серверной технологии заключаются в:

  • возможности удалённого управления серверной частью с помощью клиента;

  • одновременном доступе неограниченного количества рассредоточенных операторов к данным биллинговой системы;

  • независимости автономной работы сервера от наличия запущенного клиентского приложения;

  • наличии единой точки доступа к биллингу: отсутствие базы данных на машине оператора позволяет жёстко контролировать права доступа, гарантировать целостность данных биллинга.

4. Особенности установки под различные платформы

4.1. Linux

Установка всего серверного ПО производится под пользователем root.

В различных дистрибутивах Linux существуют разные схемы автоматического запуска служб при старте сервера. Со всеми серверными приложениями биллинга в каталоге scripts поставляются скрипты запуска с командами start и stop. Для простоты работа со службами везде описана применительно к системе sysvinit. Эта система самая старая и простая и поддерживается большинством дистрибутивов.

Все поставляемые скрипты ориентированы на командный интерпретатор Bash, либо совместимый (проверена работа с Dash), ссылка на который должна располагаться в файле /bin/sh. В случае, если у вас используется другой интерпретатор, либо отсутствует ссылка - поправьте скрипты

Рассмотрим способ добавления службы bgbilling.

1) Выполните команду runlevel, чтобы узнать уровень запуска.

[root@bill-2 init.d]# runlevel
N 3

2) Cкопируйте скрипт службы в /etc/init.d, установите права на выполнение.

chmod 755 /etc/init.d/bgbilling

3) Перейдите в папку /etc/rcN.d (N - требуемый уровень запуска), где выполните команду.

ln -s /etc/init.d/bgbilling S99bgbilling

Для запуска/остановки службы используйте /etc/init.d/bgbilling start (stop). Префикс ссылки S99 задаёт порядок старта сервиса.

4.1.1. Стандартные действия при установке

При установке каждого серверного приложения необходимо всегда выполнить несколько шагов.

1) Установите права исполнения .sh файлов и удалите Windows скрипты.

rm -f *.bat && rm -f *.exe && rm -f *.ini && chmod 744 *.sh

2) Проверьте все *.sh файлы на наличие символов ^M и удалите их, если есть. Если в системе установлена утилита dos2unix, можно воспользоваться ей.

dos2unix *.sh

4.2. Windows

Внимание

Следует учитывать, что ОС семейства Windows не являются оптимальными для запуска серверных приложений. Их применение снижает производительность дисковой подсистемы и оптимальность использования ресурсов аппаратуры. Кроме того, операционные системы данной серии менее гибко управляемы. Для запуска высоконагруженных биллинговых систем используйте ОС *NIX семейств. Ещё одним негативным фактором использования Windows является усложнение предоставления тех. поддержки по причине отсутствия полноценного shell доступа.

ОС семейства Windows НЕ РЕКОМЕНДУЮТСЯ разработчиками BGBilling для установки серверной части программы, однако хорошо подходят для запуска клиентского приложения.

Некоторые конфигурационные или шаблонные файлы компонентов системы (например, настройки BGCashCheckServer) используют кодировку UTF-8. Следует учесть, что, по традиции, в операционной системе Windows свои подходы к любой технологии и поэтому сохранённое, например, в "блокноте" не является валидным UTF-8, обратите на это внимание. Пользуйтесь текстовыми редакторами, сохраняющими правильно.

Установка всего серверного ПО производится под пользователем, обладающим администраторскими привилегиями на машине.

Для проверки и установки системных переменных окружения нажмите правой клавишей мышки по ярлыку Мой компьютер затем выберите Свойства=>Дополнительно=>Переменные среды. В нижнем окошке (Системные переменные) нажмите Создать, либо поправьте интересующую переменную.

Здесь и далее обратите внимание на необходимость установки переменной именно как системной, а не как пользовательской. Достаточно распространённая ошибка при настройке в дальнейшем службы - иначе работать не будет или будет работать неправильно. Также не забудьте перезагрузить систему после правки любой системной переменной окружения.

Все серверные приложения устанавливаются в данной ОС как службы и доступны через меню Пуск=>Настройка=>Панель управления=>Администрирование=>Службы. Следует учитывать, что ОС Windows не позволяет настроить порядок запуска служб, предоставляя взамен механизм зависимостей. Поэтому все службы по умолчанию помечены зависимыми от MySQL и ActiveMQ. В случае, если данные службы устанавливаются на отдельных машинах, необходимо удалить зависимость в .ini файле службы перед её инсталляцией (например server.ini, scheduler.ini).

4.2.1. Стандартные действия при установке

При установке каждого серверного приложения необходимо удалить все *.sh скрипты.

del /F *.sh

5. Установка вспомогательного ПО

5.1. MySQL-сервер

MySQL-сервер используется как постоянное хранилище для большинства данных биллинговой системы. Доступ к нему со стороны приложений биллинга осуществляется посредством сетевого соединения, поэтому MySQL может быть установлен на отдельной машине с любой поддерживаемой ОС. Для небольших баз, либо тестовых целей возможна установка MySQL на одну машину с сервером биллинга и другими серверными приложениями, весь процесс установки описан под этот случай и все конфигурации по умолчанию также ориентированы на этот случай.

Для работы биллинга необходим MySQL-сервер версии 5.0 и новее. Служба MySQL-сервера должна быть запущена до момента старта всех серверных приложений биллинга.

После установки MySQL-сервера (см. далее) произведите его настройку в соответствии требованиями и рекомендациями по настройке MySQL-сервера с нашего WiKi.

Подключение к MySQL для каждого приложения настраивается в .properties файле, например data/data.properties для сервера биллинга, планировщика и загрузчика логов.

db.driver=com.mysql.jdbc.Driver
db.url=jdbc:mysql://127.0.0.1/bgbilling?useUnicode=true&characterEncoding=UTF-8&allowUrlInLocalInfile=true&zeroDateTimeBehavior=convertToNull&jdbcCompliantTruncation=false
db.user=bill
db.pswd=bgbilling

Если база данных MySQL и приложение установлены на одной машине, то ничего менять не надо. В противном случае вместо 127.0.0.1 указывается IP-адрес машины с БД. Параметры db.user и db.pswd определяют имя пользователя и пароль, под которыми приложение будет подключаться к базе данных. Возможна настройка отдельного пользователя MySQL для каждого серверного приложения биллинга, это позволит сразу видеть источник запроса на MySQL-сервере.

Пользователь bill с паролем bgbilling создаётся при начальном создании БД при установке сервера биллинга (скрипт dump.sql).

5.1.1. *NIX

Для установки MySQL-сервера на *NIX-машине воспользуйтесь предусмотренным системой способом установки. Например, для Linux с пакетным менеджером yum:

yum install mysql, mysql-server

Служба сервера обычно устанавливается и стартует автоматически. Обратите внимание, что для заливки дампа базы помимо сервера MySQL вам понадобится клиентское приложение mysql.

5.1.2. Windows

Для установки MySQL-сервера на Windows-машине загрузите последнюю версию с сайта http://dev.mysql.com/downloads/mysql/. Рекомендуем устанвить MySQL Server в корень диска, например в папку C:\MySQL.

Служба сервера обычно устанавливается и стартует автоматически. Обратите внимание, что для заливки дампа базы помимо сервера MySQL вам понадобится клиентское приложение mysql.

5.1.3. О кодировках

Рекомендуемые настройки для БД "character_set" везде "utf8", настройки "collation" везде "utf8_unicode_ci" (не "utf8_general_ci").

Проверить можно запросами:

SHOW VARIABLES LIKE 'character_set%';
SHOW VARIABLES LIKE 'colla%';

Ориентировочные настройки MySQL-сервера:

[client]
default-character-set=utf8
[mysqld]
character-set-server=utf8
collation-server=utf8_unicode_ci
init_connect="SET collation_connection = utf8_unicode_ci;"

5.2. JDK

Java - язык, на котором написан биллинг, является интерпретируемым и запускается с помощью специальной программы - Java-машины. Для нормальной работы необходимо JDK версии 1.7.0, либо выше. Последнюю версию для вашей платформы можно найти по адресу http://www.oracle.com/technetwork/java/javase/downloads. Необходимо загрузить именно Java SE JDK(Java-машина + средства разработки), а не JRE (только Java-машина), т.к. биллинг использует динамическую компиляцию кода, кроме того, средства разработки могут быть полезны при расследовании нештатных ситуаций в системе.

Обратите внимание, что для нормальной работы приложений биллинга необходима JDK производства Oracle. Соответственно, приложения биллинга, в общем случае, могут быть запущены на любой платформе, для которой выпускается JDK. Это Windows, Linux, Solaris. В официальной поставке включены скрипты запуска только для Linux (Bash скрипты, скрипты сервисов для RPM-дистрибутивов) и Windows (Batch).

JDK должна быть установлена на всех серверах с компонентами биллинга, в т.ч. на клиентских машинах. Также JDK необходим для запуска ActiveMQ.

5.2.1. Linux

Загрузите .bin файл (например jdk-6u2-linux-i586.bin), скопируйте его в директорию /opt/java (создайте, если её нет), перейдите в неё, дайте права на исполнение файла и запустите. Программа проинсталлируется в текущий каталог, создав подкаталог, например jdk1.6.0_02. Путь /opt/java/jdk1.6.0_02 является JAVA_HOME - путём к Java-машине. Для более удобного обновления Java в дальнейшем рекомендуем перейти в папку /opt/java и создать символическую ссылку /opt/java/jdk.

ln -s jdk1.6.0_02 jdk

В скриптах в качестве переменной JAVA_HOME указывать /opt/java/jdk.

Замечание

При использовании Gentoo Linux обнаружена проблема с некорректным определением java текущей временной зоны. Данная ошибка связана с тем? что Oracle Java определяет временную зону по содержимому файла /etc/sysconfig/clock, который отсутствует в данном дистрибутиве.

Для решения проблемы создайте этот файл самостоятельно, заполнив следующим содержимым:

# The ZONE parameter is only evaluated by system-config-date.
# The timezone of the system is defined by the contents of /etc/localtime.
ZONE="Asia/Yekaterinburg"
UTC=false
ARC=false

Название временной зоны вы можете получить из названия каталога и файла в /usr/share/zoneinfo. Правильность установки зоны можно проверить по отметкам времени, выводимому в логе BGBillingServer/log/server.log, либо в любом другом логе.

5.2.2. Windows

Загрузите установочный .exe файл (например jdk-6u25-windows-i586.exe) и запустите его установку. Рекомендуем устанавливать ближе к корню диска, например C:\Java\Jdk-1.6.0. Иначе при установке в Program Files путь будет содержать пробелы, что неудобно при использовании в batch-файлах и командной строке.

Установка производится мастером, смените каталог установки на не содержащий пробелы, выбрав опцию Change destination folder в начале установки.

Проверьте, что системная переменная JAVA_HOME указывает на каталог установки JDK, а также на наличие в переменной PATH пути до исполнимого файла java.exe. Команда java -version в консоли должна возвращать правильную версию Java-машины.

5.3. ActiveMQ-сервер

MQ (Message Queue)-сервер необходим для передачи сообщений между различными приложениями - компонентами системы. Он также важен для работы, как и сервер базы данных. В качестве MQ-сервера используется Apache ActiveMQ. Загрузите настроенную версию с нашего FTP ftp://ftp.bgbilling.ru/pub/bgbilling/. Загружать версию из каталога linux или win в зависимости от вашей ОС.

Главный конфигурационный файл ActiveMQ, использующийся по умолчанию, находится в conf/activemq.xml. Логины и пароли расположены в файле credentials.properties.

Обратите внимание на закомментированный фрагмент, в этом отрывке настраивается сеть серверов MQ - можно запустить несколько MQ-серверов, объединенных в одну сеть. При этом указывается имя сети (default).

<!--
       <networkConnectors>
            <networkConnector uri="multicast://default" dynamicOnly="true" 
                networkTTL="3" prefetchSize="1" decreaseNetworkConsumerPriority="true" />
        </networkConnectors>
-->

В ветке plugins указан параметр, при котором все сообщения, у которых истек timeToLive будут удаляться (по умолчанию они переносятся в очередь ActiveMQ.DLQ):

            <!-- drop messages that have been sent to the DLQ -->                                                                                                                                                                            
            <discardingDLQBrokerPlugin dropAll="true"/>  

Ниже описывается использование системных ресурсов для NON_PERSISTENT, PERSISTENT-сообщений и временных очередей. При превышении данных ресурсов отправка сообщений будет замедлена:

        <systemUsage>
            <systemUsage>
                <memoryUsage>
                    <memoryUsage limit="128 mb"/>
                </memoryUsage>
                <storeUsage>
                    <storeUsage limit="10 gb"/>
                </storeUsage>
                <tempUsage>
                    <tempUsage limit="1 gb"/>
                </tempUsage>
            </systemUsage>
        </systemUsage>

В этом отрывке указывается тип коннектора для работы с сервером, интерфейс и порт:

        <transportConnectors>
            <transportConnector name="nio" uri="nio://127.0.0.1:61616" discoveryUri="multicast://default"/>
        </transportConnectors>

К этому порту будут подключаться к серверу MQ приложения биллинговой системы. Если все компоненты биллинга установлены на одном сервере, то можно оставить значение uri=nio://127.0.0.1:61616. Иначе нужно указать ip интерфейса, на который будут идти подключения или установить uri=nio://0.0.0.0:61616, чтобы порт был открыт на всех интерфейсах.

Параметры подключения к серверу ActiveMQ указываются в каждом серверном приложении в .properties файле, например в data/data.properties для сервера биллинга.

mq.url=failover:(nio://127.0.0.1:61616)
mq.user=bill
mq.pswd=bgbilling

Для локальной машины mq.url=failover:(nio://127.0.0.1:61616), для нескольких серверов (должна быть настроена поддержка сети серверов в каждом из MQ-серверов):

mq.url=failover:(nio://mq1.core.provider.org:61616,nio://mq1.core.provider.org:61616)

В последнем случае подключение будет к случайному из списка, если подключение невозможно - идет попытка подключения к следующему указанному серверу MQ, и так пока не установится подключение. Если второй сервер играет роль "запасного" - например, он установлен на слабой машине и должен принять работу только, если прервется работа первого сервера, то можно указать, чтобы подключение не устанавливалось к случайному, а попытки шли в указанном порядке:

mq.url=failover:(nio://mq1.core.provider.org:61616,nio://mq1.core.provider.org:61616)?randomize=false

5.3.1. Linux

Внимание

Убедитесь, что имя сервера с ActiveMQ указано в файле /etc/hosts. Имя сервера можно получить командой uname -n.

Пример установки ActiveMQ версии 5.4.2 в каталог /opt.

1) Перенесите каталог с ActiveMQ в /opt (/opt/apache-activemq-5.4.2);

2) Создайте символическую ссылку

ln -s /opt/apache-activemq-5.4.2/bin/linux-x86-32 /opt/apache-activemq-5.4.2/bin/linux

либо, если у вас 64х разрядная ОС

ln -s /opt/apache-activemq-5.4.2/bin/linux-x86-64 /opt/apache-activemq-5.4.2/bin/linux

3) Укажите в скрипте запуска /opt/apache-activemq-5.4.2/bin/linux/wrapper.conf переменную wrapper.java.command. Например:

# Java Application                                                                                                                                                                                                                                          
wrapper.java.command=/opt/java/jdk/bin/java 

4) Создайте ссылку на службу.

ln -s /opt/apache-activemq-5.4.2/bin/linux/activemq /etc/init.d/activemq

Настройте автоматический запуск службы и запустите её. При работе на одной машине с приложениями биллинга служба должна стартовать раньше всех приложений биллинга (регулируется префиксом ссылки).

Логи выполнения хранятся в data/activemq.log и data/wrapper.log, по ним можно проследить безаварийный старт сервиса.

5.3.2. Windows

Настройте системную переменную ACTIVEMQ_HOME, указывающую на каталог установки ActiveMQ.

Перейдите в директорию ACTIVEMQ_HOME/bin/win32. Выполните InstallService.bat. После выполнения в списке служб Windows должна появится служба ActiveMQ.

Логи выполнения хранятся в data/activemq.log и data/wrapper.log, по ним можно проследить безаварийный старт сервиса.

6. Установка сервера биллинга

Для работы сервера биллинга необходима установка и запуск MySQL и ActiveMQ-сервера.

Извлеките из архива BGBillingServer_X.X_Y.zip файл dump.sql и BGBillingServer (X.X - номер версии, Y - билда) в каталог установки. Стандартный каталог установки для Linux /usr/local, для Windows - C:\.

Перенесите файл dump.sql на машину с MySQL-севером, если это отдельная машина. Перейдите в каталог в dump.sql, запустите

mysql --default-character-set=utf8 < dump.sql

для создания базы данных.

При необходимости скорректируйте параметры подключения к БД и ActiveMQ в data/data.properties. Там же можно скорректировать прослушиваемый порт, адрес, порт управления.

При успешном запуске (см.далее) в папке log биллинга должны появится server.log и server.out. В первом должно быть примерно следующее:

INFO   13.07.2005 19:42:42  Starting BGBillingServer..
INFO   13.07.2005 19:42:42  HTTP port: 8080
INFO   13.07.2005 19:42:42  Browsing installed modules..
INFO   13.07.2005 19:42:42  dialup v.3.5
INFO   13.07.2005 19:42:42  email v.3.5
...
INFO   13.07.2005 19:42:42  Starting listen admin port 2005

6.1. Linux

Выполните стандартные действия, предшествующие установке приложения на Linux.

Установите переменную JAVA_HOME в файле setenv.sh.

JAVA_HOME=/opt/java/jdk

Замечание

Служба загрузчика логов (dataloader) используется только в модуле Phone. Если вы не используете этот модуль, можете её не устанавливать.

Создайте службы сервера, планировщика и загрузчика логов. Для этого используйте скрипты из BGBillingServer/script. Скрипт bgcommonrc таже необходимо перенести в /etc/init.d, он содержит общие переменные для скриптов сервера, планировщика и загрузчика логов.

Запустите сервер, планировщик задач и загрузчик логов.

/etc/init.d/bgbilling start
/etc/init.d/bgscheduler start
/etc/init.d/bgdataloader start

6.2. Windows

Выполните cтандартные действия, предшествующие установке приложения на Windows.

Установите переменную окружения BGBILLING_SERVER_DIR=C:\BGBillingServer.

После этого необходимо перезагрузить компьютер.

Замечание

Служба загрузчика логов (BGDataLoader) используется только в модуле Phone. Если вы не используете этот модуль, можете её не устанавливать.

Проинсталируйте службу сервера, планировщика и загрузчика логов. Для этого перейдите в папку C:\BGBillingServer и запустите server_install.bat, scheduler_install.bat и dataloader_install.bat.

Зайдите в управление службами и запустите службы BGBillingServer, BGScheduler, BGDataLoader.

7. Установка и первый запуск клиента биллинга

Клиентское приложение единое для Windows и UNIX-систем, различия в установке незначительны, поэтому процесс описан в одной главе.

1) Загрузите клиент биллинга BGBillingClient_X.X_Y.zip (X.X - номер версии, Y - билда)и распакуйте его в произвольное место. На машине, где установлен клиент должна стоять JDK (допускается JRE);

2) Выполните стандартные действия для Linux, либо стандартные действия для Windows;

3) Для Linux пропишите переменную JAVA_HOME в начале .sh скриптов:

cd ${0%${0##*/}}.

JAVA_HOME=/opt/java/jre

4) В каталоге BGBillingClient найдите файл client.properties.

db.server.0.title=MyBilling
db.server.0.url=http://127.0.0.1:8080/bgbilling/executer
db.server.0.proxy.host=
db.server.0.proxy.port=

В случае, если клиент установлен на одну с сервером машину, ничего менять не надо. Если необходимо подключиться к серверу с другого рабочего места укажите вместо 127.0.0.1 адрес машины, где установлен сервер BGBilling и, при необходимости, хост и порт прокси, если подключение идёт не напрямую.

Аналогичным образом вы можете добавить ещё один сервер BGBilling, доступный для подключения. Нужно лишь добавить аналогичный набор записей ниже, исправив server.0 на следующий номер. Например:

db.server.1.title=NextBilling
db.server.1.url=http://www.bill.com:8080/bgbilling/executer
db.server.1.proxy.host=my.proxy.com
db.server.1.proxy.port=3128

При запуске клиента вам будет предложено выбрать сервер для подключения. Кроме редактирования файла возможно добавление серверов в окне логина, как это сделать описано далее.

5) Запустите клиент с помощью пакетного файла bgbilling_w9x.bat для Win98/ME, bgbilling_w2k.bat для Windows2000/XP/2003, bgbilling.sh для Linux. Если клиент не стартует, либо после старта обнаруживаются проблемы, запустите DEBUG-версию bgbilling_debug.bat, либо bgbilling_debug.sh, при этом в каталоге BGBillingClient должен появится файл log, который вы можете передать разработчикам при разборе проблемы.

6) Если клиент стартовал, вы увидите окошко авторизации (см. рисунок).

В списке подключений необходимо выбрать требуемый сервер.

При установке базы биллинга в ней создаётся единственный пользователь admin c паролем admin. После первого входа желательно поменять пароль в целях безопасности.

Обратите внимание на опцию загружать обновления с этого сервера, её необходимо установить, чтобы библиотеки установленных на сервере модулей могли быть получены клиентом. Опцию можно снимать при подключении к сторонним серверам для предотвращения получения нежелательных обновлений.

При выборе в списке позиции Создать новое подключение и нажатии кнопки ... открывается редактор подключений где вы можете создать подключение к новому серверу биллинга.

Созданные таким методом подключения, также как и сохранённые логины и пароли запоминаются в файле HOME_DIR/.bgbilling/config, где HOME_DIR - домашний каталог пользователя.

Замечание

Вы можете изменить файл, в котором сохраняются пароли и дополнительные соединения установив опцию -Dlocal.setting.file.name=<имя отличное от config> в скрипте запуска клиента, например так:

start javaw -Dupdate.folder=lib.update -Djavax.net.ssl.trustStore=.keystore -Dsun.net.client.defaultConnectTimeout=1000 -Xmx256m -Duser.language=ru -Duser.region=RU -Dlocal.setting.file.name=config_v.4.5 -cp %CLASSPATH% bitel.billing.ShellFrame

Это может быть полезно, если на одной машине запускается несколько клиентов для разных версий биллинга.

Если ошибок авторизации не выдаётся, а просто происходит очистка окошек ввода логина и пароля, то, скорее всего, проблема в сервере.

Проверьте лог C:\BGBilling\log\server.out на наличие ошибок (Exception). Вероятнее всего, сервер не может соединиться с базой данных. Попробуйте взять логин и пароль из файла data\data.properties и с их помощью соединиться с БД. Для этого используйте консольный клиент mysql, расположенный в директории C:\mysql\bin. Наберите в командной строке

mysql -ubill -pbgbilling bgbilling

Если соединение не прошло, проверьте, запущен ли сервер MySQL.

7) Если вы устанавливали модули или плагины, то при загрузке клиента должно быть выведено сообщение об установке обновлении системы, после чего потребуется перезапуск клиента.

Если после логина требуется сменить текущий сервер биллинга (в случае, если у вас их несколько, см. выше как можно их добавлять) вы можете воспользоваться выпадающим списком расположенным справа от надписи БД: на панели инструментов. При первом входе на новый сервер биллинга будет запрошен логин и пароль, при последующих переключениях авторизация не требуется. Открытые вкладки клиента при переключении на другой сервер и возврате на исходный сохраняются.

8. Описание интерфейса клиента биллинга

Так выглядит основное рабочее окно программы BGBillingClient (приведена только верхняя область окна):

Интерфейс клиента биллинга построен на вкладках, открывающихся в основном окне. Это позволяет оператору держать одновременно открытыми несколько договоров/редакторов/справочников и т.п. Во вкладках открываются договоры, редакторы справочников, редакторы свойств модулей и пр.

Для закрытия вкладки (вкладок) можно нажать крестик на вкладке в нижней области окна, либо вызвать пункт меню Договор=>Закрыть вкладку (Закрыть вкладки). Пункты меню продублированы на панели инструментов кнопками Закрыть вкладку (Закрыть вкладки).

Панель инструментов расположена ниже меню. Первые семь кнопок дублируют часто используемые пункты меню Договор. Расположенные далее кнопки Новый элемент, Редактировать, Удалить элемент, Обновить действуют на текущую вкладку биллинга и являются универсальными. В контексте текущей вкладки они позволяют:

  • создать новую сущность на выбранной вкладке;

  • редактировать существующую сущность;

  • удалить выбранную сущность;

  • обновить информацию на вкладке данными с сервера биллинга.

Далее идёт выпадающий список подключений к серверу (БД). Если сменить текущий сервер, то снова вызовется диалог авторизации с вводом логина/пароля к серверу. Переключение между серверами, на которые уже произошла авторизация, происходит без вызова диалога. Если такой сервер выбрали в диалоге авторизации (диалог вызвали для не авторизованного сервера, а потом сменили на уже авторизованный), то правка логина/пароля недоступна, в диалоге при этом появляется кнопка Выйти - она разрывает соединение с сервером и он становится не авторизованным.

При смене сервера запоминаются все текущие вкладки и активная вкладка , они восстанавливаются, если вернуться к старому серверу. Далее на панели идёт вывод текущего логина и кнопка разрыва соединения с текущим сервером биллинга.

Далее на панели инструментов идет отображение текущего логина и кнопка завершения сеанса. И в завершении панели отображается актуальное время на сервере биллинга.

Меню и панель инструментов могут быть настроены редактированием файла BGBillingServer/data/menu.xml и toolbar.xml. Установленные плагины и модули могут дополнять содержимое меню и панели инструментов новыми пунктами.

Пример 1.1. Пример работы с вкладками

Выберите пункт меню Справочники=>Другие. В открывшемся справочнике типов платежей выберите корневой узел, нажмите Новый элемент в панели инструментов. В появившемся редакторе введите название типа платежа, установите галочку Элемент группы и нажмите OK.

Выберите получившийся тип платежа и удалите его кнопкой Удалить на панели инструментов. Далее закройте вкладку Редактор справочников одним из вышеописанных способов.

Возможны случаи, когда в редакторах вкладок используются кнопки не со стандартной панели инструментов. Следует использовать ближайшую к редактору панель инструментов. Пример такого случая приведён на снимке ниже.

8.1. Горячие клавиши

Во всех текстовых полях работают горячие клавиши копировать/вырезать/вставить - Ctrl+C/Ctrl+X/Ctrl+V, что позволяет использовать в работе с клиентом буфер обмена. Для копирования в буфер обмена информации, содержащейся в таблице, выберите требуемое количество строк таблицы мышью, нажимая кнопки Shift, Ctrl, либо Ctrl+A для выбора всех строк и нажмите Ctrl+C.

8.2. Коды

При настройке конфигураций, разработке расширений довольно часто необходимо получить внутренний идентификатор справочного значения, либо сущности биллинга. Идентификатор может отображаться в таблице значений в столбце ID, в редакторе открытой сущности, либо возвращаться по сочетанию клавиш Ctrl + i.

На снимках экрана ниже пример идентификаторов (кодов) типов платежей и тарифного плана (получен нажатием Ctrl + i в редакторе тарифных планов).

8.3. Редактирование даты

При редактировании дат открывается календарь с установленным предыдущим значением даты, либо с текущей датой, если предшествующее значение отсутствовало.

Кнопка ОК устанавливает выбранную дату. Х - оставляет существующее значение даты в поле ввода (отмена). Стрелки влево и вправо позволяют проматывать года и месяцы, стрелки продублированы кнопками с установленными значениями годов. Текущий год и месяц выделены жирным шрифтом.

Ctrl+стрелка вверх/Ctrl+стрелка вниз изменяют год, Ctrl+стрелка влево/Ctrl+стрелка вправо - месяц.

Также можно редактировать дату при выделенном поле даты (т.е. имеющим фокус), но не нажатом, без открытого календаря. В этом случае Ctrl+стрелка вверх/Ctrl+стрелка вниз изменяют месяц, Ctrl+стрелка влево/Ctrl+стрелка вправо - дату, Ctrl+Insert - устанавливает текущее число, Ctrl+Delete - очищают значение.

Пример 1.2. Пример работы с календарём

Для тренировки вы можете нажать меню Договор=>Новый договор либо кнопку Новый договор на панели инструментов. Нажатие поля ввода даты вызывает календарь. При вновь созданной базе биллинга список шаблонов будет пуст.

8.4. Выпадающие списки

При наборе с клавиатуре на выделенном выпадающем списке (ComboBox) производится автоматический поиск первой совпадающей по подстроке записи. При этом выше отображается набранный отрывок, а при навигации кнопками вверх/вниз выделение переходит по совпадающим полям. Esc - обнуляет отрывок поиска.

8.5. Таблицы

Практически все таблицы в биллинге настраиваемые. Можно изменять размер столбцов, положение (перемещением за заголовок), их видимость (правой кнопкой мыши на заголовке таблицы - Видимость столбцов...), затем сохранить настройки (пункт меню Запомнить расположение). Пункт меню Расширить расширяет столбцы по ширине таблицы, Сбросить расположение - сбрасывает размер, положение и видимость на значения по умолчанию.

После перенастройки таблицы данные сохраняются на сервере для данного пользователя и автоматически применяются при дальнейшей работы пользователя с сервером.

8.6. Постраничный вывод

Вывод таблицы и списков данных с большим количеством пунктов организован в биллинге постранично. Для перемотки страниц и настройки количества записей на странице используется такой элемент управления:

Кнопки позволяют переходить на первую, предыдущую, последующую и последнюю страницы. В квадратных скобках отображается текущий размер страницы. При нажатии по средней части элемента отображается следующий диалог:

Правая область используется для быстрого перехода на нужную страницу. Для этого на изображённой справа клавиатуре мышью набирается номер страницы и кнопкой OK осуществляется переход. Кнопка С позволяет отменить неправильный набор.

Левая область задаёт размер страницы. Нажатием кнопки можно установить предопределённое значение. Для установки пользовательского значения нажмите кнопку SW, далее наберите на правой клавиатуре нужное значение и нажмите OK.

Сохранённые настройки записываются в файл $USER_HOME/.bgbilling/config.

8.7. Выбор договора

В элементе интерфейса выбор договора:

Необходимо обозначить один или несколько договоров, при этом отображаются только договоры, вкладки которых открыты в данный момент в клиенте. Диалог выбора договоров вызывается кнопкой >>>.

8.8. Отключение фонового рисунка

В клиентском приложении есть возможность отключить фоновый рисунок (например, при использовании терминал сервера), добавьте в BGBillingClient/client.properties

bg.enable=0

9. Настройка подсистем биллинга

9.1. Конфигурации

Очень большое количество редко меняющихся настроек поведения системы вынесено в конфигурации. Конфигурация - это текстовый блок, состоящих из записей вида: <ключ>=<значение>. На одной строке может быть только одна такая запись, символ # в начале строки означает комментарий. Порядок записей в тексте значения не имеет. При необходимости указания порядка в ключе вводятся дополнительные числовые индексы.

Конфигурации вводятся либо в текстовых properties-файлах (опции подключения к БД, базовые настройки), либо в редакторах конфигурации в клиенте биллинга, сохраняясь в базе данных. Ядро биллинга, каждый экземпляр модуля биллинга, плагины обладают различными конфигурациями, конфигурация ядра доступна в меню Сервис=>Настройка=>Конфигурация.

На приведённом снимке экрана изображён типовой редактор конфигурации. В таблице указан перечень конфигураций, из которых в текущий момент активен только один, установка активной конфигурации производится кнопкой Установить. Установка конфигурации позволяет осуществлять быстрый переход на заранее подготовленную конфигурацию. Создание новой конфигурации производится кнопкой Создать. Открытие - двойным кликом мыши, либо кнопкой Открыть.

В значениях параметров конфигурации возможна подстановка ранее указанных значений с помощью подстановок {@имя параметра}. Рассмотрим пример подстановки.

# определение значения
howYou=how you
# использование подстановки
some.kind.of.config.record=Thats {@howYou} should use macro!

Т.е. при такой конфигурации при взятии значения some.kind.of.config.record получаем в результате строку "Thats how you should use macro!". Подставляемое значение должно быть обязательно определено ранее подстановки.

В большинстве случаев при смене конфигурации необходим перезапуск сервера, использующего данную конфигурацию. Например, при установке опций для работы RADIUS-сервера в конфигурации привязанного модуля DialUP необходим перезапуск RADIUS-сервера.

Для быстрого комментирования отдельных строк и блоков: ctrl+shift+C.

9.2. Логирование

Замечание

Вы можете пропустить, либо бегло изучить этот раздел и вернуться к нему, если вам понадобится изменение стандартных параметров логирования.

По умолчанию логи серверов сохраняются в папке log приложения. В качестве подсистемы логирования используется библиотека log4j. Конфигурирование логирования заключается в правке файла data/log4j.xml (log4j-radius.xml - для RADIUS-сервера, log4j-collector.xml - для коллектора). Это xml-файл определенной структуры.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE log4j:configuration SYSTEM "log4j.dtd">
<log4j:configuration xmlns:log4j='http://jakarta.apache.org/log4j/'>

 <appender name="APPLICATION" class="org.apache.log4j.RollingFileAppender">
  <param name="File" value="${log.dir.path}${log.prefix}.log" />
  <param name="MaxFileSize" value="100MB" />
  <param name="MaxBackupIndex" value="2" />
  <param name="Append" value="false" />

  <layout class="org.apache.log4j.PatternLayout">
   <param name="ConversionPattern" value="%d{MM-dd/HH:mm:ss} %5p [%t] %c{1} - %m%n" />
  </layout>

  <filter class="ru.bitel.common.logging.Log4JMDCFilter">
   <param name="key" value="nestedContext" />
   <param name="value" value="${log.prefix}" />
  </filter>
 </appender>

 <appender name="MQ" class="org.apache.log4j.RollingFileAppender">
  <param name="File" value="${log.dir.path}${log.prefix}.mq.log" />
  <param name="MaxFileSize" value="100MB" />
  <param name="MaxBackupIndex" value="2" />
  <param name="Append" value="false" />

  <layout class="org.apache.log4j.PatternLayout">
   <param name="ConversionPattern" value="%d{MM-dd/HH:mm:ss} %5p [%t] %c{1} - %m%n" />
  </layout>

  <filter class="ru.bitel.common.logging.Log4JMDCFilter">
   <param name="key" value="nestedContext" />
   <param name="value" value="mq" />
  </filter>
 </appender>

 <appender name="ASYNC" class="ru.bitel.common.logging.Log4jAsyncAppender">
  <appender-ref ref="APPLICATION"/>
 </appender>

 <root>
  <priority value="INFO" />
  <appender-ref ref="ASYNC" />
 </root>

</log4j:configuration>

Логирование в системе основано на категориях и контекстах. Разные контексты (server/script или collector/processor/loader) разнесены по разным аппендерам. Аппендер - это куда и как добавляется запись лога - т.е., например в файл server.log такого вида:

server 04-06/12:04:49  INFO [main] DefaultServerSetup - Init DB connection pools
server 04-06/12:04:49  INFO [main] DefaultServerSetup - Init trash pools..
server 04-06/12:04:49  INFO [main] DefaultServerSetup - Init trash pool trash_1
server 04-06/12:04:49  INFO [main] Server - Starting BGBillingServer..
server 04-06/12:04:49  INFO [main] Server - HTTP port: 6565
server 04-06/12:04:49  INFO [main] Server - Starting HTTP connector..
server 04-06/12:04:49  INFO [main] Server - HTTPS port: -1

root - это главная категория, по умолчанию priority/@value='INFO', т.е. все логирование в режиме info. Чтобы переключить логирование в режим debug, необходимо указать здесь 'DEBUG'.

 <root>
  <priority value="DEBUG" />
  <appender-ref ref="ASYNC" />
 </root>

Также в каждом аппендере можно указать фильтр по приоритету. Например, в root указать DEBUG, а в аппендере APPLICATION добавить указанную ниже ветку, чтобы логирование для всех контекстов, кроме APPLICATION было в режиме DEBUG.

<param name="Threshold" value="ERROR" />
 <appender name="MQ" class="org.apache.log4j.RollingFileAppender">
  <param name="Threshold" value="ERROR" />
  <param name="File" value="${log.dir.path}${log.prefix}.mq.log" />
  <param name="MaxFileSize" value="100MB" />
  <param name="MaxBackupIndex" value="2" />
  <param name="Append" value="false" />

  <layout class="org.apache.log4j.PatternLayout">
   <param name="ConversionPattern" value="%d{MM-dd/HH:mm:ss} %5p [%t] %c{1} - %m%n" />
  </layout>

  <filter class="ru.bitel.common.logging.Log4JMDCFilter">
   <param name="key" value="nestedContext" />
   <param name="value" value="mq" />
  </filter>
 </appender>

9.3. RADIUS-протокол

Замечание

Вы можете пропустить этот раздел при первичной установке системы и вернуться к нему, если вам понадобится работа с протоколом RADIUS.

RADIUS - протокол авторизации и аккаунтинга (передачи информации о соединении). В качестве транспорта используется UDP. Протокол бинарный, определяет формат передачи пакетов нескольких типов, в каждом из которых могут быть определены пары "атрибут-значение". NAS (Network Access Server) - сервер, через который происходит выход клиента с RADIUS-авторизацией.

Типы пакетов могут быть следующими:

1. AUTHENTICATION_REQUEST

Запрос авторизации, отправляется NASом RADIUS-серверу и содержит помимо идентификационной информации соединения, указанной выше, информацию о логине и пароле пользователя. Логин передаётся в открытом виде, пароль шифруется.

2. AUTHENTICATION_REJECT

Отказ в авторизации, может содержать атрибут с кодом ошибки.

3. AUTHENTICATION_ACCEPT

Пользователь авторизован. В данном пакете могут содержатся атрибуты, устанавливающие характеристики соединения пользователя (IP-адрес, скорость, максимальную длину сессии, частоту Update-пактов и т.п.).

4. ACCOUNTING_REQUEST

Запросы аккаунтинга могут быть трёх типов: Start, Stop, Update. Различаются они атрибутом Acct-Status-Type который равен 1, 2 или 3 соответственно. Данный тип запросов передаёт на RADIUS-сервер информацию о ходе соединения (соединение началось, завершилось или текущее состояние соединения).

5. ACCOUNTING_RESPONSE

Ответ RADIUS-сервера о том, что он получил запрос аккаунтинга. Ответ не содержит никаких атрибутов. Исключение составляет ответ MPD-серверу, который может содержать атрибут, информирующий NAS о необходимости разрыва соединения.

Посредством RADIUS-атрибутов передаётся вся информация пакета. Все используемые атрибуты должны быть описаны в файле dictionary.xml. Фактически файл определяет соотнесение кодов атрибутов их строковым обозначениям и типам. Он необходим при разборе RADIUS-пакета и при его создании, для выяснения кода атрибута по его имени.

Замечание

Обратите внимание, что строковые обозначения атрибутов в нашем словаре могут отличаться от обозначений в словарях производителей оборудования. Для взаимодействия это совершенно не важно, т.к. в пакете атрибут обозначает числовой код.

Такой файл есть в любом приложении, которому может понадобится работа с RADIUS-протоколом. Во всех конфигурациях атрибуты должны указываться с именем таким же как и в данном конфигурационном файле. Атрибуты идентифицируются по имени, недопустимы атрибуты с одинаковыми названиями в пределах dictionary.xml. Перезагрузка словаря приложением происходит при изменении конфигурации связанного с приложением экземпляра модуля.

Рассмотрим формат описания атрибута в словаре.

<attribute name="cisco-Fax-Connect-Speed" type="string" add="yes" code="8"/>

Где:

code - числовой код атрибута;
name - строковое обозначение, отображается в логах, указыается в конфигурации;
type - тип атрибута, возможные типы далее;
add - при установке в yes в пакете имя строкового атрибута дублируется в поле со значением, это особенность CISCO устройств.

Возможные типы атрибутов:

octets - последовательность байт;
string - текстовая строка;
integer - беззнаковое целое число, 4 байта;
ipaddr - IP-адрес, 4 байта;
abinary - текстовая строка с бинарными кодами.

Значения атрибутов в текстовых конфигурациях указываются в виде: <NAME>=<VALUE>, например: Framed-IP-Address=192.168.168.2. Для текстовой строки с бинарными кодами бинарный код указывается как \0x<code>, где <code> - код в 16-ичной системе счисления. Например: cisco-SSG-Command-Code=\0xC SERVICE А.

Тегированные атрибуты указываются в виде: <NAME>:<TAG>=<VALUE>, например: ERX-Activate-Service:2=testtest. Тегированный атрибут в словаре должен быть помечен атрибутом tag, который определяет логику для разных типов атрибутов.

Таблица 1.1. Логика тегирования

Тип тегирования/Тип атрибутаintegerstring
1Тег - первый байт значения, значение от 0x01 до 0x1F, если тегирования нет - его значение 0. Оставшиеся три байта - само число.Тег - первый байт значения, значение от 0x01 до 0x1F, если тегирования нет - его значение 0. Оставшиеся байты - значение строки.
2Не поддерживается.Если значение первого байта от 0x01 до 0x1F, то это тeг, иначе - первый байт - это начало значения, тэгирования нет.

При необходимости указания нескольких атрибутов они разделяются точкой с запятой, например: Framed-IP-Address=192.168.168.2;Service-Type=1;ERX-Activate-Service:2=testtest. Для указания точки с запятой в теле атрибута нужно писать её парно. Например: Framed-IP-Address=192.168.168.2;cisco-SSG-Service-Info=QU;;1024000;;512000;;D;;1024000;;512000.

Строковые представления для некоторых перечислимых числовых RADIUSатрибутов в данный момент не поддерживаются. Например, значению 1 атрибута Service-Type соответствует Login.

10. Настройка сервера биллинга

10.1. Конфигурация

После установки сервера и клиента сервер должен быть настроен, для этого откройте в клиенте пункт меню Сервис=>Настройка=>Конфигурация. В появившейся вкладке в нижней части найдите и нажмите кнопку Создать для создания новой конфигурации сервера.

Если в дальнейшем где-то упоминается Конфигурация сервера, то следует знать, что речь идёт именно об этой конфигурации. В биллинге много различных редакторов конфигурации, ориентироваться в них на стадии освоения системы может быть затруднительно.

#--------------------------------------
# Системные настройки сервера
#--------------------------------------
# Путь к временному каталогу, используется обработчиком логов для загрузки логов по FTP и сервером биллинга для хранения промежуточных файлов.
# Если не указан, то используется каталог BGBillingServer/tmp 
#temp.dir.path=
#
#-----------------------------------------
# Настройки интерфейса BGBillingClient
#-----------------------------------------
# Порядок элементов в дереве договора клиента
client.gui.contract.tree.order=parameters objects hierarchy status limit mode face balance tariff modules groups web tariffGroup script addAction memo
# Какие лимиты предлагаются на выбор в договоре 
client.gui.contract.limit.values==-2000;=-500;=-300;=-150;=-50;=-30;=-10;=0;-5/1;-50/1;-100/1;-15/3;-50/3;-100/3
# Какие лимиты предлагаются на выбор в шаблоне договора 
client.gui.pattern.limit.values=-2000;-500;-300;-150;-100;-50;-10;0;5;30;100;15;50;100
#
#--------------------------------------
# XSLT
#--------------------------------------
# Кэширование XSLT-шаблонов памяти: 1 - включить 
# Необходимо отключать опцию на момент модификации любых XSLT-шаблонов
xslt.cache=0

# Заголовок и адрес к шаблону карточки (доступны в свойствах договора)
contractcard.1=card_inet.xsl:Карта регистрации
#
#--------------------------------------
# Протокол
#--------------------------------------
# Вывод в server.log XML, возвращаемых клиенту в режиме DEBUG - 1 
server.response.debug=0
# Заголовок HTTP-пакета, в котором передаётся IP-адрес клиента, если параметр не указан или не передан, то используется request.getRemoteAddr()
# нужен при проксировании запросов с помощью nginx
header.name.remote.addr=X-Real-IP
# Максимальный размер запроса к серверу (в байтах), запросы большего размера обрезаются, что может привести к некорректной работе сервера.
# Признак того, что нужно увеличить - ошибка вида "Модуль null не найден!"
max.post.size=10000000
#
#--------------------------------------
#Копирование параметров договора - шаблоны
#--------------------------------------
# Шаблоны
contract.param.pattern.keys=bank,firm
# Название шаблона
contract.param.pattern.bank.title=Банк (реквизиты)
contract.param.pattern.firm.title=Организация (название, руководство, ИНН/КПП)
# Коды параметров договора, которые будут выделяться 
contract.param.pattern.bank.pids=12,34
contract.param.pattern.firm.pids=1,23,8,4,25
#
#--------------------------------------
# Параметр типа "Адрес"
#--------------------------------------
# проверка уникальности адреса договора при вводе - 1, 0 - не проверять
address.unique.check=1
# Формат адреса (доступен также параметр ${comment} - комментарий параметра)
addrs.format=(${index})(, ${city})(, ${area})(, ${quarter})(, ${street})(, д. ${house})(${frac})(, кв. ${flat})( ${room})(, ${pod} под.)(, ${floor} эт.)
# Разрешение создавать дома в редакторе адреса параметров договоров и объектов
#address.create=1
#
#--------------------------------------
# Параметры сущностей адресного справочника
#--------------------------------------
# Для каждой сущности можно завести неограниченное число параметров. Типы параметров могут быть числовые(int), строковые(string), дата(date)
## для страны
address.country=countPeople,test
address.country.countPeople.title=Население страны
address.country.countPeople.type=int
address.country.test.title=Тестовый параметр
address.country.test.type=string
# для города аналогично, но вместо country будет city
# для района аналогично, но вместо country будет area
# для квартала аналогично, но вместо country будет quarter
# для улицы аналогично, но вместо country будет street
# определение почтового индекса по номеру дома
address.street.boxIndexRange.title=Почтовый индекс
address.street.boxIndexRange.type=string
# для дома
address.house=dateConnecting, test, floorRange, entranceRange
address.house.dateConnecting.title=Дата подключения
address.house.dateConnecting.type=date
address.house.test.title=Тестовый параметр
address.house.test.type=string
# определение подъезда по квартире
address.house.entranceRange.title=Диапазон подъездов
address.house.entranceRange.type=string
# определение этажа по квартире
address.house.floorRange.title=Диапазон этажей
address.house.floorRange.type = string
#
#--------------------------------------
# Поведение 
#--------------------------------------
# Запрет ввода уже существующего на договоре тарифа с пересекающейся датой, 1 - включен
check.double.tariff=0
# Разрешение платежей и расходов будущим числом
allow.future.payment=0
allow.future.charge=0
# Разрешение платежей и расходов для закрытых договоров
allow.closed.payment=0
allow.closed.charge=0
# Что выводить в поле "сальдо" монитора статуса, 1 - сальдо, 2 - исх. остаток
contract.status.monitor.saldo.show.mode=1
# Запрет установки договору лимита без указания периода в случае наличия заданий на автоматическое изменение лимита, 1 - включение запрета
reject.limit.update=0
# Отключение учёта при активации тарифной опции уже активированных опций
#tariffOption.dontCheckOnActivateAlreadyActivated=1
#
#-------------------------------------
# Статусы договора
#-------------------------------------
# Статусы договора, коды и обозначения
contract.status.list=0:Активен;1:В отключении;2:Отключен;3:Закрыт;4:Приостановлен;5:В подключении
# Статусы договора, запрещённые к ручной установке
contract.status.no.manual.set=1,5
# Не используемые статусы договора (не будут отображаться в списках, но останутся в логах изменений)
contract.status.deprecated=
# При смене статуса договора смена статусов его независимых субдоговоров, 1 - включение
independ.subcontract.status.change=0
#
#--------------------------------------
# Статусы договора, кредитовые договора
#--------------------------------------
# Статус договора, при котором кредитовый договор считается активным
credit.contract.active.status=0
# Cтатусы договора, из которых кредитовый договор может быть переведён в активный статус по платежу
# в случае, если сальдо станет положительным
credit.contract.open.by.payment.status=2,3
# Cтатусы договора, которые перекрываются в будущем активным статусом, при открытии кредитового договора
credit.contract.override.future.to.active.status=2
# Не переводить статус договора в активный по платежу, тоже что пустой список credit.contract.open.by.payment.status
#do.not.open.contract.on.payment=1
# Перечень кодов групп договоров через запятую, которые не активируются по платежу
#do.not.open.groups.on.payment=
# 
#-------------------------------------
# Проверки закрытого периода 
#-------------------------------------
# Проверка закрытого периода при операциях, 1 - включить
closed.date.enabled=1
# Перечисления кодов групп пользователей, для  который проверка закрытого периода отключена
#closed.date.groups.id=1,2,3
# Выборочное отключение проверки закрытого периода
# (договор) удаление расхода 
#closed.date.disabled.ActionDeleteContractCharge=1
# (договор) удаление платежа
#closed.date.disabled.ActionDeleteContractPayment=1
# (договор) удаление Услуги
#closed.date.disabled.ActionDeleteContractService=1
# (договор) удаление группы тарифов
#closed.date.disabled.ActionDeleteContractTariffGroup=1
# (договор) удаление тарифного плана
#closed.date.disabled.ActionDeleteContractTariffPlan=1
# (договор) изменение расхода 
#closed.date.disabled.ActionUpdateContractCharge=1
# (договор) изменение Даты открытия
#closed.date.disabled.ActionUpdateContractDate1=1
# (договор) изменение Даты закрытия
#closed.date.disabled.ActionUpdateContractDate2=1
# (договор) изменение платежа
#closed.date.disabled.ActionUpdateContractPayment=1
# (договор) изменение Услуги
#closed.date.disabled.ActionUpdateContractService=1
# (договор) изменение группы тарифов
#closed.date.disabled.ActionUpdateContractTariffGroup=1
# (договор) изменение тарифного плана
#closed.date.disabled.ActionUpdateContractTariffPlan=1
# (договор) изменение периода обьектов
#closed.date.disabled.ActionObjectUpdate=1
# (договор) изменение статуса договора
#closed.date.disabled.ActionContractStatusChange=1
#
#----------------------------------------
# Планировщик заданий 
#----------------------------------------
# Количество одновременных потоков для выполнения периодических заданий по расписанию
scheduler.periodic.thread.count=5
# Количество одновременных потоков для выполнения асинхронных задач (переобсчёты)
scheduler.nonperiodic.thread.count=5
#
#--------------------------------------
# Загрузчик логов
#--------------------------------------
# Автоматическая генерация заданий на обработку логов
loader.add.process=1
#
#----------------------------------------
# Расширение функциональности 
#----------------------------------------
# Логирование вызовов функций скриптов поведения в договорах (1-логировать, 0-нет).
# Логируются выводы print, error и ошибки; после установки перезапустить BGBillingServer
log.function.process=1
#
#----------------------------------------
# Расширение функциональности - динамический код 
#----------------------------------------
# Кодировка файлов динамического кода (UTF-8 предпочтительно, по умолчанию)
dynamic.src.encoding=UTF-8
# Каталог размещения динамического кода относительно BGBillingServer
dynamic.src.dir=dyn
#
#----------------------------------------
# BGSecure 
#----------------------------------------
# Проверка прав, 0 - не проверять
bgsecure.check=1
# Логирование действий в журнале событий, 0 - не логировать
bgsecure.log=1
#
#----------------------------------------
# Почтовая подсистема 
#----------------------------------------
mail.smtp.host=bill.ru
mail.from.email=bill@bill.ru
mail.from.name=BGBilling Server
mail.to.email=bill@bill.ru
mail.to.name=bill@bill.ru
mail.encoding=UTF-8
# Параметры SMTP-авторизации
#mail.smtp.user=
#mail.smtp.pswd=
#
#----------------------------------------
# Система алармов - экстренных оповещений 
#----------------------------------------
# На какой адрес высылать оповещения, указать обязательно!
alarm.mail=
#
#----------------------------------------
# Web-интерфейс клиента 
#----------------------------------------
# Режим выдачи страниц: xml, либо html - сборка страниц браузером, либо на сервере
web.mode=html
# Разграничение доступа в личный кабинет:
# 1 - вошедший через логин субдоговора видит всю иерархию договоров (по умолчанию)
# 2 - вошедший через логин субдоговора видит только свой договор
#web.sub.contract.auth.mode=1
# Сохранять все ошибки входа (даже если не идентифицирован договор)
#web.error.all=1
# В режиме xml по этому пути браузер будет получать xsl
# Адрес должен быть доступен отовсюду
web.xslt=http://127.0.0.1:8080/bgbilling/xsl/
# В режиме xml при обращении через порт https по этому пути браузер будет получать xsl
# Адрес должен быть доступен отовсюду
web.xslt.https=https://127.0.0.1:8443/bgbilling/xsl/
# Добавление в XML на странице статистике детальной информации по договору - 1
web.add.contract=0
# Страница куда пересылать при выходе с Web-статистики
web.exit.redirect=about:blank
# Логирование Web-запросов пользователя (Web-интерфейс)
webquery.log=0
# Максимальный размер в байтах прикрепляемого файла в Web 
multipart.max.post.size=1048576
# Настройка страниц ошибок сервера по ошибкам (можно указывать различные коды ошибок)
server.error.404=/error/error404.html
server.error.403=/error/error403.html
#
#----------------------------------------
# Web-интерфейс, доступ 
#----------------------------------------
# MD5-хэш универсального пароля к Web-статистике, хэш можно получить в "Утилиты => Вычисление Digest"
#web.admin.password=21232F297A57A5A743894A0E4A801FC3
# Режим авторизации для доступа к Web-статистике код модуля:режим;код модуля 1:режим 
# модуль 0 - ядро
# режим 0 - не разрешена, 1 - по номеру договора, 2 - по текстовому параметру договора
web.auth.modes=0:1
# Максимально количество запросов для договора на сервер статистики в день, 0 - не ограничено
web.max.day.request.count=0
# Длина пароля договора для доступа к статистике
password.length.min=5
password.length.max=10
# Длина автоматически генерируемого пароля
password.length.auto=6
# Допустимые в пароле символы
password.chars=1234567890
#
#----------------------------------------
# Web-интерфейс, доступ, защита от подбора пароля
#----------------------------------------
# Максимальное количество неудачных попыток авторизации подряд
logon.counter.max=20
# Базовый интервал времени в секундах между неудачными попытками авторизации
logon.timeout.period=0
# Время блокировки в секундах после исчерпания количества попыток авторизации
logon.timeout.lock=21600
# Размер кэша паролей
logon.lock.cache.size=100
# Время устаревания записи в кэше паролей в секундах
logon.lock.cache.expired=600
# Алгоритм увеличения времени между попытками (+ или ^)
logon.timeout.action=+
#
#-----------------------------------------
# Web-интерфейс, доступ, восстановление пароля 
#-----------------------------------------
# Код текстового параметра, содержащий E-Mail, на который будет высылаться письмо по восстановлению пароля
contract.password.forgot.email.param.id=<числовой код параметра>
# В течение скольке часов после высылки письма можно войти на статистику по ссылке в письме
contract.password.forgot.expire.hour=24
# Ссылка на страницу статистики в письме с восстановлением пароля
contract.password.forgot.link=http://localhost:8080/bgbilling/webexecuter?action=ChangePassword&mid=contract
# Тема письма
contract.password.forgot.email.subject=Восстановление пароля
# Текст письма
contract.password.forgot.email.body=Для восстановления пароля к серверу статистики по договору {contract} - перейдите по ссылке ниже (в течении {hour} часов) и смените пароль.
# набоН символов одноразового пароля
contract.password.forgot.char.array=1234567890QWERTYUIOPLKJHGFDSAZXCVBNMqwertyuioplkjhgfdsazxcvbnm
#
#-----------------------------------------
# Web-интерфейс, временное понижение лимита 
#-----------------------------------------
# сообщения при изменении лимита
limit.max.current.msg=Вы не можете в данный момент понизить лимит. Превышено максимально количество не погашенных и/или частично погашенных понижений
limit.max.nopayed.msg=Превышено максимально количество просроченных понижений. Возможность понижения лимита заблокирована
#

Значение большинства параметров пояснены в комментариях, либо присутствует ссылка на главу с более подробным описанием подсистемы.

Если вы не знаете, что ввести в качестве параметра в конфигурацию, возьмите этот параметр из примера, приведённого выше. После сохранения конфигурации выберите строку с ней в таблице и нажмите Установить.

В поле Вид и поведение вы можете изменить текущую тему оформления клиента.

Внимание

Установка темы оформления отличной от Metal может привести к проблемам с отрисовкой. Смена темы оформления производится пользователем на его страх и риск, нарушение в отрисовке клиента не считается ошибкой ПО.

10.2. Почтовая подсистема

Необходимо обязательно настроить опции почты:

# Настройки почты
mail.smtp.host=bill.ru
mail.from.email=bill@bill.ru
mail.from.name=BGBilling Server
mail.to.email=bill@bill.ru
mail.to.name=bill@bill.ru
mail.encoding=UTF-8
# Имя хоста, отправляемое в команде EHLOW SMTP-серверу, если необходимо отличное от имени хоста, где запущено приложение биллинга.
# Параметр общий для для всех приложений биллинга, отправляющих почту, он может быть также указан в скрипте запуска приложения ключём -Dmail.smtp.localhost=<host>
# либо в .properties файле приложения
#mail.smtp.localhost=<имя хоста>
# Включение отладки SMTP-обмена в .out лог, 1 - включить, 0 - выключить
#mail.debug=1

Данные настройки используются для отправки почтовых сообщений всеми приложениями биллинга. Настройка почтовой подсистемы очень важна, т.к. иначе не будет работать система экстренного оповещения "алармы". Для проверки корректности настройки подсистемы произведите модификации конфигурации сервера биллинга и попытайтесь отправить отчёт по балансу в договоре. Для этого откройте любой созданный договор, выберите в дереве узел Баланс и нажмите кнопку с изображением конверта над таблицей.

В mail.smtp.host укажите ваш почтовый сервер, адрес и имя, подставляемые в поля ОТ письма (mail.from.email, mail.from.name). Также укажите адрес и имя администратора (mail.to.email, mail.to.name). В кодировке можете указать windows-1251, либо UTF-8, либо KOI8-R на ваш выбор.

Если SMTP-сервер требует авторизации, логин и пароль указываются в параметрах mail.smtp.user, mail.smtp.pswd.

Для поддержки отправки почты через SSL-соединение (например, smtp.gmail.com) добавьте следующие настройки (SMTP порт 465).

mail.properties.mail.smtp.socketFactory.class=javax.net.ssl.SSLSocketFactory
mail.properties.mail.smtp.socketFactory.fallback=false
mail.properties.mail.smtp.quitwait=false
mail.properties.mail.smtp.port=465
mail.properties.mail.smtp.socketFactory.port=465

10.3. Система оповещения

В опции alarm.mail укажите почтовый ящик для отправки экстренных оповещений о нештатной ситуации в биллинге (потеря связи с БД, недостаток памяти и т.п.). При наступлении нештатной ситуации приложение биллинга вышлет письмо со следующей темой: [<имя приложения>] <название ошибки>, где:

<имя приложения> - название процесса биллинга, уникально для каждого процесса биллинга, может быть переопределено передачей ключа -Dapp.name=<новое имя> в скрипте старта процесса (.sh, .bat);
<название ошибки> - краткое описание ошибки.

Например: "[BGBillingServer] Достигнут лимит одновременных подключений к Master базе". Если, например, у вас установлено несколько серверов биллинга и необходимо получение алармов на один ящик, то вы можете скорректировать скрипт server.sh следующим образом (имя приложения изменено на BGBillingServer2):

if [ "$1" = "start" ]; then
   #starting
   nohup  ${JAVA_HOME}/bin/java -Dapp.name=BGBillingServer2 ....
else

Аналогично может быть скорректировано имя любого приложения. В теле письма содержится идентификатор проблемы, время регистрации и краткое описание, например:

ID события: db.master.connection.limit.over
Время регистрации события: 10.03.2009 16:12:01

Это может привести к снижению времени отклика системы.
Необходимо предпринять меры по ускорению работы Master базы данных.

Connections pool to Master status Idle: 0; Active: 4; maxActive: 4; maxIdle: 4

Для каждого типа оповещения определен минимальный интервал между отправками писем. Интервал существует для избежания большого потока писем одного содержания. Он может быть изменён установкой опции конфигурации сервера биллинга alarm.min.interval.<key>=<seconds>, где:

<key> - идентификатор события, например db.master.connection.limit.over;
<seconds> - минимальное время в секундах между отправками писем по этому типу события.

Например:

alarm.min.interval.db.slave.connect.error=240

Хоть это и не рекомендуется, но можно отказаться от получения каких-либо оповещений. Для этого в конфигурации перечислить ключи (ID) оповещений через запятую. Например:

# Алармы, которые надо игнорировать. Ключи через запятую.
alarm.disabled=bad.java

Также существует возможность отправки оповещений не только на почту, но и в log-файл. Это достигается путем добавления в конфигурацию сервера опции

#Алармы, которые направляются в log. Необходимо указать список ключей через запятую или символ "*", чтобы ВСЕ алармы писались в лог.
alarm.send.to.log=<keys>

Log-файл располагается в стандартном каталоге логов сервера и называется *.alarm.log. Также стоит отметить следующее: если ключ аларма указан и в опции alarm.disabled, и в alarm.send.to.log, то на почту оповещение не придет, но в лог запишется; если ключ указан только в alarm.send.to.log, то оповещение придет и на почту, и в log-файл; если же ключ указан в alarm.disabled, но его нет в alarm.send.to.log, то оповещение будет полностью проигнорировано.

10.4. Закрытый период

В меню настройки сервера (пункт меню Сервис=>Настройка=>Конфигурация) также существует возможность указания закрытого периода для сущностей ядра и модулей системы. Проверка закрытого периода работает только при установленной опции конфигурации сервера биллинга closed.date.enabled=1. Также имеется возможность выборочного отключения проверки закрытого периода. Флаги отключения см. здесь, и в описании конфигурации модулей.

Назначение закрытого периода в том, чтобы не допускать изменения или удаления сущностей в периоде, уже закрытом для изменений в балансе. Для закрытого периода устанавливается его правая граница. Логика работы проверки на закрытый период для изменения сущностей, имеющих период работы (две даты, например, тарифный план), следующая:

  • если и левая, и правая границы периода сущности лежат левее закрытой даты, то невозможно любое изменение этих сущностей;

  • если левая граница периода сущности лежит в закрытом периода, а правая нет (либо не существует, либо лежит правее закрытой даты), то возможно изменение параметров данной сущности, за исключением изменения левой границы ее периода (т.к. она лежит в закрытом периоде) и установки правой границы внутри закрытого периода;

  • если обе границы периода сущности лежат правее закрытой даты, то возможно любое изменение этой сущности за исключением тех, которые приводят к пересечению периода сущности с закрытым периодом.

Для сущностей с одной датой (например, приход) логика работы проверки на закрытый период для изменения следующая:

  • если дата сущности лежит внутри закрытого периода, то невозможно любое изменение этой сущности;

  • если дата сущности лежит вне закрытого периода, то возможно любое изменение этой сущности, за исключением установки ее даты внутри закрытого периода.

Логика проверки на закрытый период для удаления сущностей едина для обоих типов (для сущностей с двумя датами в проверке участвует только левая граница ее периода, т.к. для проверки на пересечение этого достаточно):

  • если дата сущности лежит внутри закрытого периода, то удаление ее невозможно;

  • если дата сущности лежит вне закрытого периода, то ее удаление возможно.

По умолчанию в системе присутствует только один закрытый период "Основной". При необходимости, возможно определение в конфигурации сервера биллинга дополнительных периодов следующим образом:

closed.date.types=<id1>:<title1>;<id2>:<title2>..

Где:

<idN> - уникальный код периода, целое число больше 1;
<titleN> - название периода.

Например:

closed.date.types=2:Период для платежей;3:Период для расходов

Для привязки какой-либо проверки периода к иному от основного необходимо указать в конфигурации ядра, либо модуля:

closed.date.type.<key>=<typeId>

Где:

<key> - ключ проверки, тот же, что используется для её отключения;
<typeId> - код периода.

Например, привязка проверки периодов при правке платежей и расходов к периоду с кодом 2:

closed.date.type.ActionUpdateContractPayment=2
closed.date.type.ActionDeleteContractPayment=2

11. Модули

Модули необходимы для расширения функциональности системы в основном для тарификации различных услуг. В этой главе полагается, что ваш сервер биллинга установлен в C:\BGBillingServer на ОС Windows. Если вы установили его в другое место, используйте ваши пути.

Установка модуля производится инсталлятором, который расположен в каталоге BGBillingServer. Для запуска положите zip-файл модуля рядом с инсталлятором и запустите

# Linux
./bg_installer.sh {имя файла с архивом}
# Windows
bg_installer.bat {имя файла с архивом}

Если инсталляция прошла успешно, будет выведено сообщение (например):

Module dialup version 3.5 was successfull installed!

Для установки обновления того же модуля (версии пакетов совпадают) необходимо выполнить:

#Linux
./bg_installer.sh {имя файла с архивом}!
#Windows
bg_installer.bat {имя файла с архивом}!

Символ "!" после имени пакета указывает инсталлятору, что установка необходима даже, если такой модуль такой версии уже стоит.

После того, как установили модуль, необходимо перезапустить сервер биллинга. После этого должен быть обновлён клиент. Для этого запустите его и подсоединитесь к обновлённому серверу биллинга.

При подключении установите в окошке логина галочку загружать обновления с этого сервера. Либо произведите вход на сервер, а после вызовите пункт меню Сервис=>Настройка=>Принудительное обновление клиента.

Если все прошло успешно, будет выведено окошко с сообщением.

Данное сообщение означает, что код клиентской части, необходимый для работы с модулем, скопирован с сервера. Иначе говоря, уже есть код модуля, но нет обособленной единицы (экземпляра) модуля со своими данными. Для того чтобы её создать, следует запустить Модули=>Редактор модулей и услуг.

Слева расположена таблица созданных экземпляров модулей: код экземпляра, его произвольное название и базовый модуль. Базовый модуль - ничто иное, как программный код, осуществляющий поддержку функционала модуля. А сам экземпляр - это совокупность данных в базе с уникальным кодом.

От одного базового модуля можно породить неограниченное количество экземпляров модулей. Например, можно сделать два экземпляра от базового модуля DialUp (Коммутируемые соединения): DialUp и VPN.

Каждому из них будут соответствовать свои таблицы в базе, свои списки логинов, NASов и т.п. Код, обрабатывающий все эти данные на сервере, будет общим. Каждый из экземпляров будет обслуживать собственный RADIUS-сервер.

После создания экземпляра модуля ему присваивается уникальный код, далее в руководстве для краткости называется Код модуля и используется во многих конфигурациях. Экземпляр модуля в дальнейшем руководстве также часто называется просто модуль, необходимо понимать разницу и выяснять нужное значение по контексту.

Для создания нового экземпляра модуля нажмите кнопку Новый элемент на общей панели инструментов, для редактирования - кнопка Редактировать, либо двойной клик по строке таблицы. Изменить можно только название экземпляра.

Удаление экземпляра модуля: кнопка Удалить. Вам может понадобиться эта кнопка после истечения тестовой лицензии на какой-либо модуль, решение о приобретении которого принято не было.

Внимание

Удаляя модуль, вы удалите и все связанные с ним данные.

Справа расположены услуги, существующие в модуле.

Услуга - это способ разделения наработки, а также возможность активации тех или иных сервисов в некоторых модуля путём добавления Разрешённых услуг договора. Каждой услуге также соответствует уникальный код и он также часто используется в конфигурациях как Код услуги.

Для редактирования списка услуг экземпляра модуля выберите строку с экземпляром и воспользуйтесь тремя кнопками над таблицей с услугами. Услуги также настраиваются по признаку используемости. Неиспользуемые услуги по желанию не будут отображаться в списке услуг, доступных для добавления к договору.

После создания экземпляра модуля созданные экземпляры должны появиться в меню Модули.

При открытии соответствующего модулю пункта подменю открывается вкладка с настройками модуля. Для каждого модуля набор вкладок разный. Однако в большинстве модулей присутствует вкладка Конфигурация модуля, её редактирование аналогично Конфигурации сервера биллинга.

Здесь задаются настройки, специфичные для данного модуля и его агентов (например, RADIUS-сервера модуля DialUp). Конфигурация сохраняется в БД и поэтому доступна всем серверным компонентам биллинговой системы.

Существуют три точки "выхода" модуля в графическом интерфейсе клиента:

1. Пункт меню Модули, описан выше;

2. Договор абонента, узел дерева Модули;

3. Вкладка Отчёты.

Для примера создадим договор (New Contract) с шаблоном по умолчанию (более подробно о договорах, их свойствах и шаблонах см. далее). Для этого нажмём кнопку Новый договор.. на панели инструментов (самая левая кнопка), далее выберем шаблон По умолчанию и текущую дату.

Должен открыться созданный договор New contract.

В дальнейшем, если вы его случайно закроете, вы можете найти его, нажав вторую кнопку на панели инструментов Открыть договор.. и нажав в ней кнопку >>>. Более подробно о поиске договоров написано далее.

Для подключения к договору модуля необходимо перейти на пункт дерева Модули, далее нажать Новый элемент, выбрать в открывшемся редакторе требуемый экземпляр модуля, нажать OK.

В результате в дереве появится ветка со свойствами модуля для конкретного договора. При её открытии откроется специфичный для модуля редактор. На снимке экрана это редактор логинов DialUp-модуля.

Вкладка Разрешённые услуги присутствует не для всех модулей, её назначение различно и описывается в документации конкретного модуля.

Также на вкладке Отчёт договора отобразится панель оперативных отчётов данного модуля.

Аналогично в договор можно добавить другие модули.

12. Плагины

Установка плагинов не отличается от установки модулей, также используется утилита bg_installer (см. предыдущую секцию документации). После инсталляции плагина перезапустите сервер биллинга и зайдите в клиенте в меню Плагины=>Настройка плагинов.

Для активации плагина необходимо дважды кликнуть по строке таблицы, поставить в редакторе галочку включён и нажать OK.Здесь же вносится конфигурация плагина, конкретные ключи и значения необходимо смотреть в документации конкретного плагина. После активации плагина сервер начинает проверять лицензию на него, в случае отсутствия, либо просроченной лицензии плагин необходимо отключить.

После активации плагина необходимо переподключиться клиентом к серверу биллинга. В зависимости от конкретного плагина он может "проявляться" в различных точках клиента. В этом отличие плагинов от модулей, которые появляются только в определённых 3х точках "входа" в интерфейс.

Например, плагин CRM добавляет пункт меню Плагины=>CRM и вкладку в договоре CRM.

13. Установка обновлений биллинга

По мере обнаружения ошибок в текущей версии программы выпускаются обновления в виде новых билдов (сборок). Каждый новый билд модуля сопровождается комментарием к сделанным исправлениям. Комментарии доступны на странице загрузки продукта. Также ведётся RSS-лента обновлений.

Периодически следует сверять текущие установленные билды модулей и плагинов с доступными на сайте. Для получения информации по версиям и билдам компонентов биллинга воспользуйтесь меню Справка=>О программе.

В верхней области отображаются версии и билды клиента и сервера. Обновление клиента и сервера доступны на сайте единым пакетом. Ниже перечислены установленные в системе модули и плагины, их версии и билды. Для установки модулей и плагинов используется утилита bg_installer.sh (.bat).

./bg_installer.sh <имя_файла_с_модулем>

Для Linux.

bg_installer.bat <имя_файла_с_модулем>

Для Windows.

Файл с модулем должен быть загружен и располагаться в каталоге BGBillingServer.

При установке обновлений следует останавливать процесс сервера биллинга, планировщика и загрузчика логов и запускать их после установки пакетов.

Для установки обновления пакет модуля, либо плагина необходимо установить повторно. Поддерживается автоматическое обновление с FTP-сервера ftp://bgbilling.ru. Для обновления системы остановите сервер биллинга, планировщик и загрузчик логов а затем выполните команду:

./bg_installer.sh update

Для Linux платформы.

bg_installer.bat update

Для Win платформы.

Инсталлятор проверит наличие обновлений и предложит их установить выбрав нажав клавишу y.

[bill@bill-reg BGBillingServer]$ ./bg_installer.sh update
Update starting..
Update from ftp://bgbilling.ru/pub/bgbilling
Server version is 4.4
Changing dir to /pub/bgbilling/4.4
Checking updates for ru.bitel.bgbilling.plugins.crm..
Found update for crm build 50 packet crm_4.4_52.zip updating to build 52
Checking updates for ru.bitel.bgbilling.plugins.documents..
Checking updates for card..
Checking updates for dialup..
Checking updates for email..
Checking updates for ipn..
Checking updates for npay..
Checking updates for reports..
Checking updates for voiceip..
Checking updates for bill..
Checking updates for gorod..
Checking updates for server..
Found update for BGBillingServer build 102 packet update_4.4.zip updating to build 104
Checking updates for client..
Install 2 updates (y/n):

Возможно установить только все обновления сразу. Также необходимо останавливать сервер, планировщик и загрузчик логов до обновления и стартовать после.

Внимание

Не забывайте делать резервную копию каталога BGBillingServer при установке обновлений. Обновление перетирает все XSLT-шаблоны и многие другие файлы, заменяя их стандартными из пакета.

Для Linux также есть скрипт update.sh, который самостоятельно останавливает службы, запускает процесс обновления и стартует службы после. Кроме того, он сохраняет лог процесса обновления в файл.

Для предотвращения перетирания файла при обновлении вы можете перед его модификацией создать копию с именем <file_name>.orig (например, style.css.orig). При установке пакета инсталлятор будет проверять перед записью каждого файла наличие файла с таким же именем в текущей установке. Если файл существует, но отличается от того, что в пакете, предпринимается попытка найти файл <file_name>.orig .

Если оригинальный файл существует и не отличается от файла из пакета, то он не будет перезаписан, система сообщит: File doesn't changed <filePath>. Если и оригинальный файл не совпадает со вновь предлагаемым, файл будет записан.

Перечень перезаписанных файлов сообщается после завершения процедуры установки, либо обновления после фразы REPLACED FILES:. Вы должны вновь внести в данные файлы требуемые корректировки и снова создать .orig-копию файла.

Обновление клиента происходит автоматически при последующем подключении к серверу биллинга и установленной опции Загружать обновления с данного сервера.

При выходе новых версий биллинга предоставляется инструкция по переходу на новую версию ПО, далее в пределах версии обновление производится по описанному выше алгоритму.

В системе обновления биллинга работает механизм предотвращения повторного выполнения SQL-запросов обновления базы данных, что значительно ускоряет обновление системы. Выполненные SQL-запросы кэшируются и хранятся в базе данных биллинга. В случае, если по какой-либо причине необходимо повторное выполнение SQL-запросов при обновлении модуля (или ядра), то необходимо запустить

./bg_installer.sh killhash <entity_id>

для Linux или

bg_installer.bat killhash <entity_id>

для Windows,

где <entity_id> - код сущности, для которой необходимо уничтожить кэш SQL-запросов (для ядра = 0; для плагина = код плагина из Плагины => Настройки плагинов; для экземпляра модуля = m<mid>, где <mid> - код экземпляра модуля из Модули => Редактор модулей и услуг).

Например:

./bg_installer.sh killhash m10

13.1. Обновление других серверных приложений

Все серверные приложения получают обновления от сервера биллинга посредством MQ-сообщений. Единый набор серверных библиотек биллинга на всех приложениях обеспечивает унифицированную среду для работы скриптов и расширений. Для обновления приложения используется скрипт update.sh (.bat). Вот примерный вывод скрипта при обновлении, в момент обновления BGBillingServer должен быть запущен.

[root@bgb BGInetAccounting]# ./update.sh
Starting libraries updating. Requesting to BGBillingServer lib info.
 05-19/18:47:40  INFO [main] DefaultServerSetup - Binding javax.jms.ConnectionFactory[org.apache.activemq.ActiveMQConnectionFactory@1e3118a] to java:comp/env/mq/connectionFactory
mq 05-19/18:47:40  INFO [EventProcessor-init] EventProcessor - Init EventProcessor MQ connection factory...
May 19, 2011 6:47:40 PM org.apache.activemq.transport.failover.FailoverTransport doReconnect
INFO: Successfully connected to tcp://localhost:61616
mq 05-19/18:47:41 DEBUG [main] EventProcessor - Request, timeout 2000 : Event[bitel.billing.server.installer.event.GetLibrariesInfoEvent] timestamp: -1; moduleId: -1; pluginId: -1; cid: -1; scid: -1; userId: -1
Taking inet.jar...
mq 05-19/18:47:41 DEBUG [main] EventProcessor - Request, timeout 0 : Event[bitel.billing.server.installer.event.GetLibraryEvent] timestamp: -1; moduleId: -1; pluginId: -1; cid: -1; scid: -1; userId: -1
OK. Saving to lib.app.update.
Taking kernel.jar...
mq 05-19/18:47:41 DEBUG [main] EventProcessor - Request, timeout 0 : Event[bitel.billing.server.installer.event.GetLibraryEvent] timestamp: -1; moduleId: -1; pluginId: -1; cid: -1; scid: -1; userId: -1
OK. Saving to lib.app.update.
Update finished. Restart application.
05-19/18:47:45  INFO [Thread-3] EventProcessor - Shutdown EventProcessor...

После обновления новые библиотеки сохраняются в каталог lib.app.update и применяются только при перезапуске приложения.

Следите, чтобы все ваши серверные приложения были обновлены!

Замечание

Данная схема распространяется только на серверные приложения, связанные с ядром через JMS. Изолированные приложения обновляются отдельно. Такие приложения не содержат конфигурации доступа к MQ-серверу в конфигурационном файле, у них нет скрипта update и каталога lib.app.update. К таким приложениям относятся, например, DHCP-сервер модуля IPN, CashCheck-сервер.

13.2. Снапшоты

Замечание

В данный момент есть версия скрипта только для ОС Linux! Для Windows выполняйте требования по резервному копированию перед обновлением!

Для сохранения текущего состояния библиотек биллинга, каталога webroot, данных по установленным модулям и плагинам в БД с BGBilling поставляется скрипт snapshot.sh. Для создания снапшота вызовите перед обновлением:

./snapshot.sh create

Снапшоты сохраняются архивами в каталог BGBillingServer/snapshots. Для восстановления снапшота команда:

./shapshot.sh restore <FILE>

, где <FILE> - имя файла со снапшотом.

Восстановив сервер из снапшота необходимо обновить с него все другие серверные приложения. Функционал скрипта реализован исключительно сторонними приложениями и может быть легко скорректирован.

14. Установка лицензии биллинга

Для корректной работы BGBilling необходимо наличии лицензии . Лицензия представляет собой файл lic.properties с набором текстовых строк, который выдаётся при покупке BGBilling. Лицензия включает в себя описание разрешенных к использованию модулей и плагинов, количества договоров и период действия.

Полученную лицензию необходимо поместить в каталог BGBillingServer/data заменив существующий lic.properties, после чего перезапустить сервер биллинга. Загруженный с сайта биллинг содержит тестовую лицензию. Текущую лицензию можно просмотреть в индикаторе лицензии.

Замечание

До 4.5 версии включительно информация о лицензии размещалась в файле data.properties. Для сохранения обратной совместимости, данный файл также просматривается, если не был обнаружен lic.properties.

Для того, чтобы получать оповещения о том, что лицензии скоро заканчиваются, в конфигурации сервера можно настроить такие параметры:

# 1- проверка лицензий включена, 0 - выключена(по умолчанию) 
need.lic.alarm=1
# Предупреждать, если  свободных лицензий осталоась меньше, чем X
lic.alarm.contract.limit=X
# Предупреждать, если  дней до конца действия лицензии осталось меньше, чем Y
lic.alarm.days.limit=Y
# Какие модули проверять. Если опция не указана , то проверяются все модули. 
lic.alarm.modules=ipn,dilaup

15. Настройка SSL между сервером и клиентом

По умолчанию обмен между клиентом и сервером биллинга, а также между Web-браузером клиента и сервером биллинга, производится по протоколу HTTP. В дополнение к нему вы можете настроить HTTPS-режим соединений, позволяющий безопасно подключаться к серверу биллинга из-за пределов вашей сети клиентом, либо получать безопасный доступ к статистике вашим абонентам.

Замечание

Вы можете пропустить эту главу при первичном знакомстве с биллингом

Для работы по HTTPS требуется серверный сертификат - пара private key и public key, public key обернут сертификатом. Сертификат и private key должны находится в хранилище сертификатов - .keystore.

Работа сертификатов основывается на паре асинхронных ключей. Необходимо создать их, для этого воспользуемся утилитой keytool, которая идет вместе с JRE/JDK:

keytool -keystore .keystore -alias bgbilling -genkey -keyalg RSA -dname "cn=bill.provider.ru, email=email@provider.ru,ou=Provider Billing, o=Provider, c=RU" -validity 1001

Параметр -validity указывает сколько дней будет действителен сертификат.

Утилита попросит ввести пароль для хранилища и пароль для закрытого ключа (private key).

Оба пароля должны совпадать и быть прописаны в конфиге сервера (по умолчанию биллинг пытается использовать значение 'bgbilling'):

keystore.password=bgbilling

cn - common name - имя сервера. Пользователь заходит на https://bill.provider.ru/, сервер возращает сертификат, браузер проверяет имя на совпадение - если не совпадает, то выводится предупреждение.

ou - organization unit, o - organization, c - country

После работы утилиты появится файл .keystore, в нем в алиасе bgbilling - закрытый ключ и сертификат. Закрытый ключ нельзя передавать никому.

Просмотреть хранилище можно командой:

keytool -keystore .keystore -list -rfc

Экспортировать сертификат, чтобы удаленная сторона могла добавить его в доверенные:

keytool -keystore .keystore -alias bgbilling -exportcert -file bgbilling.cer

В данный момент хранилище уже готово для работы, но текущий сертификат подписан самим собой, т.е. не подписан доверенным сертификатом - таким образом, когда клиент зайдет на https://bill.provider.ru/ - ему выведется предупреждение, например, "К сертификату нет доверия, так как он является самоподписанным." и предложат уйти с сайта, продолжить работать или добавить сертификат в доверенные и продолжить работать.

Если вы хотите, чтобы браузер сразу доверял сертификату, необходимо его подписать одним из Certification Authority (CA), например VeriSign, Inc. Для этого создаем запрос на подпись сертификата - Certificate Signing Request (CSR).

keytool -keystore .keystore -alias bgbilling -certreq -file bgbilling.csr

Созданный запрос нужно отправить CA, в ответ вы получите серфтикат, подписанный им (или цепь сертификатов).

Сначала необходимо импортировать сертификат CA в доверенные (или верхний из цепи сертификатов, например ROOT), т.к. при импорте ответа проверяется, что ответ подписан доверенным сертификатом.

keytool -keystore .keystore -alias verisign -importcert -file verisign.cer

Далее импортируем ответ, он заменит наш самоподписанный сертификат:

keytool -keystore .keystore -alias bgbilling -importcert -trustcacerts -file response.cer

Более подробную информацию о работе keytool можно получить здесь: http://java.sun.com/javase/6/docs/technotes/tools/windows/keytool.html

Скопируйте файл .keystore в каталог BGBillingServer. В файле data.properties сервера укажите:

connector.https=*:8443

и перезапустите его. Если нужно поднять биллинг на конкретном ip (интерфейсе) , то вместо "*" можно указать его, например "81.30.30.30:8443".

В результате сервер начинает слушать на 2х портах. Не стоит убирать http.port, т.к. сервер должен обращаться к самому себе за некоторыми ресурсами (XSL-файлы) по этому протоколу.

При этом клиенты для просмотра Web-статистики также могут использовать 2 вида протоколов HTTP и HTTPS. Для обращения через безопасное соединение необходимо набирать https://<IP адрес сервера биллинга>:8443/bgbilling/webexecuter.

Редактируем файл client.properties в клиенте

db.server.0.url=http://127.0.0.1:8080/bgbilling/executer 

меняем на

db.server.0.url=https://bill.provider.ru:8443/bgbilling/executer 

Руководство по интеграция существующего сертификата и приватного ключа SSL в хранилище keystore вы можете найти в WiKi.

16. Настройка планировщика

Специально для выполнения периодических процессов (снятие абонплат, очистка таблиц, восстановление лимитов на договоре и т. д.) в системе BGBilling предусмотрен планировщик задач, выполняющий задачи в заданные интервалы времени.

Для просмотра/добавления/редактирования/удаления задач зайдите в Сервис=>Администрирование=>Планировщик заданий. Перед вами откроется окно управления планировщиком с фильтруемым списком задач. Фильтрация осуществляется по модулям.

Для создания/редактирования/удаления задач воспользуйтесь стандартной панелью инструментов клиента биллинга. При создании/редактировании задачи снизу появится редактор, представленный на рисунке ниже.

Максимальная частота запуска заданий планировщиком - один раз в минуту. Данная частота устанавливается, если во всех полях Время запуска будет поставлена *. Т.е. следует читать так: "любая минута,любой час, любой день месяца, любой день недели, любой месяц".

Если столь высокая частота не требуется, можно уточнить параметры. Например, запуск задачи один раз в месяц 1-го числа в ОО:10 можно задать установкой Дни месяца в 1, Часы в 0, Минуты в 10. При необходимости нескольких значений временных фильтров можно указывать через запятую. Для кратных количеств можно указывать строки вида */n, где n - кратность. Например, */8 для часов установит часы в строку вида 0,8,16. Также можно указывать диапазоны чисел через '-'. Например: 8-16.

Параметр Приоритет показывает приоритет потока, который будет выполнять задачу. Без особой необходимости его не следует менять. Не забудьте поставить состояние Включено. Все задачи сгруппированы по модулям, к которым относятся. Для начала нужно выбрать модуль из выпадающего списка Модуль, затем задачу этого модуля из соответствующего выпадающего списка.

Каждая задача может иметь специфические Параметры запуска, которые должны быть введены в поле Параметры запуска в виде <ключ>=<значение>, каждая пара на новой строке. Параметры к каждой отдельной задаче и рекомендации по частоте её запуска даны далее в руководстве к ядру системы и её модулям.

В качестве тренировки вы можете добавить задачу восстановления временно изменённых лимитов, установив параметры задачи, как показано на рисунке.

Для немедленного запуска задачи планировщика используется контекстное меню, доступное по щелчку правой кнопкой мыши на задаче.

Планировщик автоматически перезагружает список периодических заданий при их редактировании в клиенте биллинга.

Кроме плановых заданий планировщик также исполняет все "тяжёлые" задачи биллинга. Например, начисление абонплат, перерасчёты. Это позволяет более оптимально использовать ОЗУ, выделяя большой объем памяти только планировщику. Также можно разгрузить сервер биллинга, вынося планировщик на отдельную машину. Количество "тяжёлых" задач, стоящих в очереди на обработку, также отображается в окне управления планировщиком в нижней части.

Поэтому планировщик должен работать, даже если список его периодических задач пуст. Задания на выполнение начислений и т.п. передаются сервером биллинга планировщику через базу данных. При этом сам планировщик может быть запущен на другой машине.

На вкладке Состояние планировщика можно посмотреть, чем в данный момент занят планировщик заданий. Отображаются как выполняемые периодические задачи, так и вся очередь тяжелых задач с отображением их текущего статуса (выполняется или ожидает выполнения).

Перенос планировщика на другую машину может быть произведен копированием каталога BGBillingServer на другую машину и перенастройкой data.properties с указанием URL к БД MySQL на другой машине. Если планировщик перенесен на другую машину, при каждом обновлении биллинга необходимо копирование папки lib на машину планировщика, а также перезапуск самого планировщика.

Параметры работы планировщика настраиваются в конфигурации сервера.

16.1. Стандартные задачи планировщика

Вместе с ядром биллинга инсталлируются перечисленные ниже задачи. Некоторые из них могут быть настроены сразу, другие связаны с различными подсистемами биллинга и их следует настраивать по мере их настройки и ввода в эксплуатацию.

Восстановление лимитов - возвращение к исходному значению временно изменённых лимитов. Периодичность запуска - 1 раз в день, в 0 часов, 0 минут. Данная задача восстанавливает лимиты после их временного понижения, более подробно о временном понижении лимитов читайте здесь. Задача может быть настроена сразу, параметров не содержит. Также задача восстанавливает лимиты договоров после просроченных "обещанных платежей" - временных понижений лимитов абонентами провайдера.

Удаление старых договоров - очистка базы биллинга от ненужных договоров с помещением их в архив. Периодичность запуска - любая, оптимально - несколько раз в сутки. Данная задача выполняет чистку базы от старых договоров по правилам, указанным в Менеджере договоров. О настройке Менеджера договоров и параметрах запуска задачи описано далее.

Генератор заданий на загрузку логов - запускается раз в час и помещает в базу данных задания для загрузки логов с источников за предыдущий час. Данная задача необходима, если вы установили модуль Phone, хотя возможен и более удобен режим автоматической загрузки логов с вызовом скрипта dataloader с параметрами по мере подготовки логов. Данная задача не обязательна.

Рассылка о понижении лимита - напоминает пользователям с пониженным на время лимитом о необходимости оплаты. При этом анализируется не станет ли текущий баланс клиента ниже лимита после его возвращения на исходное значение. В параметрах задачи должны быть указаны:

# Тема письма
email.subject=Напоминание о задолженности
# Код параметра договора типа E-Mail, содержащего E-Mail, на который отсылается письмо
email.pid=<число>

Данная рассылка должна проводится раз в сутки, оптимальное время запуска - середина дня, для предоставления возможности пользователям пополнения баланса. Текст, содержащийся в письме, варьируется в XSL-шаблоне debt_mail.xsl.

Установка статусов договоров - задача должна запускаться раз в сутки в 0 часов 0 минут и изменять актуальные статусы договоров в соответствии с заданиями.

Валидатор - задача должна запускаться раз в период минимальной загрузки системы (например, 3 часа ночи 0 минут). Выполняет проверку базы биллинга на корректность данных, диагностируя ошибки случайных сбоев. Оповещает о наличии ошибок в журналах, которые не были исправлены. В параметрах задачи должно быть указано:

email=<EMail для отправки отчета>

Задача должна отправлять отчет при любом результате проверки. В данный момент производятся проверки журналов ошибок, таблицы баланса на правильность переноса остатков и совпадения суммарных наработок/платежей/расходов с суммами в соответствующих таблицах. В перспективе задача будет вызывать подсистемы валидации модулей и плагинов.

Генератор событий таймера - выполняет генерацию определенного события с заданной периодичностью. В качестве параметров могут быть указаны:

flag=<флаг таймера>
cid=<список id договоров, для которых нужно выполнить скрипт>
gid=<список id групп, для договоров которых нужно выполнить скрипт>

Флаг позволяет различать текущий таймер от других, позволяя обрабатывать только нужные. При этом задача будет выполняться только для указанных договоров или для договоров из указанных групп договоров.

17. Справочники

17.1. Общие сведения

Система справочников необходима для настройки биллинга. В справочниках задаются значения, которые могут принимать различные параметры договоров. Для редактирования справочников выберите пункт меню Справочники=>Другие. В разделе перечислены назначения справочников ядра, дополнительно в списке могут появится справочники установленных плагинов.

17.2. Адрес - страны, города, районы, кварталы, улицы, дома

Внимание

Используйте новый справочник адресов. Начиная с версии 5.3 старый справочник адресов будет убран.

Адресный справочник необходим для правки параметров договоров и объектов типа "Адрес". Основная сущность справочника - дом. Страны, города, кварталы, районы и улицы - это обычные перечисления, которые используются в справочнике домов. Города привязаны к странам. Кварталы, районы и улицы привязаны к городам. Дома привязаны к улицам. Адресный справочник доступен в меню Справочники=>Адреса или при нажатии комбинации клавиш Alt+A.

Для поиска нужного адреса, необходимо сначала выбрать страну, город, улицу/квартал/район и дом. Для поиска каждой из сущностей в параметрах поиска доступно несколько режимов:

  1. подстрока - искомая сущность должна содержать введеную подстроку;

  2. начинается - искомая сущность должна начинаться с введенной подстроки;

  3. заканчивается - искомая сущность должна заканчиваться на введенную подстроку;

  4. равна - искомая сущность должна совпадать с введенной подстрокой.

После того, как необходимая сущность найдена необходимо двойным кликом выбрать ее. После выбора найденной сущности в таблице выведутся все привязанные к ней сущности, параметр поиска заблокируется, причем в строку поиска будет введно полное название искомой сущности. Как видно из скриншота, приведенного выше, после выбора улицы, данный параметр заблокировался для редактирования, а в таблице справа вывелись все дома, относящиется к данной улице, которые заведены в справочнике.

Для редактирования сущностей, необходимо выбрать ее в таблице и нажать кнопку редактирования на глобальной панели инструментов. Все редакторы схожи, кроме редактора домов. Редактор позволяет отредактировать название сущности и добавить к ней параметры, которые были заведены в конфигурации сервера.

Редактор домов обладает большей функциональностью. В нем можно привязать дом к району, кварталу. Также можно указать индекс дома и кол-во квартир в нем.

Для улицы можно завести специальный параметр boxIndexRange по которому при заведение дома может автоматически вычисляться почтовый индекс. Поиск индекса идет до первого совпадения.

Пример 1.3. Примеры заполнения параметра boxIndexRange

Заполнение параметра boxIndexRange.

Пример 1. Все дома на улице с одинаковым индексом

450000:*

Пример 2. Несколько диапазонов с разными индексами

450001:1-10,31-34;450002:11-30;45000:*

Пример 3. Несколько диапазонов с разными индексами, исключение для конкретных номеров домов и дома с индексами.

450023:7,3,5/a,1;450001:1-10,31-;450002:11-30

Для дома можно завести специальные параметры диапазонов, по которым будет автоматически рассчитываться подъезд и этаж указанной квартиры. Это параметры floorRange - для определения этажа по квартире , entranceRange - для определения подъезда по квартире. Они также заводятся в конфигурации сервера.

Пример 1.4. Примеры заполнения параметров floorRange и entranceRange

Заполнение параметра entranceRange.

Пример 1. Заполнение параметра для простого 9 этажного панельного дома, в котором 3 подъезда, диапазон квартир 1-108, кол-во квартир 4 на этаже и соответственно в одном подъезде 36 квартир.

1-108/36/1,

где первый параметр - диапазон квартир в доме/нескольких подъездах, второй параметр - количество квартир в подъезде, третий параметр - с какого подъезда начинается данный диапазон квартир.

Пример 2. Заполнение параметра для сложного дома.

1-72/36/1;73-132/60/3;133-168/36/4;169-187/19/5

Из примера видно, что в данном доме первые 2 подъезда стандартные по 36 квартир в подъезде, в 3 подъезде 60 квартир, в 4 - опять 36 квартир, а в 5 - 19 квартир. Соответственно ";" разделяются диапазоны квартир в нескольких подъездах.

Заполнение парметра floorRange.

Пример 1. Заполнение параметра для простого 9 этажного панельного дома, в котором 3 подъезда, диапазон квартир 1-108, кол-во квартир 4 на этаже и соответственно в одном подъезде 36 квартир.

1-108/4/1/9,

где первый параметр - диапазон квартир в доме/нескольких этажах, второй параметр - количество квартир на этаже, третий параметр - с какого этажа начинается данный диапазон квартир, четвертый параметр - на каком этаже заканчивается данный диапазон квартир.

Пример 2. Заполнение параметра для сложного дома.

1-72/4/1/9;73-132/4/1/15;133-168/4/1/9;169-183/3/1/5;184-187/2/6/7.

Из примера видно, что в данном доме первый диапазон стандартный по 4 квартиры на этаже с 1 по 9й этаж (соответствует первым 2 подъездам в доме), второй диапазон 15 этажей и по 4 квартиры на этаже (соответсвует 3 подъезду в доме), третий диапазон 9 этажей по 4 квартиры на этаже (соответствует 4 подъезду в доме), четвертый диапазон с 1 по 5 этажи по 3 квартиры на этаже, пятый диапазон с 6 по 7й этаж по 2 квартиры на этаже. Четвертый и пятый диапазоны соответствуют 5 подъезду в доме. Соответственно, ";" разрделяется диапазон квартир на нескольких этажах.

На квладке Новые адреса выводятся адреса, заведенные через интерфейс "Пользовательское значение адреса" в редакторе адресного параметра договора.

В левой части интерфейса отображаются адресные параметры договора и параметры объектов. В правой части новые адреса в таблице. При двойном клике открывается редактор адресного параметра договора, в нем можно повторно попробовать найти данный адрес. Если он не находится, то необходимо данный адрес завести в справочник адресов. Для этого необходимо переключиться на вкладку Адреса. После заведеня нового адреса в справочник, необходимо переключиться обратно на вкладку Новые адреса и открыть редактор адресного параметра договора, после чего произвести поиск нового адреса и заполнить адресный параметр договора.

17.3. Договоры - параметры

В дополнение к стандартному набору параметров договор может иметь набор пользовательских атрибутов. Для этого их надо перечислить и указать их тип.

Существуют следующие типы параметров договоров:

Текстовое поле - простой текстовый параметр, например Фамилия;
Список - значение параметра может быть выбрано из определённого перечня, перечень значений определяется в справочнике Значения списков (см. далее);
Адрес - структурированный адресный параметр, ссылается на справочники Городов, Улиц, Районов и Домов;
Флаг - параметр имеющий только два значение - да/нет;
E-Mail - в значении данного параметра договора могут быть введены E-Mail адреса;
Договор - параметр договора, ссылающийся на другой договор (необходим для реализации агентских договоров);
Дата - параметр типа дата;
Телефон - параметр типа телефон. Подробнее см. здесь.
Разделитель - визуальный разделитель в списке параметров.
Мультисписок - может быть выбрано одно или несколько значений из определенного перечня, перечень значений определеятся в справочнике Значения мультисписков (см. далее);

Также существует возможность включить ведение истории параметров договоров каждого договора. Для того, чтобы включить ведение истории нужного параметра, двойным щелчком откройте редактор параметра и установите галочку в поле "История". Нажмите "ОК".

О просмотре истории параметра подробнее см. здесь.

17.4. Договоры - группы параметров

Иногда для разных групп договоров существуют параметры, которые не совпадают друг с другом. Так, для договора на частное лицо параметр "Юр. адрес" не имеет смысла. Чтобы при редактировании договора отображались только нужные параметры, следует создать группу параметров и в привязке параметров указать необходимый набор атрибутов.

Группа параметров привязывается к договору, определяя какими параметрами он обладает.

Ниже изображен справочник групп параметров - это простой перечень, где редактирование осуществляется кнопками панели инструментов.

При добавлении новой группы или редактировании существующей открывается панель привязки параметров, которая определяет какие параметры есть у договоров группы.

17.5. Договоры - группы

Группы необходимы для логического объединения договоров одного типа, поиска. Например: "Телефония", "Интернет" и т.п.. У одного договора может быть установлено сразу несколько групп, они сохраняются битовой маской.

Для того, чтобы убрать группу у всех договоров, необходимо в справочнике групп выбрать группу, нажать правой кнопкой мыши и в появившемся меню активировать пункт Удалить у всех договоров. Признак Группа используется определяет видимость группы в редакторе в договоре и во всех фильтрах поиска.Признак Редактируемый элемент означает то, что помеченные группы вручную можно устанавливать/убирать в договоре.

17.6. Договоры - шаблоны комментариев

Зачастую приходится вводить однотипные комментарии в имени договора, которые совпадают с какими-либо его параметрами (Ф.И.О., электронный адрес и прочее). Для автоматизации этого процесса можно использовать шаблоны комментариев. Для редактирования справочника шаблонов комментариев выберите пункт меню Справочники->Другие и затем Шаблоны комментариев в панели слева.

Для создания нового шаблона комментария нажмите на кнопку Создать на панели сверху. Для редактирования шаблона выделите необходимую строку и нажмите на кнопку Редактировать на панели сверху, либо дважды щелкните по ней мышью. Для удаления выбранного шаблона нажмите на кнопку Удалить.

В шаблоне указывается Название шаблона, а также сам Шаблон. Шаблон - это произвольная строка, в которой возможна подстановка значений из параметров договора, путём включения макросов ${param_<pid>}, где <pid> - код параметра договора. Например: ${param_4} - подстановка значения параметра договора с кодом 4. При изменении параметров договора комментарий автоматически изменяется с учётом новых значений параметров.

В договоре шаблон комментария указывается при редактировании имени и комментария договора.

17.7. Договоры - именованные номера шаблонов

Порядковый именованный параметр шаблона имени договора позволяет вставить номер в имя договора при создании из шаблона. Подробности о шаблонах имени. Он идентичен подстановке ${NX} но обладает следующими преимуществами:

  • Возможность сквозного нумерования в разных шаблонах;

  • Вы сможете править шаблон имени и при этом нумерация продолжится с того же номера;

  • Возможность сквозной нумерации между разными серверами биллинга;

  • Скорость генерирования имени гораздо выше( для примера: БД с 10К договорами генерирование происходит в 8~10 раз быстрее );

Для редактирования справочника именованных номеров выберите пункт меню Справочники->Другие и затем Договоры - именованные номера шаблонов в панели слева.

Для создания нового именованного порядкового номера нажмите на кнопку Создать на панели сверху. Для редактирования выделите необходимую строку и нажмите на кнопку Редактировать на панели сверху, либо дважды щелкните по ней мышью. Для удаления выбранного именованного порядкового номера нажмите на кнопку Удалить.

При создании необходимо указать следующие данные:

  • Название - это уникальная произвольная строка, которая является указателем на параметр, именно его вы будете подставлять в макрос "${NS_name}" вместо "name"

  • Индекс - это текущий номер с которого начнется отсчет. Например если вы хотите заменить параметр ${NX}, то вам следует сюда указать последний его номер. Для новых параметров укажите 0;

  • Кол-во цифр - это, как следует из названия, указатель порядка числа. Например если он = 3, то для первого договора он будет 001;

Следует иметь в виду, что при изменении названия вам следует также изменить его и во всех используемых шаблонах имени.

Генератор не боится повторений, и если сгенерированное имя уже занято, то счетчик будет увеличен на 1 и так до тех пор, пока не будет сгенерировано уникальное имя.

17.8. Договоры - значения списков

В данном справочнике указываются допустимые значения для списковых параметров.

В верхнем списке выбирается требуемый списковый параметр, по двойному клику мыши либо открывается перечень значений. Редактирование перечня осуществляется нижней панелью инструментов.

На вкладке Пользовательские значения списков можно добавить новое значение справочника и/или заменить пользовательское значения списка на существующее значение.

Добавить - добавится новое значение в справочник и пользовательское значение в договоре заменится на добавленное. Удалить - значение удалится из договора.

Заменить - пользовательское значение заменится на значение из справочника.

Аналогично c Значения мультисписков и Пользовательские значения мультисписков

17.9. Договоры - обслуживание

Здесь указывается перечень обслуживающих лиц. В дальнейшем эти лица могут быть привязаны в параметрах конкретного договора как обслуживающие какие-то адреса клиентов. Использование данного параметра нежелательно в связи с появлением в биллинге системы объектов, позволяющей выделять отдельные точки клиента в объекты с указанием в параметрах адреса объекта, обслуживающих лиц и пр.

17.10. Договоры - скрипты поведения

Перечень скриптов поведения, которые могут быть назначены договору. Скрипт поведения определяет реакцию на определённые события относящиеся к договору, более подробно о скриптах BGBS описано далее.

17.11. Типы платежей

Типы платежей необходимы для разделения потока платежей клиентов по видам. Далее по ним может быть построена аналитика. Примеры типов платежей: "Наличный", "Через банк", "Дилер Х", "Платёж за подключение" и т.п..

Для добавления нового типа, либо подгруппы нужно выбрать группу для добавления (группа Все группы существует изначально) и нажать Новый элемент на панели инструментов.

В справочник можно добавить как группу платежей (см. снимок выше) так и непосредственно платёж, выбирая галочку Группа, либо Элемент группы. Группы типов платежей предназначены исключительно для визуально более лёгкого восприятия перечня типов платежей в справочнике. Нигде больше они в данный момент не используются.

После добавления платёж, либо группу можно перемещать между группами-предками. Для этого выберите узел, нажмите правой кнопкой мыши, в появившемся меню выберите Вырезать, далее выберите новую группу для переносимого узла вызовите меню правой кнопкой мыши и выберите Вставить.

Параметр Нередактируемый элемент показывает, что данный тип платежа нельзя заносить и редактировать через редактор платежей в договоре. Для того чтобы добавлять платежи договорам в справочнике должен быть хотя бы один Редактируемый тип платежа. Создайте его сразу.

Нередактируемые платежи заносятся системой без непосредственного участия человека, это мера защиты от правки такого платежа оператором, например, при активации интернет-карточки. Для правки такого платежа пользователь, обладающий правами изменять справочники, должен снять признак нередактируемости с типа платежа, скорректировать платёж в договоре и вернуть признак.

Следует обратить внимание на столбец ID - это код типа платежа. Во всех конфигурациях, где необходимо указание типа платежа, указывается именно этот код.

17.12. Типы расходов

Расход - это единоразовое снятие с баланса договора некоторой суммы. Так же как и платёж расходы разделяются по типам, отображающим их назначение. Например: "Переподключение", "Вызов мастера" и т.п. Расходы также бывают редактируемые и нередактируемые. Для занесения расхода в договор биллинга в справочнике должен быть заведён хотя бы один редактируемый тип расхода. Создайте его сразу.

Редактирование справочника аналогично справочнику типов платежей.

17.13. Типы времени

Справочник предназначен для создания глобальных категорий времени и использования их в дальнейшем в тарифных планах в узлах типа Ограничение по типу времени.

При открытии типа времени для редактирования открывается редактор с одним или несколькими периодами, бесконечный период выглядит как просто тире. Периоды позволяют внутри одного типа времени задавать разные маски для разных интервалов дней. Например, можно вести учет выходных и праздничных дней на несколько лет. При открытии редактирования периода отображается редактор следующего вида:

В верхней области необходимо определить, собственно, период действия. В приведенном примере начато определение выходных и праздников на 2009 год.

Далее задаются несколько правил. Каждое правило устанавливает маски на часы, дни недели, дни месяца, месяцы. Месяцы могут принимать значения от 1 до 12, часы от 0 до 23, дни недели от 1 до 7, месяцы от 1 до 12. Маски в пределах правила соединяются условием "И". Т.е., например, часы от 0 до 8 И дни недели 6-7. Правила внутри типа времени соединяются условием ИЛИ. Совпадение хотя бы с одним правилом времени даёт основание отнести его к данному типу.

Несколько особенностей поведения типов времени:

1. пустая дата начала или оконачания периода означает бесконечность;
2. при пустом списке периодов в типе времени любое время относится к данному типу;
3. пустой набор правил периода также "включает" в себя любое время, попавшее в данный период.

18. Договор

18.1. Общие сведения, создание договора

Договор - основная рабочая единица системы BGBilling. В терминах BGBilling договор - это отдельный баланс (кошелёк) и набор параметров. К договору подключаются установленные в системе модули, посредством добавления услуг этих модулей, что позволяет абоненту использовать свой баланс на различные виды услуг, предоставляемых модулями.

Создание договора производится выбором пункта меню Договор=>Новый договор, либо кнопки Новый договор на стандартной панели инструментов. При создании договора открывается диалог следующего вида:

Если система только что установлена, в списке шаблонов будет предложен только один шаблон По умолчанию. Перед созданием договора необходимо выбрать дату и шаблон, по которому будет создан договор. Шаблон имени договора можно задать вручную. Также данный диалог позволяет создать субдоговор. Для этого нужно выбрать соответсвующий пункт, после чего появятся дополнительные параметры.

При создании субдоговора следует указать какой будет баланс, зависимый или независимый. Также необходимо выбрать супердоговор, у которого можно скопировать заполненные параметры договора. Настройка копирования производится в конфигурации сервера. В нее следует добавить одну или несколько подобных записей, в зависимости от количества шаблонов.

contract.params.copy.<pattern_id>=1,2,19

где pattern_id - код шаблона, по которому создается договор, а значение этой переменной является список id параметров договора.

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

После нажатия Создать открывается вкладка со вновь созданным договором New contract. При использовании шаблонов система способна также самостоятельно вести последовательную нумерацию вновь создаваемых договоров с использованием порядкового номера договора, года создания.

18.2. Обзор карточки договора

Карточка вновь созданного договора выглядит следующим образом.

Числом 1 отмечен номер договора. Номер может содержать любые буквы и цифры и, для вновь созданного договора по шаблону По умолчанию, устанавливается в New contract. После номера в скобках указывается комментарий договора, для нового договора он пуст. Числом 2 отмечен уникальный идентификатор договора.

Рекомендуется присваивать договорам единообразную буквенно-цифровую нумерацию вида B5555-07 (пример), при этом префикс можно использовать для обозначения типа договора (телефония, интернет, IP-телефония и т.п.), а порядковый номер - для последовательной нумерации.

В комментарии можно указывать название организации, либо Ф.И.О. частного лица. Для изменения номера и комментария кликните на них. В появившемся диалоге введите требуемые значения.

Комментарий для договора может задаваться шаблоном комментария. Если выбран пункт Без шаблона, то комментарий можно задавать вручную, в противном случае (если выбран какой-либо шаблон), то комментарий формируется автоматически.

Кнопка Восстановить возвращает поля редактора номера в исходное состояние.

Период договора (3) определяет временной диапазон существования контракта. Дата начала устанавливается в момент создания договора и может быть впоследствии изменена. При закрытии даты завершения система автоматически закрывает периоды действия всех услуг в договоре (период действия логинов, абонплат, ИП адресов и т.п.).

В левой области карточки договора расположено дерево навигации (5). Оно позволяет переключать вкладки редактирования характеристик договора.

Первым при открытии договора отображается вкладка с параметрами договора (сами параметры обозначены числом 4, более подробно чуть далее).

Более подробно об остальных вкладках по тексту ниже. В частности об объектах вы можете прочитать здесь, при первом ознакомлении этот пункт можно пропустить, а об иерархии договоров описано в отдельной главе.

18.3. Параметры договора

18.3.1. Общие сведения

Набор параметров договора состоит из фиксированных и настраиваемых параметров. К фиксированным относятся:

Лицо - Физическое, либо Юридическое, параметр обозначает тип контрагента по договору;
Группа параметров - определяет набор настраиваемых параметров договора, которые будут использованы в данном договоре, перечень групп настраивается в справочнике Справочники=>Другие=>Договоры - группы параметров.

О создании настраиваемых параметров договоров, их привязке к группам описано в описании справочника "Договор - параметры".

Набор настраиваемых параметров отображаются в виде таблицы. Если группа параметров не установлена для договора, то договору доступны все заведённые в справочнике Параметры договоров параметры. Иначе будут отображены только параметры, входящие в выбранную группу. Для удобства поиска и заполнения параметров предусмотрен фильтр по параметрам. Также можно вывести только заполненные параметры: для этого необходимо нажать на соответствующую кнопку.

18.3.2. Копирование параметров

Для копирования параметров из других договоров в текущий открытый договор необходимо вначале открыть необходимые договоры. Далее в договоре, в который нужно скопировать параметры из других нажать на кнопку копировать из...

В открывшемся окне необходимо выбрать договор, из которого будут копироваться параметры. Для удобства поиска параметров можно выбрать все или только заполненные параметры договора, из которого они копируются. Далее необходимо отметить параметры, которые нужно скопировать. Если копирование параметров давольно частое действие и копируются одни и теже параметры, то можно завести шаблон, при выборе которого, параметры, которые указаны в шаблоне, будут автоматически выделяться. Шаблоны настраиваются в кофигурации сервера. Копировать параметры можно в 2х режимах: в режиме замены или режиме дополнения.

18.3.3. Параметры типа "Текст", "Флаг", "Дата", "E-Mail"

Правила редактирования параметров различных типов различны. Для редактирования текстового параметра необходимо выбрать правый столбец, ввести новое значение и нажать Enter.

Для редактирования параметра типа Флаг достаточно изменить его нажатием мыши.

Для редактировании параметра типа Дата необходимо двойным нажатием по строке выбрать календарь и, ввести дату, либо закрыть календарь, выбрав, тем самым, текущую дату, либо нажать Х, очистив дату.

Для редактирования параметра типа E-Mail двойным кликом вызовите редактор, указав адреса, каждый с новой строки.

18.3.4. Параметр типа "Адрес"

Для редактирования параметра типа Адрес вызывается редактор двойным кликом мыши по строке.

При выборе дома система автоматически высвечивает индекс, район и квартал. Для выбора дома нужно нажать на кнопку с адресом. При этом редактор перейдет в режим поиска дома.

Для осуществления поиска необходимо начать вводить название улицы в соответствующем элементе управления. При этом, по мере набора, покажется выпадающий список названий улиц (с указанием городов), которые содержат в виде подстроки введенную в поле строку. В этом списке выводится только 25 первых записей. Выделение нужной улицы осуществляется с помощью клавиш "вверх" и "вниз" на клавиатуре. Для выбора выделенной улицы нужно нажать клавишу Enter. При этом автоматически начнется поиск всех домов, находящихся на выбранной улице, с последующим выводом найденного списка в таблице.

Кроме выбора улицы из выпадающего списка предусмотрен второй вариант. Можно набрать в поле "Улица" название улицы или ее часть и нажать Enter (не выбирая при этом из выпадающего списка). При этом в таблицу будут выведены все найденные улицы, содержащие введенную строку в качестве подстроки. Далее, двойным щелчком по строке таблицы выбирается нужная улица, после чего в таблицу загружаются дома, расположенные на этой улице. Описанный режим поиска улиц полезен, если требуемая улица отсутствует в выпадающем списке (ввиду ограничения в 25 записей).

Для выбора дома нужно дважды щелкнуть на соответствующей строке в списке найденных домов. После этого редактор вернется в исходный режим, где можно указать дополнительную информацию об адресе.

Для уменьшения количества выводимых записей в таблице предусмотрен фильтр по номеру дома. В поле Дом (в него можно перейти нажатием клавишы Tab) нужно ввести номер интересующего дома и нажать Enter. При этом в списке найденных домов останутся только те дома, в номерах которых присутствует подстрока, введенная в поле Дом.

Установкой опции конфигурации сервера address.create=yes можно разрешить добавление недостающего дома непосредственно при редактировании параметра. При этом пользователю будет доступна кнопка "Добавить новый дом..." в режиме поиска дома. При нажатии на нее редактор перейдет в режим создания нового дома.

Кнопка "Пользовательское значение адреса" предназначена для записи адреса в свободной форме операторами биллинга, если необходимая улица не была найдена. По завершении редактирования адреса он попадает в специальный раздел редактора адресов. После чего администратор или оператор, обладающий правами на редактирование адресов, заводит несуществующие адреса в справочник адресов.

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

В некоторых случаях удобнее и правильнее использовать один формат, тогда как для другого случая данный вариант не подходит. Форматы отображения адреса настраиваются в конфигурации через меню Сервис->Настройка->Кофигурация.

Формат адреса настраивается с помощью параметра addrs.format.pattern.<ID>, где в качестве <ID> может выступать любой уникальный идентификатор: будь то строка или число. Есть также некоторые особенности: если в начале идентификатора указывается cp (ContractParameter - параметр договора типа Адрес) или ор (ObjectParameter - параметр объекта типа Адрес), то после такого идентификатора необходимо указывать pid (из меню Справочники->Другие->Договоры-параметры) того адресного параметра, которому необходимо задать формат.

Примеры:

addrs.format.pattern.1=(${index})(, ${city})(, ${area})(, ${quarter})(, ${street})(, д. ${house})(${frac})(, ${flat})( комната ${room})(, ${pod} подъезд)(, ${floor} этаж)(, [${comment}])
addrs.format.pattern.2=(${index})(, ${city})(, ${street})(, д. ${house})(${frac})(, ${flat})(, [${comment}])
addrs.format.pattern.3=(, ${city})(, ${street})(, д. ${house})(${frac})(, ${flat})(, [${comment}])
addrs.format.pattern.cp19=(, ${city})(${index})(, ${street})(, д. ${house})(${frac})(, ${flat})
addrs.format.pattern.op6=(улица ${street})(, дом ${house})(${frac})(, кв. ${flat})(, комн. ${room})
addrs.format.pattern.cp58=(улица ${street})(, дом ${house})(${frac})(, квартира ${flat})

Формат адреса - это REGEXP, в котором прописаны определенные переменные. В качестве переменных можно использовать: ${index} - индекс; ${city} - город; ${area} - район; ${quarter} - квартал; ${street} - улица; ${house} - дом; ${frac} - дробь; ${flat} - квартира; ${room} - комната; ${pod} - подъезд; ${floor} - этаж; ${comment} - комментарий параметра.

Для корректной работы форматов адресов необходимо указывать в конфигурации параметр addrs.format.list, в котором прописать порядок следования форматов друг за другом. В соответствии с этим списком будет заполнена таблица Формат адреса. Соответственно, некоторые форматы можно и не включать в список - тогда они не будут отображаться в таблице. Пример:

addrs.format.list=1;cp19;3;cp58;op6

Как видно из примера, формат с идентификатором 2 не включен в список. Помимо настраиваемых форматов в таблице Формат адреса на первой строке всегда будет формат по умолчанию:

Если параметр addrs.format.list не указывается в конфигурации, то в конфигурации ищется параметр addrs.format, если и он не будет найден, то в таблице будет только 1 формат по умолчанию. Примеры с использованием параметра addrs.format:

addrs.format=(${city})(, ${street})(, д. ${house})( , дробь ${frac})(, квартира ${flat})
addrs.format.cp58=( ${city})(, ${street})(, д. ${house})(${frac})(, ${flat})(, [${comment}])

При редактировании справочников Города, Улицы, Дома, Районы, Кварталы все адресные строки, ссылающиеся на изменённые значения переформатируются.

Это свойство можно использовать при изменении формата адреса в конфигурации. Простое пересохранение названия города в справочнике городов переформатирует все адреса, относящиеся к этому городу.

При установке параметра конфигурации сервера address.unique.check=1 система будет выводить предупреждения если в других договорах есть аналогичный адрес.

18.3.5. Параметр типа "Список"

Для редактирования спискового параметра вызовите редактор двойным кликом по строке.

Выбор -- не указано -- очистит значение параметра.

18.3.6. Параметр типа "Мультисписок"

Для редактирования мультиспискового параметра вызовите редактор двойным кликом по строке.

Также можно добавить через точку с запятой одно или несколько пользовательских значений - значения не из справочника.

18.3.7. Параметр типа "Телефон"

Редактировать параметр типа Телефон можно вызвав редактор двойным щелчком мыши по строке.

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

Принцип формирования вывода - префикс - последовательность цифр, пробелов, тире и скобок. Произвольные цифры обозначаются символом 'X'. Все цифры идут до первого символа 'X'. Формат вывода номера телефона задается в конфигурации параметром phones.formats, в котором задаются через запятую возможные префиксы телефонов.

phones.formats=8 (917) XXXXXXX,7 (347) 2XX-XX-XX,XXX-XX-XX

При вводе в поле телефона цифр, будет произодиться поиск соответстующего префикса и вывод в соответствии с ним. Поиск производится сравнением первых введенных цифр и первых цифр из префикса. Например, в случае ввода цифр 89 формат вывода телефона будет отформатирован по первому префиксу, т.к. первый префикс подходит для телефонов, начинающихся с комбинаций цифр: 8917, 891, 89, 8. Поиск производится от частного к общему: например, в случае, когда пользователем будут введены 4 цифры 8917 будет производиться поиск префиксов, подходящих для комбинации цифр 8917, затем 891, после 89, потом 8 и в завершении префикс без цифр. Поиск префикса завершается при первом найденном префиксе.

Дополнение разрешенной длины номера телефона.

В редакторе телефона разрешенная длина номера равна 11, но разрешенную длину можно дополнить своим значением. Для этого в конфигурации параметрами заведите параметр phones.customLengthNumber.

phones.customLengthNumber=12

С данным параметром в редакторе можно будет набрать номер состоящий из 11 и 12 цифр. Внимание! Максимальная длина номера, даже с этим параметром, не может превышать 14.

18.3.8. История изменения параметра

Для просмотра истории параметров для данного договора необходимо щелкнуть по иконке с лупой (наличие знака "плюс" на иконке означает, что история для данного параметра в текущий момент времени ведется; отсутствие - не ведется) напротив интересующего параметра. В открывшемся окне отобразится история выбранного параметра. При необходимости ее можно очистить ,нажав на кнопку Очистить историю.

Если текстовый параметр содержит гиперссылку, то она выделится синим и подчеркнётся. Редактировать её можно как обычный текстовый параметр. Чтобы "кликнуть" по ней, как по гиперссылке, нужно зажать клавишу Ctrl - ссылка откроется в браузере по умолчанию. Для всех типов параметров вызвать соответствующий редактор можно как двойным кликом мышью, так и клавишей Enter.

18.4. Группы договоров

Группа - признак, несущий смысловую нагрузку, установленный в договоре. Например: Оператор, Телефония, VIP. Группы устанавливаются битовой маской, в одном договоре могут быть установлены несколько групп. Всего групп 62. Именование и активация групп производится в справочнике Справочники=>Другие=>Группы договоров, см. ранее. Доступны к редактированию в договоре только группы, отмеченные как используемые и которые не помечены как нередактируемые.

Редактирование групп договора осуществляется на вкладке Группы карточки договора простым проставлением, либо снятием галочек. После нажатия кнопки Обновить на общей панели инструментов выбранные группы отображаются в дереве.

Группы - основной инструмент деления договоров, доступный в качестве фильтра в большинстве мест, где требуется выбрать несколько договоров.

18.5. Поиск договоров

Поиск договоров осуществляется вызовом меню Договор=>Открыть договор, либо нажатием аналогичной кнопки на панели инструментов. После этого открывается окно поиска.

Поиск можно осуществлять по названию и комментарию с фильтром по группам и типу лица, либо по параметрам договора. При поиске по названию договора, либо комментарию следует набрать маску поиска и нажать >>> или клавишу Enter. Маска поиска - подстрока, входящая в искомое значение. Кнопка X - отмена поиска, сброс значения. >>> - запуск поиска.

Поиск по параметрам осуществляется выбором фильтруемых параметров и далее в зависимости от типа параметра.

Для спискового параметра выбирается параметр и проставляются галочками, удовлетворяющие условию значения.

Для мультиспискового параметра выбирается параметр и галочками проставляются удовлетворяющие условию значения.

Для параметра типа E-Mail вводится подстрока адреса и галочками отмечается перечень параметров, в которых анализируется данная подстрока.

Для параметра типа Текст выбирается подстрока и перечень параметров, в которых она ищется.

Для параметра типа Адрес выбираются город, улица, номер дома (дробь), квартира и комната, в которых будет произведён поиск. Для того, чтобы искаль по городам, в поле улица нужно начинать вводить название города начиная с *(. Например: *(Уфа).

Кроме номера договора в окне результатов поиска отображается сам адрес.

Для поиска по параметру Телефон необходимо указать номер телефона, а также сам параметр типа Телефон, по которому будет производится поиск.

Для поиска по идентификатору договора (ID договора) необходимо указать интересующий ID и нажать на кнопку >>> или клавишу Enter.

Для поиска по примечанию необходимо написать часть текста, содержащегося в примечании договора и нажать на кнопку >>> или клавишу Enter.

Также доступны следующие опции:

Учитывать скрытые - позволяет включить в результаты поиска скрытые договоры.

Учитывать субдоговора - позволяет искать субдоговоры при поиске.

Учитывать закрытые - ищет договоры, у которых дата закрытия меньше текущей даты. По умолчанию такие договора не ищутся.

После получения списка договоров выберите интересующие вас и нажмите OK. Возможно открытие нескольких договоров, выделив их с помощью кнопок Shift, Ctrl и мыши. Открыть договор можно также двойным кликом мышью или клавишей Enter.

18.6. Баланс

Вкладка позволяет отследить движение денег на балансе пользователя. Баланс в системе ведётся помесячно, каждый месяц характеризуется:

  1. входящим остатком - остатком денежных средств с конца предыдущего месяца;

  2. наработкой - наработкой по различным услугам, которые потреблял клиент, наработку начисляют модули;

  3. приходом - поступления денежных средств на баланс пользователя в течении месяца;

  4. расходом - списанием денежных средств за разовые услуги со счета клиента;

  5. возвратом - списанием денежных средств, которые были возвращены клиенту;

  6. исходящим остатком - вычисляемое значение Исх.ост. = Вх.ост. - Расход + Приход - Наработка - Возврат, исходящий остаток переходит на входящий остаток следующего месяца.

  7. резервом - временное списание денежных средств, если включено влияние резервов на баланс.

  8. доступная сумма - идентично исходящиму остатку, но включает еще и резервы, и соответсвенно если у вас включено влияние резервов, то данная сумма будет отлична от исходящего остатка на текущую велечину резервов у клиента.

Для того чтобы включить влияние резервов на баланс договора, необходимо добавить параметр в конфигуратор сервера: contract.balance.reserve.influenceToBalance=true. А после перезапустить сервер. Если не включать, тогда резервы могут нести некий информационный характер.

В дереве вкладок (слева) отображается баланс за тот месяц, за который было зарегистрировано последнее движение по балансу (в целях оптимизации размеров БД). Для просмотра баланса договора за месяц нажмите кнопку Баланс.

Баланс отображается в табличном виде в формате : "Месяц, год - Входящий остаток - Приход - Наработка - Расход - Исходящий остаток".

В верхней области можно выбрать текущий период с точностью до месяца.

Режим, выбираемый кнопкой М - просматривается баланс выбранного кнопкой месяца. Режим П - позволяет просмотреть балас за определенный период путем нажатия на одну из кнопок:

"Договор" - весь период действия договора;
"Месяц" - период, равный текущему месяцу ;
"Квартал" - период, равный от начала текущего квартала до текущего месяца;
"Год" - период, равный от начала текущего года до текущего месяца;
"3 Мес." - период, равный последним 3-м месяцам;
"6 Мес" - период, равный последним 6-м месяцам;
"12 Мес" - период, равный последним 12-м месяцам.

При выборе Наработки отображается наработка за месяц, разбитая по услугам. Наработка не редактируется через клиентское приложение, её начисляют модули за различные услуги, потреблённые клиентом.

Кнопки Приход и Расход отображают платежи и списания по договору за месяц. В отличие от наработки, которая ведётся помесячно, платежи и расходы ведутся с указанием даты.

Для добавления платежа нажмите в режиме просмотра платежей Новый элемент на стандартной панели инструментов биллинга. Аналогично вносится расход. При внесении платежей/расходов в списке типов платежей/расходов отображаются только редактируемые типы.

Необходимо выбрать сумму, тип платежа/расхода и дату. После внесения платежа/расхода система автоматически обновляет баланс от месяца внесения платежа/расхода до текущего с корректировкой переходящих остатков. При этом за каждый месяц пересчитываются суммарные наработки, приходы и расходы.

Замечание

Внесение и удаление фиктивного платежа или расхода можно использовать для корректировки сбоев в балансе (когда сумма, отображаемая на вкладке Баланс, не соответсвует суммам платежей/расходов или наработки)

Для редактирования платежа/расхода нужно дважды кликнуть по нему в таблице, при этом будет вызван редактор, аналогичный редактору внесения платежа/расхода. Платежи/расходы нередактируемых типов править нельзя.

Режим Баланс дет. отображает сводную таблицу баланса договора за период с остатками, приходами, расходами и наработкой.

18.7. Лимит договора, режимы договора, управление лимитом

Лимит - это минимальный остаток счета договора, при котором он может еще работать. Для редактирования лимита перейдите на вкладку, изображенную на снимке ниже.

Для смены лимита можно использовать как кнопки с предопределенными значениями, так и произвольное значение, указанное в текстовой области. Каждая смена лимита отображается в логе. Есть возможность временного и постоянного изменения лимита.

Временное понижение лимита может использоваться, например, чтобы пользователь смог пополнить счет карточкой. В первом поле вводится значение, на которое изменяется лимит (положительное - для повышения, отрицательное - для понижения), а во втором - на сколько дней. При временном понижении лимита в таблице Автоматическое изменение лимита добавляется задание на возврат лимита на измененную сумму (см. снимок ниже). Задание может быть удалено, тогда лимит не будет возвращен в предыдущее состояние.

Возвращение лимита к прежнему значению осуществляется задачей восстановления лимитов которую нужно прописать в планировщике.

Если лимит нужно просто установить, второе поле ввода оставляется пустым. В текстовой области перед кнопкой Ок можно ввести комментарий, объясняющий изменение лимита.

Если при установке постоянного лимита на текущий момент у договора присутствуют задания на автоматическое изменение лимита, то пользователь будет уведомлен об этом в дополнительном диалоговом окне. Ему будет предложено подтвердить свое решение или же отказаться от него.

В конфигурации возможен запрет на установление постоянного лимита в таких случаях, так как это может привести к нежелательным последствиям (например, к ненужному завышению или занижению реального лимита, которое может произойти после отработки задачи восстановление прежде измененных лимитов).

Клиенту можно предоставить возможность самому временно понижать лимит через страницу Web-статистики (только в режиме Дебет).

18.8. Режимы баланса договора

В системе существуют два режима работы договора: дебет и кредит. Их отличие - в способе работы с должниками.

При режиме дебет должником признается договор, остаток которого менее текущего лимита счета. Все сервисы должника блокируются, а разблокировка производится как только на баланс договора поступит платеж, достаточный для превышения остатка над лимитом. Данный режим используется для предоставления сервиса по предоплате. Лимит может быть незначительно меньше нуля, либо равен нулю.

Режим кредит предназначен для организаций, работающих по кредитовой схеме оплаты. Должником признается договор, сумма платежей которого за текущий месяц не покрывает отрицательный остаток на начало месяца. При этом наработка и расходы за текущий месяц не учитываются. Лимит также является минимально допустимым остатком счета, но носит скорее функцию аварийного блокиратора, предотвращая сильную переработку клиента, например, при вирусной эпидемии. Для договоров в режиме кредит лимит устанавливается отрицательным, равным максимально приемлемой для клиента задолженности.

Отключение должников в кредитовом режиме производится оператором биллинга после выставления счетов и ожидания оплаты в течении нескольких дней. Для отключения используется система работы с должниками.

18.9. Статус договора

Статус - это глобальная характеристика договора, общая для всех подключенных услуг. Перечень статусов в системе и их коды задаются переменной contract.status.list конфигурации сервера, например, так:

contract.status.list=0:Активен;1:В отключении;2:Отключен;3:Закрыт;4:Приостановлен;5:В подключении

Код статуса должен быть уникален. В зависимости от статуса договора различные модули меняют свое поведение. Открывается, либо блокируется доступ к услугам, начисляется, либо не начисляется абонентская плата.

Текущий статус договора отображается отдельным узлом в дереве карточки договора в виде: Статус <значение>. При выборе узла дерева в таблице отображается статусы договора.

Внизу отображается таблица с историей изменения статусов.

В этом же окне возможно изменение статусов для договоров с указанием периодов и комментария. При смене статуса оператор указывает период и новый статус. В комментарии может быть указана причина изменения. Например: "По гарантийному письму ХХХХ". Период может быть указан с пустой датой окончания, в этом случае период считается не ограниченным сверху.

Вновь установленный статус перетирает все статусы с пересекающимися периодами. В один день возможен только один статус договора.

Не все статусы доступны для ручной установки, перечень запрещённых задаётся переменной конфигурации сервера contract.status.no.manual.set. Данные статусы могут устанавливаться, например, скриптами.

Если какой-либо статус более не используется, то его код должен быть указан в переменной конфигурации сервера contract.status.deprected, коды указываются через запятую. Статус останется в истории смен, но будет недоступен в фильтрации и установке.

Если устанавливаемый статус договора включает текущую дату, то действующий статус договора меняется сразу. Однако возможна ситуация, когда меняется текущий статус и остается задание на изменение статуса договора в дальнейшем. Такие задания выполняет стандартная задача планировщика Установка статусов договоров.

При смене статуса супердоговора изменяются статусы его зависимых субдоговоров. Включить смену статусов независимых договоров можно опцией конфигурации сервера independ.subcontract.status.change=1.

18.9.1. Настройка активных статусов в модулях

Статусы экземпляра модуля, в которых сервис доступен, указываются в переменной конфигурации модуля contract.status.active.codes. Коды статусов указываются через запятую. Например.

contract.status.active.codes=0

Статусы, в которых сервис считается приостановленным указываются в переменной contract.status.suspend.codes. Например.

contract.status.suspend.codes=3,4

Для модуля NPay данная переменная означает статусы, при которых не снимается абонплата. Для модулей с потреблением услуг влияет, например, на узлы-диапазоны в тарифных планах. Значение в узлах уменьшается в зависимости от времени, которое сервис был пристановлен. Более подробно это описано в документации модулей.

18.9.2. Роль статуса в дебетовых договорах

Для договоров в режиме Дебет статусы договора устанавливаются только администратором, перевод статуса договора в любой из неактивных делает модули заблокированными. Поступление денег на счет ситуацию не меняет. При нормальной работе дебетовый договор постоянно находится в активных статусах, сервисы при этом блокируются модулями, если баланс опускается меньше лимита и автоматически разблокируются после поступления денег на счет.

18.9.3. Роль статуса в кредитовых договорах

Для кредитовых договоров статус тесно завязан с системой работы с кредитовыми должниками. Он может изменятся в результате оплаты договора. Активный статус для кредитовых договоров задаётся переменной конфигурации сервера credit.contract.active.status. Например.

credit.contract.active.status=0

В активном статусе работает аналогичная дебетовым договорам аварийная блокировка/разблокировка сервисов в модулях по балансу и лимиту договора.

Основная рабочая область оператора для отключения кредитовых должников вкладка Сервис=>Администрирование=>Монитор статуса. Перед началом работы необходимо сделать срез балансов, нажав соответствующую кнопку. Все описанные далее алгоритмы применимы только к кредитовым договорам.

Монитор выводит информацию по состоянию кредитовых договоров, их статусах и сальдо (входящий остаток на начало месяца минус платежи за месяц). Таблицу с результатами выборки договоров можно выгрузить в csv формате.

Все фильтры соединяются по условию И. Возможна фильтрация по:

1. группе договора + исключение определенных групп договоров;
2. минимальному объему наработки по указанным услугам за прошлый и текущий месяц;
3. режиму договора: кредит/дебет;
4. статусу договора;
5. периоду, который договор был в данном состоянии в днях или месяцах;
6. сумме сальдо (указывается диапазон от и до);
7. соотношению текущего баланса или баланса на начало месяца с лимитом;
8. размеру превышения модуля отрицательного сальдо начала месяца над наработкой какого-то количества предыдущих месяцев.

Изменения статусов договоров производится идентично смене статуса одного договора (см. выше), необходимые договоры выбираются в таблице с использованием клавиш Ctrl и Shift. Двойной клик по строке таблицы открывает договор.

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

В случае, если отключенный статус попадает в перечень из переменной конфигурации credit.contract.open.by.payment.status, договор может быть возвращён в активный статус по приходу платежа, если сальдо станет положительным.

По звонку отключенного клиента с обещанием оплаты оператор может перевести его в активный статус на несколько дней. При этом период активного статуса указывается с датой открытия и закрытия. Если до окончания периода клиент не оплатит, отключенный статус станет действующим и клиента заблокирует. В случае оплаты вновь установленный активный статус перекроет будущий отключенный. При этом перекрытие производится только для статусов, которые указаны в переменной конфигурации credit.contract.override.future.to.active.status.

При неоплате клиента в течении какого-то времени возможна его выборка монитором статуса и перевод в другой отключенный статус, из которого уже не выводит платёж.

Если по каким-либо причинам такое поведение статусов нежелательно, то можно отключить автоматическую активацию договора при изменении сальдо на положительное. Для этого в концигурации сервера необходимо указать флаг do.not.open.contract.on.payment=1. Отсутствие этой записи или установка флага в 0 оставит поведение по умолчанию.

Если же возникла необходимость отключить данное поведение не для всех договоров, а только для каких-либо групп договоров, то необходимо установить флаг.

do.not.open.groups.on.payment=X,Y,Z,...

Где X, Y, и Z - это номера групп договоров, для которых стандартное поведение нежелательно.

18.9.4. Изменение стандартной логики перетирания статусов

Имеется возможность задать свою любую логику перетирания статусов при установке. Стандартная логика заключается в полном перекрытии лежащих уже в договоре отрезков статуса. Иногда требуется при разных условиях выполнять разные действия. Для этого предназначено событие BGBS Задание логики перетирания статусов. В скрипте (обработчике этого события) можно отслеживать откуда выполняется попытка установить статус (сервер, клиент, web) и полностью изменить алгоритм.

На WiKi-странице "Изменение стандартной логики перетирания статусов" приведены дополнительные подробности и прилагается полный рабочий скрипт, представляющий собой в точности реализованную стандартную логику. Его также можно использовать для изучения алгоритма. Там же расположено описание алгоритма установки статусов и примеры скриптов.

Возможность включается установкой в конфигурации сервера флага

# Использовать ли событие Задание логики установки/перетирания статусов (иначе используется стандартное поведение)
use.event.set.status.logic=1

18.10. Тариф и группа тарифов

На двух вкладках отображаются глобальные тарифные планы, установленные для данного клиента и его персональные тарифные планы. Для добавления глобального, либо локального тарифного плана используйте кнопку Новый элемент.

Тарифы можно фильтровать по признаку используемости, по модулю и по фильтру договоров, указанных в самом тарифном плане (см. здесь). В один момент у договора могут быть несколько тарифов, в каждом из которых устанавливаются цены услуг в разных модулях.

Позиция тарифного плана - это число, задающее порядок просмотра тарифа при поиске цены. Позиция действует лишь для некоторых модулей. Более подробно о позициях и тарифных планах вообще можно прочитать далее.

Группа тарифов нужна исключительно для ограничения тех тарифов, на которые клиент может переключиться через Web-интерфейс. Более подробно об этом описано в главе Группы тарифных планов

18.11. Примечания

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

Галочка примечание доступно пользователю отображает примечания в Web-интерфейсе клиента в меню Примечания.

18.12. Дополнительные действия

Дополнительные действия в договоре - это возможность непосредственного вызова скрипта BGBS для данного договора через АРМ оператора биллинга, либо из Web-статистики. Список дополнительных действий формируется скриптом по событию Получение списка доп. действий для договора, либо Получение списка доп. действий для Web, пример в WiKi.

Далее оператор биллинга, либо клиент на Web-статистике вызывает действие, снова вызывая скрипт, но уже с событием Обработка доп. действия для договора. Скрипт выполняет какие-то действия с договором, возвращая сообщения.

Cообщения о выполненых действиях возможно создавать в виде html, при этом создержимое должно быть валидным xml-фрагментом, а корневым элементом должен быть элемент <html>:

event.addReport( "<html><table cellspacing=\"1\"><thead><tr><td>Отчет</td></tr></thead><tbody>"
  + "<tr><td class=\"comment\">Привет, анлим активирован!!!</td></tr></tbody></table></html>" );

18.13. Подключение модулей и их услуг к договору

При выборе узла Модули отображаются как потребляемые клиентом модули, так и неиспользуемые. В качестве дочерних узлов выступают подключенные модули.

На открывшейся панели возможно манипулировать подключенными к договору модулями. В левом списке перечислены модули, которые уже подключены к договору. В правом списке, соответственно, указаны модули, которые не подключены. Для того, чтобы подключить к договору новые модули, выберите их из списка права, отметив галочками, и нажмите на кнопку <. Все выбранные модули будут подключены к договору. Соответсвенно, для отключения модулей из договора выберите их в списке слева и нажмите на кнопку >.

Внимание

При удалении модулей из договора сохранность выделенных сущностей, оказанных услуг и прочей информации данного модуля, связанной с данными договором, НЕ ГАРАНТИРУЕТСЯ.

Добавленный модуль должен появится в дереве. Далее его можно выбрать и изменить пользовательскую настройку этого модуля для контракта (для DialUp - это список логинов входа), а также добавить разрешенные услуги для модулей, где они необходимы.

В некоторых модулях конфигурация услуг данного модуля, добавленная в договор, также имеет значение. В модуле DialUP возможен режим, когда при авторизации проверяется наличие в договоре всех требуемых для данной сессии услуг.

Разрешенные для модуля услуги настраиваются на соответствующей вкладке в настройках договора. Чтобы добавить новый модуль нажмите кнопку Добавить на стандартной панели инструментов.

18.14. Карты регистрации договора

18.14.1. FOP-карточки

Вид карточки:

Карточки генерируются по XSLT:FO-шаблону, указанному в основной конфигурации:

contractcard.1=card_inet.xsl:Карта регистрации
contractcard.2=card_inet.xsl:Вторая карта регистрации

Возможно указание групп договоров, для которых отображается данная карта. Группы указываются после указания карты в конфигурации, через двоеточие:

contractcard.2=card_inet.xsl:Вторая карта регистрации:0,4,5

В приведенном выше примере карточка отображается только для груп договоров с кодами 0, 4 и 5.

Замечание

XSLT-шаблон card_inet.xsl можно использовать как пример, поправив его под ваши модули. Шаблон необходимо переименовать, чтобы избежать его перетирания при обновлении.

Если существуют какие-либо более сложные условия для добавления той или иной карточки к данному договору, то можно воспользоваться скриптом поведения на событие Получение списка карточек договора.

Возможно создание собственных карточек: при генерации карточки в XML-документ собирается информация по договору, затем документ трансформируется по выбранному шаблону. Содержимое XML-документа можно посмотреть, если нажать на кнопку XML:

С помощью кнопок управления внизу окна карточка может быть распечатана, сохранена в PDF-файл, отправлена на почту. Карточки доступны к загрузке в Web-интерфейсе клиента.

18.14.2. Полная карта договора

Карта имеет следующий вид:

Карточка генерируется по XSLT-шаблону contract.xsl. При генерации карточки в XML-документ собирается информация по договору, затем документ трансформируется в HTML. Содержимое XML-документа можно посмотреть если нажать на кнопку XML.

С помощью кнопок управления внизу окна карточка может быть распечатана, сохранена в HTML-файл, отправлена на почту.

18.15. Шаблоны договоров

Шаблоны договоров созданы для двух целей:

1. они позволяют избежать рутинного заполнения параметров при частом создании однотипных договоров, достаточно указать шаблон и параметры будут указаны автоматически;
2. для автоматического создания договоров; например, при первом звонке клиента с интернет-картой, ему создается договор по шаблону, который указан для этой карты.

Для создания или редактирования шаблонов зайдите в Договор=>Шаблоны.Редактирование осуществляется с помощью общей панели инструментов. Для создания шаблона, ему необходимо дать имя и указать параметры.

Рассмотрим подробно, какие параметры для создаваемого договора можно задать в шаблоне.

18.15.1. Шаблон имени

Шаблон имени задает имя договора сразу после создания, при пустом поле сразу после создания договор называется New contract.

Шаблон имени может включать буквы, символы и следующие подстановки:

  • ${NS_name} -именнованный порядковый номер договора, name - имя именованного параметра, предварительно вам необходимо его создать в справочнике. Подстановка будет заменена порядковым номером договора.

  • ${NX} - порядковый номер договора, X - цифра. Подстановка будет заменена порядковым номером договоров такого типа, дополненным слева нулями до длины X; Данная подстановка является устаревшой, используйте ${NS_name}

  • ${Y2} - две последние цифры года создания договора;

  • ${Y4} - четыре последние цифры года создания договора;

  • ${time:<format>} - время создания договора, вместо <format> может быть строка макроса с yy - две последние цифры года, yyyy - четыре цифры года, MM - месяц, dd - день месяца. Полное описание допустимых макросов доступно здесь.;

  • ${NRX} - относительный порядковый номер договора, где Х - число разрядов в номере (аналогично ${NX}-подстановке). Относительный порядковый номер формируется следующим образом: сначала выполняются все прочие подстановки (например, текущая дата), затем находится договор в базе с таким "шаблоном" имени договора, берется последний относительный номер среди подобных договоров и увеличивается на единицу, после чего подставляется непосредственно в имя текущего создаваемого договора. Например, если шаблон имени определен как "D${Y4}${time:MM}${time:dd}-{NR4}", то при создании за текущие сутки (например, 01.01.2009) двух договор получим номера, соответственно, D20090101-0001 и D20090101-0002, а при создании нового договора по этому же шаблону на следующие сутки получим номер D20090102-0001.

Для модуля карт (создание договора по карте) доступны следующие макросы:

  • ${card:00000} - логин карты, количество нулей может быть любым и задает дополнение логина нулями слева до определенной длины;

  • ${card_series:00000} - серийный номер карты карты, количество нулей может быть любым и задает дополнение логина нулями слева до определенной длины.

При создании договора выбираются все договоры, шаблон имени которых совпадает с данным, далее определяется последующий порядковый номер и создается имя договора. Имя договора может и не содержать номера.

18.15.2. Лимит, лицо, режим, время жизни, статус

Второй ряд элементов управления позволяет установить параметры:

  • лицо (юридическое и физическое) - тип договора;

  • режим (дебет и кредит) - режим обсчета;

  • лимит - минимальный остаток на счете;

  • время жизни - количество дней, в течении которых будет существовать договор. При этом 0 означает неограниченный срок (пока не будет закрыт вручную). Договор будет создан с указанной датой закрытия. Данный параметр можно использовать для создания карт с ограниченным сроком действия. Т.к. после активации карточки создается договор, он будет создан с проставленной датой закрытия;

  • статус (подключен, отключен, закрыт, приостановлен) - выбор статуса при создании договра.

18.15.3. Модули

На вкладке Модули указываются подключаемые к договору модули. Каждый подключаемый модуль должен быть добавлен в список, после чего для него возможно указание выполнения некоторых дополнительных действий. Как-то: добавление логинов, типов счетов и т.п. Также возможно указание разрешенных услуг для модулей, в которых они используются.

18.15.4. Прочие параметры

Прочие параметры, устанавливаемые на вкладках правее вкладки Модули:

18.15.5. Создание договора по шаблону

Для создания нового договора выберите пункт меню Договор=>Новый договор. В появившемся окошке выберите базовый шаблон и дату заключения договора.

При выборе некоторого шаблона договора можно вручную изменить шаблон его имени, отметив поле "Вручную". Причем вводить можно не только конкретное имя нового договора, но и изменять текущие макроподстановки (фактически создавать новый шаблон имени). Это удобно в том случае, если имя договора не генерируется системой, а по тем или иным причинам заранее известно, однако необходимо сохранить внутренние настройки шаблона договора.

Также договор можно сразу создать как субдоговор для какого-либо супердоговора. Для этого следует отметить поле "Создать договор как СУБДОГОВОР для ..."

... выбрать тип баланса для данного договора, а также непосредственно сам супердоговор (нажав на >>>), вкладка которого должна быть предварительно открыта.

18.16. Субдоговоры

Биллинг позволяет выстраивать договоры в иерархии. При этом в вершине иерархии устанавливается супердоговор, а подчиненными к нему - субдоговоры. Каждый субдоговор является полноценным договором во всех остальных отношениях: к нему могут быть подключены модули, назначен тарифный план, установлены параметры.

Субдоговора различаются на два типа: с зависимым балансом (зависимые субдоговора) и независимым балансом (независимые субдоговора). Выбор режима субдоговора производится при его подключении к супердоговору.

18.16.1. Добавление субдоговоров

Для выстраивания иерархии договоров необходимо либо выбрать для добавления субдоговор в супердоговоре, либо в будущем субдоговоре выбрать супердоговор (см. снимки экрана ниже). Супер и субдоговор должны быть открыты во вкладках. При выстраивании иерархии необходимо выбрать тип отношения - зависимый, либо независимый баланс.

При этом вкладка Иерархия договоров меняется следующим образом для супердоговора и субдоговора. Обратите внимание, что тип зависимости указывается буквой рядом с именем субдоговора в списке субдоговоров супердоговора и в дереве субдоговора строкой з.субдог или н.субдог.

При присоединении/отсоединении договора его баланс пересчитывается в соответствии с текущим статусом. Таким образом любые два договора в любой момент можно выстроить в иерархические отношения, либо вернуть в независимое состояние. Для быстрого перехода в субдоговор из супердоговора можно использовать двойной клик в списке субдоговоров.

18.16.2. Зависимые субдоговоры

Все зависимые субдоговоры супердоговора имеют единый баланс со своим супердоговором.

В балансе субдоговора входящий остаток на начало месяца всегда равен нулю. Приход единого баланса супердоговора и субдоговоров равен сумме приходов супердоговора и его субдоговоров. Расход единого баланса равен сумме расходов супердоговора и его субдоговоров. Наработка единого баланса равна сумме наработок супердоговора и всех субдоговоров.

При принятии решении о доступе пользователя к услуге по субдоговору используется остаток на едином балансе и лимит субдоговора.

При изменении статуса супердоговора изменяются статусы его зависимых субдоговоров.

18.16.3. Независимые субдоговора

Независимый субдоговор имеет свой собственный баланс, его приходы/расходы/наработка отделены от супердоговора. Субдоговоры с независимым балансом позволяют разделять несколько видов сервиса для одного клиента, каждый из которых блокируется отдельно и имеет свой счет. При занесении прихода в супердоговор с независимыми субдоговорами возможно произведение распределения прихода по супердоговору и независимым субдоговорам. По умолчанию сначала гасится задолженность супердоговора, затем поочередно субдоговоров. Распределение суммы может быть скорректировано в таблице.

В зависимости от режима баланса супердоговора и независимых субдоговоров при оценке задолженности берется либо баланс, либо сальдо. Распределение наработки может быть произведено и после занесения прихода оператором биллинга путем нажатия кнопки Перенос средств в любой из панелей баланса договора.

Для вывода баланса вместо сальдо для независимых договоров в режиме кредит в в конфигурации сервера необходимо указать флаг:

# При занесении расходов, показывать баланс, а не сальдо для кредитовых договоров
client.gui.payment.show.balance.for.credit.contract=1

После выбора распределения средств между супердоговором и субдоговорами в супердоговор заносится расход, а в субдоговоры - приходы. Типы расхода и прихода должны быть определены в справочниках как нередактируемые и указаны в конфигурации сервера следующим образом:

transfer.payment.type=<код типа платежа, используемого для переноса средств>
transfer.charge.type=<код типа расхода, используемого для переноса средств>

Перенос средств доступен также через Web-интерфейс пользователя.

В модуле телефонии (Phone) субдоговоры с независимым балансом несут дополнительную функцию организации тарификации по агентской схеме, когда звонки и наработка по одному и тому же поинту, добавленному в супердоговор, относятся либо к супердоговору, либо к одному из его независимых субдоговоров.

При изменении статуса супердоговора статусы его независимых субдоговоров не изменяются, однако это поведение может быть изменено опцией конфигурации сервера биллинга independ.subcontract.status.change=1.

18.17. Переоформление договоров

Типовая операция, подразумевающая закрытие старого договора определенной датой с переносом всех его свойств на новый договор следующим днем от той даты. При этом в новом договоре указывается новое название организации, реквизиты.

Для переоформления договора откройте карточку договора, выберите кнопку Переоформить договор в общей панели инструментов либо в меню Договор. В открывшемся диалоговом окне выберите дату, с которой будет открыт новый договор и шаблон, на основании макроса имени которого будет сгенерировано имя нового договора.

После нажатия Ok старый договор будет закрыт, новый открыт и на него будут перенесены все опции старого с новой даты. Как то: логины, адреса, услуги, абонплаты и пр.

18.18. Удаление договоров, архив договоров

Для удаления договора следует его открыть и нажать на кнопку Удалить договор. После чего нужно ответить на вопрос: удалять его безвозвратно или в архив.

После удаления в архив договор будет сериализован в формат XML, сжат в архив ZIP и выложен в папку ..BGBillingServer/archive. После чего данные из базы будут удалены.

Для автоматического удаления договоров зайдите в Сервис=>Настройка=>Менеджер договоров и на вкладке Правила для удаления укажите правила, по которым будет удаляться договор. Правила делятся на два типа:

  • по времени - устанавливается параметр срок - период в месяцах, прошедший с момента закрытия договора( это вторая дата у периода действия договора ). Также можно установить фильтр по группам;

  • по сумме - устанавливается сумма - минимальный остаток на счете, после которого договор будет удален, срок - период в месяцах, в течении которого не было движения по счету. Движением по счету считается наличие прихода, наработки или расхода.

Очень желательно поделить все ваши договоры по группам: например Карточки, Организации и т.д. Это позволит вам более гибко устанавливать правила удаления, не рискуя удалить не те договоры.

После добавления нужных правил добавьте задачу удаления в планирощике заданий "Удаление старых договоров". Установите временные критерии запуска задачи.

Рекомендуется ставить эту задачу на ночное время, чтобы днем не загружать БД. В параметрах задачи укажите значения:

max_balance=20
max_closed=10
email=bill@bill.ru
#подкаталог для архивирования
#folder=card

Значение параметров max_balance - максимальное количество договоров, удаляемое за один раз по правилам по сумме, max_closed - по времени, email - адрес, на который будет послан отчет с перечнем удаленных договоров, если таковые имелись.

Тема приходящего письма: "These contracts were deleted!".

Для того, чтобы планировщик смог отсылать письма не забудьте указать в настройках сервера параметры E-Mail. Все автоматически удаляемые договоры помещаются в архив договоров. Для просмотра архива используйте вкладку Сервис=>Настройка=>Менеджер договоров=>Управление архивом.

С помощью фильтра можно выбирать время создания файла. Выбрав строку и нажав кнопку Восстановить договор из архива, вы можете восстановить договор из файла в базу данных. Если восстановление прошло успешно, файл будет удален из архива.

19. Тарифные планы

19.1. Общие сведения

Тарифный план задает стоимость услуги в какой-либо момент времени. Кроме того, в нём могут быть указаны параметры сервиса, опции тарификации. Тарифный план представляет собой дерево, в котором определяются одно или несколько модульных поддеревьев, задающих правила тарификации в экземплярах модулей.

Следует понимать, что тарификатор каждого модуля реагирует только на свое "поддерево" в тарифе, установленном для договора и игнорирует поддеревья других модулей. В зависимости от удобства использования модульные поддервевья могут собираться как в едином тарифе, так и разбиваться по нескольким.

Например, если у вас в системе есть линейка DialUP-тарифов с разной абонплатой и стоимостью часа, вы можете объединить модульные поддеревья DialUP и NPay-модулей, указывая в договоре только один тариф. Но, в то же время, те же договоры могут быть подписаны на разные Voip-тарифы, для которых целесообразно создать отдельную линейку и указывать в договоре 2 тарифа: DialUP+Абонплата и Voip.

Тарифные планы могут быть глобальные (созданы в справочнике тарифных планов и могут использоваться всеми договорами) и персональные (созданы в конкретном договоре) .

Для того, чтобы создать глобальный тарифный план, зайдите в меню Справочники=>Тарифные планы. Перед вами откроется окно со списком всех тарифных планов в системе, который можно отфильтровать по ряду критериев:

1) По названию;

2) по используемости;

3) по модулям;

4) по меткам.

Также можно видеть ряд статистических данных по тарифам: сколько договоров использует каждый тариф, сколько из них активных, сколько тарифов-наследников. В случае, если имеется сложный тариф с множеством услуг и условий и необходимо создать похожий, отличающийся незначительными изменениями, то можно воспользоваться кнопкой копирования выбранного тарифа. Она расположена над таблицей со списком тарифов.

Метки предназначены для удобной каталогизации имеющихся тарифов, которых со временем может скопиться огромное множество. Редактор меток доступен по нажатию кнопки P в фильтре по меткам.

Добавление/изменение/удаление меток осуществляется через контекстное меню. Изменение положения меток осуществляется перетаскиванием мышью.

Для добавления нового тарифного плана нажмите кнопку Новый элемент на стандартной панели инструментов.

Новый тарифный план создается с пустым деревом. Во вкладке Основные настройки находятся основные параметры тарифа. Для изменения названия тарифного плана введите новое имя в поле сверху .Также есть галочка, обозначающая используется тариф или нет.

Фильтр по договору используется при добавлении тарифного плана для некоторого договора (см. здесь). Тариф будет отображаться в списке возможных для добавления тарифов к данному договору только в том случае, если удовлетворяет выбранному фильтру. Лицо - тариф будет доступен, соответственно, для любых договоров, только для физических лиц или только для юридических лиц. Маска - тариф будет доступен только, если имя договора удовлетворяет заданной маске договора. Группы - тариф будет доступен, если договор входит хотя бы в одну из выбранных групп.

В разделе Метки можно назначить тарифу одну и более меток, по которым его в дальнейшем возможно отфильтровать.

Для добавления в тариф возможности тарификации услуг определенных модулей необходимо добавить модульные поддеревья, перейдя на вкладку Дерево -> Управление поддеревьями.

Слева расположен выпадающий список экземпляров модулей, правее - кнопки создания поддерева для модуля, либо удаление. Далее располагается список тарифных планов, у которых уже есть поддеревья для выбранного модуля, которое можно расширить.

19.2. Редактирование тарифного поддерева

Для добавления в узел дерева дочерних элементов нажмите по нему правой клавишей мышки, выберите Добавить и выберите нужный тип узла. На рисунке показано, как в модуль DialUp добавляется узел Услуга.

А вот вид дерева после добавления узла:

Для того, чтобы редактировать узел нажмите правой кнопкой и выберите в меню Редактировать. Для узла отобразится специфичный для него редактор. Ниже изображен редактор для узла типа "Услуга". После завершения редактирования (в нашем случае, это выбор услуги) необходимо нажать кнопку с галочкой для сохранения результата, либо с красным крестиком, если результат не нужно сохранять. В некоторых узлах вместо данных кнопок реализованы кнопки Ок и Отмена.

Во многих узлах позиция дочернего узала не имеет значения. Но иногда она важна. Для смены положения узла в родителе нужно в меню узла выбрать пункты Двинуть вверх или Двинуть вниз.

Положение узла значимо, например, для временных фильтров. Если цена будет найдена в одном фильтре, следующий уже не будет просмотрен. Поэтому можно располагать самые жесткие ограничения (праздники, например) первыми, а остальные после них.

Для удаления узла выберите Удалить узел в контекстном меню узла.

Тарифные деревья поддерживают возможность поиска по отображению. Для поиска воспользуйтесь текстовой областью над деревом, кнопками Найти и Найти следующее. Найденные узлы подсвечиваются синим цветом. Если вхождений больше нет, дерево свернется.

В ходе правки тарифное дерево может принимать неконсистентные состояния. Например, вы удалили узел с какой-то стоимостью и ещё не добавили новый. При этом в этот момент дерево не пригодно для тарификации.

В модулях Inet, NPay кэшированное в памяти тарифицирующего приложения дерево не перечитывается до тех пор, пока не будет передано событие. Событие передаётся выбором пункта Оповестить об изменениях в корневом узле модульного подерева. О внесённых в поддерево изменениях сигнализирует оранжевый цвет корневого узла.

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

В оставшихся модулях считывание производится при первом обращении к дереву после его правки. Т.е. при правке дерева необходимо стараться уменьшить время, когда оно пребывает в неконсистентном состоянии. Отчасти проблема сглаживается тем, что для тарификации реального времени (DialUp-модуль) дерево кэшируется в момент авторизации соединения и далее не изменяется даже, если будет поправлено. Т.е. правка дерева может вызвать только временные проблемы с авторизацией соединений. Для периодической тарификации (IPN, RSCM и т.п.) дерево также загружается в момент начала обсчёта и далее используется. Т.е. проблема может возникнуть только, если на начало периодической тарификации дерево некорректно, повторый переобсчёт проблему устраняет.

Оранжевый цвет корневого дерева также может информировать об ошибках в структуре его хранения. В этом случае вам следует выбрать в контекстном меню корневого узла пункт Исправить ошибки, после чего закрыть тариф, открыть снова и проверить порядок узлов.

19.3. Расширение тарифных планов

Механизм расширения позволяет создать модульное поддерево на основании существующего поддерева аналогичного модуля из другого тарифа, добавив в него новые узлы. Например, с его помощью можно переопределять цены. Рассмотрим для примера "Тариф1" и "Тариф2", модульное поддерево экземпляра модуля "INET" которого получено путём расширения модульного поддерева первого тарифа.

Для расширения поддерево необходимо создавать с помощью кнопки расширения, слева от которой расположен список тарифов, содержащих поддерево экземпляра модуля. Название тарифа с поддеревом - предком отображается в квадратных скобках в корневом узле.

Узлы дерева-предка всегда выделены серым цветом и недоступны для редактирования. Узлы дерева-потомка всегда располагаются после узлов предка. Так же они обрабатывают позже тарифный запрос. При этом они могут перетирать значения параметров ответа тарифного запроса, установленные предыдущим узлом предком. Например, в предыдущем примере при использовании тарифа "Тариф2" стоимость мегабайта типа трафика "Входящий" будет стоить 1 рубль.

В базовом поддереве могут быть и не определены цены, можно использовать его просто как каркас для построения конечных тарифов. В этом примере в тарифе "Тариф1" можно было не размещать узел типа "Стоимость".

19.4. Персональные тарифные планы

В договоре могут быть определены собственные (персональные) тарифные планы.

Для создания персонального тарифа необходимо перейти на вкладку Персональные тарифы и нажать кнопку Добавить в единой панели инструментов сверху.

Далее для редактирования дерева тарифа строку с тарифом нужно выбрать в таблице персональных тарифов и нажать кнопку Открыть дерево в нижнем правом углу. Правила редактирования дерева персонального тарифа не отличаются от редактирования дерева глобального тарифа. Персональный тариф может быть расширен от глобального, либо создан с нуля.

Для закрытия персоанального тарифа - кнопка Закрыть дерево в правом нижнем углу.

19.5. Порядок просмотра тарифных планов

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

Алгоритм 1:

1. ищется тариф, содержащий модульное поддерево экземпляра модуля среди персональных тарифов договора, используется фильтр по дате, сортировка по позиции тарифа; если найдено - то 3;
2. ищется тариф, содержащий модульное поддерево среди глобальных тарифов договора, используется фильтр по дате, сортировка по позиции тарифа;
3. в найденном модульном поддереве ищется цена на все услуги, которые нужно тарифицировать; если цена какой-то услуги там не найдена, то ошибка тарификации.

При такой схеме в один день в договоре может активно действовать только один тариф, содержащий модульное поддерево экземпляра модуля. Если таких тарифов окажется несколько, то будет выбран первый из них в соответствии с алгоритмом. Если в найденном тарифе не окажется цен на все требуемые услуги - получится ошибка тарификации, другие тарифы просматриваться не будут.

Алгоритм 2:

1. выбирается список тарифов, содержащих модульное поддерево экземпляра модуля среди персональных тарифов договора, используется фильтр по дате, сортировка по позиции тарифа;
2. выбирается список тарифов, содержащих модульное поддерево экземпляра модуля среди глобальных тарифов договора, используется фильтр по дате, сортировка по позиции тарифа.

Для каждой из тарифицируемых сущностей (услуга, тип трафика) ищется последовательно цена в списках 1 и 2. Как только находится тариф с ценой - поиск прекращается.

В ряде модулей (Phone, NPay) алгоритм поиска тарифа отличается от перечисленных здесь и описан отдельно.

19.6. Стандартные узлы тарифных планов

Принцип работы дерева заключается в передаче запроса, содержащего опеределенные параметры, внутрь дерева. Параметры запроса отличаются для разных модулей. Типичными параметрами являются: время, код услуги.

Каждый узел дерева получает запрос и обрабатывает его, помещая результаты обработки в ответ и модифицируя запрос. В результате обработки узел может как пропустить запрос внутрь для всех своих подузлов, так и не пропускать его. Запретить обработку запроса следующим за ним узлом узел не может.

Вид поддеревьев и состав используемых узов различен для каждого модуля и описан в его документации. Некоторые узлы специфичны для модуля, мы рассмотрим здесь универсальные узлы, встречающиеся в тарифах всех модулей. Ниже перечислены основные типы узлов, встречающиеся во всех модулях:

19.6.1. Услуга

Редактор узла и узел в тарифе выглядят так:

Узел выступает фильтром по услуге и передает запрос каждому из потомков только, если услуга из тарифного запроса совпадает с указанной в узле.

19.6.2. Мультиуслуга

Редактор узла и узел в тарифе выглядят так:

Узел выступает фильтром по услуге и передает запрос каждому из потомков только, если услуга из тарифного запроса совпадает с одной из указанных в узле. Действие узла полностью идентично узлу Услуга за исключением возможности указания нескольких услуг в одном узле. Эта возможность может быть удобна при необходимости указания одинаковой цены на несколько услуг, либо выдачи единой квоты по трафику (IPN, DialUP модули).

19.6.3. Период

Редактор узла и узел в тарифе выглядят так:

Параметр "время" из тарифного запроса попадает в указанный период. Если одна из дат не указана, то она берется бесконечной (в прошлое или будущее). Узел период с неуказанными обеими датами просматривает дочерние узлы в любом случае.

Основное назначение узла - изменение стоимости в тарифном плане с какой-либо даты. Ниже приведен пример, как изменить стоимость услуги Dial-Up(время) с 1 сентября 2009 года.

В период можно помещать также секции тарифного дерева, регулируя, когда отрабатывает тот или иной блок. В приведенном ниже примере с 1 сентября увеличивается объем предоплаченного трафика в тарифе модуля DialUp.

19.6.4. Фильтр по времени

Редактор узла и узел в тарифе выглядят так:

Для редактирования условия нужно вызвать редактор, сделав двойной клик по строке условия в редакторе, либо нажав кнопку Добавить. Набор масок дней, часов, дней недели и месяцев, перечисленных в условии, должен выполнятся весь, т.е. чтобы сработало условие, нужно совпадение всех масок. При вводе масок условия часы могут принимать значения от 0 до 23, дни недели от 1 до 7, дни месяца от 1 до 31, месяцы от 1 - 12. При вводе можно использовать символы "-" ( интервал со входящими концами ) и "," ( перечисление ). Для удобства ввода можно использовать записи * (будут выведены все значения), а также */n (n - целое число, все что делится на n, например */2 - 0, 2, 4, 6... ), либо *\n ( n - целое число, все что не делится на n).

Узел выступает фильтром тарифного запроса, запрос пропускается к обработке в узлах-потомках только, если параметр "время" в запросе совпадает хотя бы с одним набором условий узла. Фильтр позволяет определять в тарифах различную стоимость услуги по времени суток, дням недели, месяца. Пустой набор ограничений означает отсутствие фильтра по времени. Узел пропускает в себя запрос, только если перед ним в том же узле-предке не стоял другой фильтр по времени, либо Фильтр по типу времени, уже пропустивший запрос в себя (принявший запрос). Данный принцип позволяет делать наборы ограничений по умолчанию. Например, так можно определить стоимость в будние дни и праздники для модуля DialUp.

В приведенном выше примере во втором наборе ограничений не указаны явно дни с 1 по 5, узел обрабатывает запросы, не попавшие в первый набор ограничений. Для данного случая метод не дает ощутимой выгоды, однако при необходимости указывать многочисленные праздничные дни он удобен. Обратите внимание, что следующий пример уже не будет работать аналогичным образом. Т.к. у узлов разный предок.

Во втором примере все запросы будет принимать второй пустой набор ограничений. Т.к. у узлов разный узел-предок. Данную ситуацию (желание задать цены на будние дни с периодом) корректно было бы разрешить так:

19.6.5. Фильтр по типу времени

Редактор узла и узел в тарифе выглядят так:

Действие данного узла абсолютно идентично Фильтру по времени, за исключением того, что сами маски определяются в справочнике типов времени. Это более удобно при большом количестве фильтров в тарифах разных модулей. Узлы данных типов абсолютно равноправны и могут быть использованы комбинированно. Например, описанный в предыдущей секции пример с исключающими масками может быть разрешен так:

Либо так:

При этом в типе времени Рабочие дни не указываются никакие маски.

19.6.6. Параметры тарификации

Редактор узла и узел в тарифе выглядят так:

Узел передает в ответной части тарифного запроса параметры тарификации:

  • максимальную длительность бесплатного звонка в секундах;

  • количество десятичных знаков после запятой в стоимость звонка (не имеет смысл устанавливать более, чем разрядность поля таблицы БД);

  • правила откругления длительности звонка.

Правила задаются в виде диапазонов длительностей звонка в секундах и кванта, до которого звонок округляется в данном диапазоне в большую сторону. На приведенном снимке звонки до минуты округляются до целой минуты, а далее идет посекундная тарификация. 0 секунд в верхней части диапазона означает отсутствие ограничений сверху.

Звонки до 10 секунд включительно считаются нулевой длительности. Стоимость звонка округляется до пятого знака, т.е., например 4.32344.

Параметр Учитывать округление при автор. действует только для Voip-модуля и позволяет выдавать клиенту длительность разговора с учетом округления длительности в большую сторону. Т.е., если сессии от 20 до 120 секунд округляются кратно 20, а человеку хватает денег на 83 секунды, то после авторизации RADIUS вышлет 80 секунд разрешенного времени.

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

19.6.7. Использовать карту зон

Редактор узла и узел в тарифе выглядят так:

Узел получает вызываемый номер из тарифного запроса, определяет по нему направление и зону и помещает их в тарифный запрос.

19.6.8. Зона

Редактор узла и узел в тарифе выглядят так:

Узел пропускает запрос внутрь только если установленная в запросе зона равна указанной в узле. Поле ввода текста в правой части и кнопка "+" позволяют быстро добавить отсутствующую зону в справочник. В запрос зона устанавливается узлом Использовать карту зон.

19.6.9. Часть префикса и Диапазон префиксов

Редактор узла и узел Часть префикса в тарифе выглядят так:

либо так для Диапазона префиксов:

Отличие двух узлов - в способе задания маски номера.

В Части префикса задается REGEXP-выражение, которое должно совпасть с начальной частью "остатка" номера.

В Диапазоне префиксов задается выражение вида <общий префикс>|<диапазоны>. Например в указанный выше диапазон можно переписать в виде: 34|72-73, где 34 будет являться общим префиксом. Общий префикс может быть и не указан. Если он указан, то как бы подразумевается для всех диапазонов после него. Начальная часть остатка номеров должна попасть в один из указанных диапазонов. При этом все диапазоны префиксов в узле должны быть одной длины.

Оба узела работают с параметром "номер", переданным в тарифном запросе. При этом разбор номера идет по частям, начиная с начальных символов. Каждый узел, в который попадает телефон, сравнивает начало номера с шаблоном в узле.

Если совпадение произошло, совпавшее начало номера как бы "откусывается" и узел передает остаток номера на обработку внутрь себя, где процесс "откусывания" продолжается до нахождения цены звонка и направления. После совпадения части префикса с номером, в следующих, соседних в этом же предке, узлах запрос будет пропущен.

У каждого узла может быть установлено направление и зона. Если в совпавшем узле указано направление, либо зона, они подставляются в ответ тарифного запроса.

Рассмотрим для примера, как происходит разбор телефона 73472555555 в указанном ниже тарифе. В нем используется комбинация этих двух узлов, т.к. они являются взаимозаменяемыми.

1) Ветка 7 Россия - начало совпадает с 7 => 7 отбрасывается и далее передается 3472555555

2) аналогично ветки 3 и 4

3) в ветке 72 определяется направление звонка

4) в ветке Минута исходящего - цена минуты разговора.

Ветки 3 и 4 просто прописывают данные в проходящий через них тарифный запрос.

После выхода из ветки 7 звонок будет помечен как обработанный после прохождения его через все дочерние узлы ветки 7. Все ветки после 7 не пропустят запрос внутрь себя.

Таким образом достигается высокая эффективность обработки запросов.

Рассмотрим еще один пример использования узлов:

В приведенном выше примере префиксы 73472-73474 и 73476 будут отнесены к Уфе, а префиксы 7351-7353 к Челябинску.

19.6.10. Стоимость минуты

Редактор узла и узел Стоимость минуты в дереве выглядят так:

Узел используется в голосовых модулях. При прохождении запроса через узел в ответной части узел размещает стоимость, указанную в нем. При установке опции по умолчанию цена переустанавливается только, если в запросе еще не установлена цена, либо она установлена также узлом со свойством по умолчанию в дереве-предке (тариф расширен). Если опция не установлена, цена будет переопределена при прохождении тарифного запроса через узел в любом случае.

19.6.11. Множитель цены

Редактор узла и узел Множитель цены в дереве выглядят так:

Узел используется для умножения цены, установленной узлом Стоимость минуты на определенный коэффициент. Например, используя данный узел, можно быстро создать тариф с НДС для физ. лиц, расширив базовый тариф и добавив в конце дерева узел с умножением.

19.6.12. Элемент каталога

Редактор узла и его внешний вид в дереве представлен на рисунке ниже.

Используется для группировки различных узлов по определенным критериям. Суть узла аналогична понятию каталог в файловой системе.

19.7. Тарифные опции

Доступны в Справочники => Тарифные опции.

Тарифные опции позволяют расширить логику тарифа. Их можно обозначить как дополнительные услуги, которые клиент может подключить из Web-интерфейса на определенный период за определенный расход. Тарифные опции можно также активировать и из клиента биллинга.

На первой закладке указываются тарифные планы, при которых можно будет активировать опцию.

На второй - указываются режимы активации опции.

Период режима активации - это период, когда возможно активировать опцию. Опция активируется на определенный период. Количество 0 означает что опция будет активирована бесконечно. При этом появляется возможность деактивировать опцию.

Режимы периода: часов - опция активируется с текущего момента на указанное количество часов; часов со следующего - c 00:00 следующего часа на указанное количество часов; часов с текущего - с 00:00 текущего часа на указанное количество часов; дней - с текущего момента на указанное количество дней; дней со следующего - с 00:00:00 следующего дня до (не включая) 00:00:00 через указанное количество дней; дней с текущего - с 00:00:00 текущего дня. Аналогично для месяцев и недель.

Внимание

Следует учитывать, что в модулях DialUp и IPN наработка хранится по часам, поэтому, если в зависимости от тарифной опции меняется цена, то активация тарифной опции не должна быть в режиме "часов (с текущего момента)" (как исключение, для модуля Dialup можно установить разрыв соединения), а также для модуля Dialup не должна быть в режиме "с текущего часа/дня/недели/месяца", чтобы цена прошедшего времени не изменялась. Если же в модуле Dialup в зависимости от тарифной опции выполняется только посылка CoA, то режим "часов (с текущего момента)" может быть активирован.

Если количество часов (дней/месяцев/недель) указано 0, то опцию можно будет деактивировать. Режимы деактивации: моментально - с момента отработки заброса; до конца дня - до (не включая) 00:00:00 следующего дня; до конца недели - до (не включая) 00:00:00 понедельника следующей недели; до конца месяца - до (не включая) 00:00:00 первого числа следующего месяца. В этом случае также можно указать возможность реактивации: если режим деактивации установлен не "моментально" и опция была деактивирована, а время окончания еще не наступило, то клиент сможет реактивировать тарифную опцию.

Если сумма в поле Снять расход больше нуля, то при активации опции проверяется, баланс - сумма >= лимита. Если средств не достаточно, опция не активируется, иначе - перед активацией снимается расход указанного типа.

На третьей закладке указываются зависимости редактируемой опции от других.

Если опция зависит от других опций, то все эти опции должны быть активированы в тот период, на который активируется опция.

Если опция не совместима с какими-либо другими опциями, то ни одна из этих опций не должна быть активирована в период активации редактируемой опции.

Периоды пересечений сравниваются с точностью до секунды.

В Web-интерфейсе клиент выбирает опцию и режим активации для нее.

На отдельной странице можно увидеть опции, период действия которых истек.

20. Объекты

Понятие объекта введено в систему для упрощения учета сложных мультисервисных договоров. Объекты никак не влияют на обсчет договоров. Объект представляет из себя именованную сущность с набором параметров и привязанных сущностей из различных модулей. Например, возможно заведение в договоре нескольких точек подключений, к каждой из которых будет привязан свой диапазон адресов из IPN-модуля, установлен собственный адрес и тип точки. Использованию объектов предшествует заполнение справочников (меню Справочники=>Объекты). Параметры объектов могут быть следующих типов: Адрес, Текст, Список, Дата.

В меню Значения списков должны быть определены допустимые значения для каждого спискового параметра.

В типах объектов определяются существующие в системе типы объектов и макрос их именования. В макросе именования могут быть подставлены следующие значения: ${text:<код параметры>} ${address:<код параметра>} ${list:<код параметра>} ${date:<код параметра>}.

Здесь же определяются привязанные к типу объекта модули, их свойства будут доступны в редакторе объекта в договоре.

После определения типов и параметров необходимо произвести привязку параметров к типам.

Для добавления объекта в договор перейдите на вкладку Параметры=>Объекты в договоре.

Для добавления объекта выберите Добавить в верхней панели инструментов. Далее выбирается тип объекта и открывается его редактор.

После чего откроется редактор для занесения параметров объекта.

Далее вводится название объекта, либо поле оставляется пустым и нажимается Применить, после чего имя объекта формируется на основании макроса.

Привязку сущности модуля к объекту можно осуществить двумя способами:

1) Для сопоставления объекту сущностей модуля в каждом модуле предусмотрено доп. поле.

2) В редакторе объекта доступны редакторы сущностей модулей, перечень которых указан в свойствах объекта

Каждая добавленная на закладке сущность модуля будет автоматически отнесена к выбранному объекту.

На вкладке Сводная отображается сводная таблица по всем подключенным к объекту сущностям модулей.

Возможно перенести объект с текущего договора на другой открытый. Для этого необходимо выбрать объект в таблице, вызвать всплывающее контекстное меню кликом правой кнопки мыши и активировать пункт Перенести на другой договор.

Внимание

В текущей версии при переносе объекта производится перенос только самого объекта и его параметров. Сущности модулей отвязываются от объекта, перенос наработки также не производится. В последующем функционал будет дореализован.

Поиск договора может осуществляться по параметрам привязанных к нему объектов.

21. Web-интерфейс пользователя

21.1. Общие сведения

Web-страница пользователя предоставляет клиентам полную информацию о состоянии счета, детальные отчеты по всем модулям договора. Через персональный кабинет пользователь может также изменять пароли, получать и выставлять себе счета, производить оплату через различные платежные системы и т.п. в зависимости от состава установленных модулей и плагинов.

По умолчанию страница статистики доступна по адресу: http://<адрес сервера биллинга>:8080/bgbilling/webexecuter. Путь контекста (/bgbilling) может быть исправлен в файле конфигурации BGBillingServer/data/data.properties переменная context.path, в т.ч. установлен пустым (context.path=/).

При входе клиента на эту страницу происходит его перенаправление на страницу авторизации.

21.2. Настройка доступа к статистике

По умолчанию клиентам разрешена авторизация по номеру договора и паролю статистики, пароль статистики изменяется на вкладке Web=>Пароль статистики договора. Для смены пароля наберите его в текстовой области, либо установите галочку авто и нажмите ОК.

В таблице отображается лог смен пароля, его можно сортировать по дате по убыванию и возрастанию.

Текущий пароль статистики, установленный после создания договора, можно посмотреть в полной карте договора (вкладка Карточки=>Полная карта в договоре).

По умолчанию отображается примерно следующая страница пользователя. Содержимое меню может пополняться по мере подключения модулей и плагинов к системе.

Параметры авториазации на странице статистики задается в конфигурации сервера биллинга.

web.auth.modes=0:1

Данное значение стоит по умолчанию и обозначает, что разрешена авторизация на странице статистики по номеру договора + паролю (вкладка Пароль в карточке договора).

Также есть режим авторизации, который использует текстовый параметр договора в качестве логина:

web.auth.modes=0:2
# Код параметра договора, значение из которого будет использоваться в качестве логина.
web.auth.contract.text.parameter=<код параметра>

Страница авторизации пользователя формируется шаблоном login.xsl. В стандартной поставке шаблон содержит только форму авторизации по номеру договора (либо текстовому параметру договора) и паролю.

Внимание

При правке этого шаблона не забудье, что он перетирается при обновлении системы.

Клиент работает на странице статистики до нажатия пункта меню Выйти, либо до истечения таймаута. При выходе со страницы статистики клиент перенаправляется на страницу, задаваемую опцией.

web.exit.redirect=about:blank

По умолчанию это пустая страница, но вы можете разместить здесть URL страницы провайдера.

Сервер определяет тип авторизации по передаваемому в форме авторизации параметру midAuth=<коду модуля>. Если параметр отсутствует - авторизация идет по номеру договора (либо текстовому параметру договора) + паролю доступа к статистике.

Пример 1.5. Пример авторизации по логину

Предположим что в системе существует модуль DialUP с кодом 21. Для того чтобы разрешить авторизацию через его логины с паролями нужно добавить опцию.

web.auth.modes=0:1;21:1

Теперь раскомментируйте вторую форму авторизации в login.xsl.

<form method="post" action="webexecuter">
<input type="hidden" name="midAuth" value="21"/>
 <table align="center" width="300px" class="filter" style="margin-top:20px;">
  <tr>
   <th align="left">Логин DialUP:</th>
   <td><input class="logon" type="text" name="user" SIZE="15"/></td>
  </tr>
  <tr>
   <th align="left">Пароль DialUP:</th>
   <td><input class="logon" type="password" name="pswd" SIZE="15"/></td>
  </tr>
  <tr>
   <td></td>
   <td><input type="submit" value="Вход" style="width: 100%; border: 1px solid #404040;"/></td>
  </tr>
 </table>
</form>

Теперь клиенту будет предлагаться два режима авторизации.

Аналогично можно добавить авторизацию по логину и паролю Voip-модуля. Возможно в midAuth-параметре формы передавать несколько модулей через запятую, 0 - код модуля ядра. При этом будет осуществлен последовательный поиск в указанных модулях. Модуль должен быть разрешен в web.auth.modes.

Так же для модуля Dialup есть отдельный режим авторизации по ip-адресу сессии. Пусть 21 - это код модуля Dialup, тогда этот режим настраивается так

web.auth.modes=0:1;21:2

Где 2- означает авторизацию по ip-адресу сессии. При этом сравнивается http-заголовок с ip-адресом переданный в http-запросе и Ip-адрес сессии абонента.

Имя http-заголовка, в котором хранится ip адрес, задается параметром

header.name.remote.addr=

в конфигурации сервера.

При ошибке авторизации отображается страница, задаваемая шаблоном error.xsl. Скорректируйте в данном шабkоне номер телефона вашей техподдержки. Если вы используете дополнительные режимы авторизации кроме договора, скорректируйте выводимый текст.

21.2.1. Восстановление пароля

С помощью системы восстановления пароля пользователь может произвести отправку пароля на E-Mail.

В поле Номер договора пользователь должен ввести номер своего договора, а в поле E-mail - почтовый адрес, который должен совпасть со значением текстового параметра договора, содержащим E-Mail-адрес для восстановления пароля. Код этого параметра указывается в конфигурации сервера биллинга contract.password.forgot.email.param.id=<числовой код параметра>.

При использовании функции восстановления пароля высылается письмо со ссылкой, перейдя на которую пользователь попадает на страницу смены пароля Web-статистики. Текст, тема письма и URL-сервера статистики задаются в конфигурации сервера биллинга.

21.2.2. Защита от подбора пароля

Если пользователь несколько раз в течение короткого времени введет неверный пароль, доступ временно блокируется с указанием времени, до которого вход запрещен. Это мера безопасности от подбора пароля Web-статистики.

Временные характеристики защиты могут быть настроены в конфигурации сервера. Переменная logon.counter.max задает максимальное количество неудачных попыток авторизации для договора подряд. После каждой попытки может быть установлен таймаут, базовый размер которого определяется переменной logon.timeout.period. После первой неудачи таймаут равен периоду, после второй - двум периодам, затем трем и т.п. Алгоритм увеличения периода задается переменной logon.timeout.action. После исчерпания logon.counter.max попыток авторизации договор блокируется на время logon.timeout.lock секунд.

Оператору биллинга на вкладке Web договора доступны функции мониторинга доступа к Web-статистике.

На вкладке Входы отображаются входы на Web-статистику. На закладке Ошибки - ошибки авторизации с отображением введенных логина и пароля. Кнопка Разблокировать позволяет досрочно открыть закрытый из-за превышения количества неудачных попыток доступ к статистике.

Счетчик обращений и лимит обращений - это защита от автоматизации пользователями получения информации о балансе (написание различных скриптов, запрашивающих статистику, что ведет к сильной загрузке сервера), возможно установление лимита на количество обращений к статистике HTTP-запросов параметром web.max.day.request.count в конфигурации сервера биллинга.

Кнопкой Сброс можно сбросить значение счетчика, также можно установить для каждого договора пользовательское значение, выбрав опцию Персональный, введя число в поле ввода и нажав Применить.

Обращением считается каждая перегрузка страницы статистики (переход по ссылке в меню, вывод данных отчета). При превышение количества обращений пользователь будет перенаправлен на страницу, формируемую шаблоном limit_error.xsl.

Введя код, пользователь сбрасывает счетчик обращений и может продолжать работу на странице статистики. Введение кода подтверждает, что это не бот и не программа.

21.3. Настройка страницы статистики

Для смены логотипа следует заменить файл BGBillingServer/webroot/img/logo.gif нужным логотипом. По умолчанию в дистрибутиве идет логотип оператора Synterra в качестве примера. Цветовую гамму Web-интерфейса можно поменять в стилевой таблице style.css.

Страницы Web-интерфейса пользователя собираются из XML-документа с использованием XSLT-шаблона. Каждый модуль и плагин помещает свои XSLT-шаблоны в каталог BGBIllingServer/webroot/xsl. Модифицируя их, вы можете настраивать оформление страницы пользователя. Главный шаблон - main.xsl.

Внимание

При каждом обновлении модуля и ядра XSLT-шаблоны перетираются.

Внимание

Начиная с версии 6.0 часть личного кабинета переведена на генерацию на основе JSP файлов. В дальнейшем планируется постепенный перевод всего ЛК. JSP файлы на основание которых генерируется ЛК распологаются в каталоге webroot/WEB-INF/jspf.

Web-интерфейс может работать в двух режимах: xml и html. Режим задается переменной web.mode конфигурации сервера биллинга. В xml режиме клиент получает XML-документ со ссылкой на XSLT-шаблон преобразования и браузер самостоятельно собирает страницу. В режиме html клиенту отдается собранная биллингом XHTML-страница.

Внимание

Выше описанный режим не распространяется на страницы генерируемые на основании JSP шаблонов

Достоинством первого метода является снижение нагрузки на сервер, а недостатком - не все браузеры смогут обработать такой ответ. Также подобный режим можно использовать для интеграции со сторонними приложениями

Параметр web.xslt конфигурации сервера - URL папки, где будут находиться ваши XSLT-шаблоны. При использовании режима xml адрес 127.0.0.1 следует заменить на адрес машины с сервером биллинга, доступный пользователям из внешней сети.

Внимание

В html- режиме при правке шаблонов установите опцию xslt.cache=0 в конфигурации сервера биллинга до окончания правок шаблонов и верните в 1 после её окончания.

Название пунктов меню в каждом модуле задаются в его конфигурации, например для ядра:

web.menuItem1=Новости
web.menuItem2=Уведомления
web.menuItem3=Просмотр баланса
web.menuItem4=Смена пароля на доступ к статистике
web.menuItem5=Смена тарифных планов
web.menuItem6=Тарифные опции
web.menuItem7=Карточки
web.menuItem8=Управление лимитом
web.menuItem9=Управление статусом
web.menuItem10=Дополнительные действия
web.menuItem11=Примечания

Перечень пунктов вы можете найти в документациях к модулям. Если название пункта меню не указано, берётся значение по умолчанию. Для того, чтобы заблокировать пункт меню нужно указать его название none. Например:

web.menuItem1=none

XSLT-процессор получает XML-данные от сервера и на основании шаблонов создаёт XML-страницу. Чтобы просмотреть XML-документ, на основании которого создаётся страница, установите режим работы Web-статистики в xml, либо добавьте к URL в браузере строку &ct=xml, далее вызовите страницу и сделайте просмотр её исходного кода.

Возможно добавление в XML-документ дополнительных данных по договору установкой опции в конфигурации сервера.

web.add.contract=1

Это создаёт дополнительную нагрузку на сервер биллинга, но позволяет разместить на странице пользователя дополнительную информацию, отсутствующую в стандартном дереве.

Таким образом на странице статистики можно разместить, например, некоторые параметры договора.

Начиная с версии 6.0 в системе доступен редактор web-меню, доступный из меню Сервис = Настройка = Редактор web-меню. Можно создать несколько меню, назначить созданные меню на договора и указать в шаблонах. Одно из созданных меню можно назначить как меню "по умолчанию". Если в редакторе не создано ни одного меню или ни одно из них не указано как меню "по умолчанию", то меню будет генерироваться автоматически, так же как это было в предыдущих версиях.

Редактор web-меню.

Добавление пункта web-меню.

Переименование пунктов web-меню.

Добавление группы.

Добавление плагинного пункта web-меню.

Переименование группы web-меню.

Назначение меню на договор.

Задание меню в шаблоне договора.

21.4. Новости

Отображаются на первой странице кабинета пользователя.

Для редактирования новостей зайдите в Сервис=>Настройка=>Редактор новостей. Нажмите кнопку Новый элемент, введите тему и текст новости. При неустановленном фильтре групп, новость будет отображена всем пользователям, иначе только выбранным группам.

Чтобы работали html-теги необходимо заключить новость в xml-теги <data></data>. В этом случае содержащаяся внутри информация должна быть правильным xml-документом, т.е все теги должны быть закрыты, все атрибуты должны быть в ""

<data>
Поздравляем всех с <b>ПРАЗДНИКОМ</b>!!!<br/>
Желаем счастья и т.д и т.п
</data>

После того как клиент зайдёт на свою страницу статистики он увидит справа от меню вашу новость.

21.5. Просмотр баланса, истории платежей, расходов и наработки

Меню Просмотр баланса отображает на выбранный месяц входящий и исходящий остатки на счету пользователя, приходы, расходы и наработку договора. Приходы и расходы отображаются с комментариями.

21.6. Смена пароля на доступ к статистике

Позволяет клиенту изменить пароль договора для доступа к статистике.

21.7. Смена тарифных планов

Биллинг поддерживает возможность смены тарифов пользователями через Web-интерфейс пользователя.

Процесс смены тарифа может быть изменён с штатной логики на любую другую путём обработки событий Смена тарифа по заданию пользователя и Запрос дат, с которых разрешена смена тарифа через Web. Примеры обработки данных событий вы можете посмотреть в WiKi.

Для предоставления пользователю смены тарифов необходимо установить для договора группу (группы) тарифных планов. Если хотя бы одна группа тарифных планов не указана, то смена их через Web-интерфейс невозможна. Группа определяет набор взаимозаменяемых тарифов договора. Обычно это линейка тарифов на одну услугу.

Рассмотрим случай наличия в системе 3х тарифных планов Тариф1..Тариф3. При этом переход между ними необходимо разрешить только в начале месяца. Предполагается что тарифы уже созданы в редакторе тарифных планов.

В Справочники=>Группы тарифов создадим группу с названием "Первая" и установим следующие параметры.

Кроме перечня разрешённых тарифов и момента, когда можно менять тариф, необходимо установить:

  1. Позиция, которую тарифные планы данной группы занимают в договоре;

  2. Количество дней, следующих после текущей даты, в которые может быть добавлено задание на переход. Например, если сейчас 20-е число месяца, в котором 30 дней и в данной опции стоит, что задания можно добавлять вперёд на 30 дней, то будут просмотрены даты от 20-го числа текущего месяца до 20 числа последующего. При этом будут выбраны даты разрешённых переходов. В данном случае подойдёт только 1-ое число последующего месяца. Если данный параметр установить в 60, то пользователь сможет генерировать задания за 2 месяца.

Также обратите внимание, что для каждого тарифа может устанавливаться начальная и/или конечная даты периода, когда эти тарифы видны в Web-интерфейсе пользователя и доступны для выбора. Это дополнительное средство обеспечения гибкости. Можно, например, сделать доступными некоторые из тарифов группы через некоторое время. Но это не имеет никакого отношения к возможности установки на какое-то число начала действия тарифа. Это только период, когда тарифы видны в списке выбора тарифов для смены.

Теперь необходимо установить в договор группу тарифов и скрипт поведения. Сделать это следует, открыв договор и щёлкнув на дереве Группа тарифов. Значение добавляется с периодом. На страничке Web-статистики пользователя должно появится меню Смена тарифных планов. В верхней таблице приведена история смены тарифов.

Обратите внимание, что система предлагает к смене только тарифы, входящие в установленные на договоре группы тарифов. Не разрешается переходить на неиспользуемые тарифные планы. После смены тарифа страничка примет следующий вид.

Также для пользователей имеется возможность отменить выбор тарифа для перехода будущим числом. Таким образом, можно отменить ошибочный переход. Обратите внимание, что если на событие смены тарифа выполняются какие-либо действия, то в событии отмены перехода (см. ниже) нужно это предусмотреть и корректно обработать. Как известно, событие смены тарифа отрабатывает в момент выбора тарифа (даже, если тариф начнёт действовать только в следующем месяце). Алгоритм обработки этой ситуации работает следующим образом:

  1. при смене тарифа сохраняется информация с какого тарифа_договора происходит переход (id строки из contract_tariff);

  2. на будущих тарифах в Web-интерфейсе есть кнопка отмены перехода на тариф (и указано для удобства на какой тариф откатится, ведь мы знаем предыдущий тариф);

  3. при нажатии на неё (после проверок на хаки) генерируется синхронное событие Отмены перехода на тариф;

  4. там можно обработать что угодно, имея ContractTariff "до" и "после";

  5. там же можно установить processed (аналогично смене тарифа), чтобы штатно не обрабатывалось;

  6. штатная обработка состоит в следующем: удаляем второй тариф (новый, который отменяем) и обновляем предыдущий, продляя дату до бесконечности (то есть "окрывая" его);

  7. после этого генерируются сразу два асинхронных события ContractTariffUpdateEvent и ContractTariffDeleteEvent для соответствующих потревоженных тарифов договора.

21.8. Тарифные опции

Тарифные опции позволяют клиенту изменять свойства сервиса или

21.9. Карточки

У абонентов есть возможность загружать на свой комьпютер карточки своего договора в формате PDF.

Загрузка карточки происходит после нажатия на ссылку Скачать. Для просмотра сохраненной карточки необходимо установить программу для просмотра PDF-документов (например: Adobe Acrobat Reader, STDUViewer и др.).

21.10. Управление лимитом

Данная функция аналогична функции "Обещанного платежа" других биллинговых систем.

Замечание

Управление лимитом доступно только договорам с режимом Дебет

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

# Коды групп договоров, для которых действует данная настройка, через ',' (чтобы узнать код группы нажмите Ctrl+i в справочнике 
# групп при выбранной строке таблицы)
contract.limit.<n>.groups=
# Максимальное количество не оплаченных (не возвратившихся) понижений,
# при котором клиенту будет доступно понижение, при 0 клиент не сможет выполнять
# понижение до тех пор пока будет хотя бы одно не оплаченное
contract.limit.<n>.maxnotpayoffed=
# Максимальное количество частично оплаченных понижений,
# при котором клиенту будет доступно понижение (0-1, частично оплаченное понижение
# может быть только одно)
contract.limit.<n>.maxpartialpayoffed=
# Количество просроченных платежей после последней разблокировки,
# после которых доступ к понижению будет заблокирован, 0 - не блокировать при любом количестве
contract.limit.<n>.maxexpiredforblock=
# Дни от до
contract.limit.<n>.mindays=
contract.limit.<n>.maxdays=
# Сумма от до
contract.limit.<n>.minsumm=
contract.limit.<n>.maxsumm=
# Нижний порог лимита при понижении клиентом (по умолчанию -100),
# т.е ниже этого порога клиент понизить не сможет
contract.limit.<n>.minlimit=

Где: <n> - целое число, начинающееся с 1, определяющее блок конфигурации для определённых групп договоров.

Например, настройка понижения лимита для групп договоров с кодами 1 или 2:

# Коды групп договоров для которых действует данная настройка, через ',' (чтобы узнать код группы нажмите Ctrl+i в справочнике 
# групп при выбранной строке таблицы)
contract.limit.1.groups=1,2
# Максимальное количество не оплаченных(не возвратившихся) понижений,
# при котором клиенту будет доступно понижение, при 0 клиент не сможет выполнять
# понижение до тех пор пока будет хотя бы одно не оплаченное
contract.limit.1.maxnotpayoffed=0
# Максимальное количество частично оплаченных понижений,
# при котором клиенту будет доступно понижение (0-1, частично оплаченное понижение
# может быть только одно)
contract.limit.1.maxpartialpayoffed=0
# Количество просроченных платежей после последней разблокировки
# после которых доступ к понижению будет заблокирован, 0 - не блокировать при любом количестве
contract.limit.1.maxexpiredforblock=1
# Дни от до
contract.limit.1.mindays=1
contract.limit.1.maxdays=4
# Сумма от до
contract.limit.1.minsumm=100
contract.limit.1.maxsumm=200
# Нижний порог лимита при понижении клиентом (по умолчанию -100),
# т.е ниже этого порога клиент понизить не сможет
contract.limit.1.minlimit=-400

Используя блоки, настройки управления лимитом можно задать различными для разных групп договоров. Разумеется, группы блоков не должны пересекаться.

Для управления лимитом используется меню Управление лимитом на странице статистики. Для понижения лимита выбирается сумма и на сколько дней необходимо понижение. В случае, если договор не входит хотя бы в одну из групп, указанных в конфигурации, для которых доступно понижение лимита или если режим договора не Дебет, меню Управление лимитом не отображается.

Пониженный лимит всегда возвращается в исходное состояние. Это происходит либо при внесение на счёт суммы, большей или равной сумме понижения до наступления даты восстановления, либо по наступлению даты восстановления задачей Восстановление лимитов.

В случае, если лимит возвращается в исходное состояние задачей, понижение отмечается как просроченное, максимально допустимое количество просроченных понижение устанавливается в конфигурации.

При каждом платеже, поступившем на договор, система погашает не погашенные (активные) понижения лимита. При этом понижение может быть погашено частично, становясь частично погашенным. Лимит при этом не изменяется. Если до даты восстановления будут произведены ещё платежи на счёт, понижение при достаточной сумме может быть признано погашенным, лимит возвращается в исходное состояние досрочно (разумеется, можно погасить понижение и одним платежом). Если до даты восстановления платежей больше не будет, понижение так и останется частично погашенным.

Если платежа хватает на погашение понижения с избытком, система ищет следующий непогашенный платёж, расходуя на него остаток платежа, и т.д. Все понижения могут быть погашены как одним так и серией платежей.

Понижение лимита доступно только при следующих условиях:

  • количество уже сделанных не погашенных понижений меньше либо равно переменной contract.limit.<n>.maxnotpayoffed конфигурации блока;

  • количество просроченных понижений меньше или равно переменной contract.limit.<n>.maxexpiredforblock конфигурации блока;

  • количество частично оплаченных платежей меньше или равно переменной contract.limit.<n>.maxpartialpayoffed конфигурации блока.

В случае, если понижение недоступно, пользователь увидит страницу следующего вида.

В момент понижения система также контролирует следующие условия:

  • количество дней на которое понижается лимит должно быть от contract.limit.<n>.mindays до contract.limit.<n>.maxdays;

  • сумма понижения должна быть от contract.limit.<n>.minsumm до contract.limit.<n>.maxsumm;

  • в результате понижения лимит не должен стать менее, чем contract.limit.<n>.minlimit.

Оператор биллинга может индивидуально управлять доступом договора к сервису временного понижения лимита через вкладку Web=>Управление лимитом договора.

На вкладке Управление возможно включение/отключение данной возможности для конкретного договора. По умолчанию возможность включается для всех групп договоров, указанных в конфигурации (см. выше).

На вкладке Статистика отображается история понижений лимита. Количество просроченных платежей сбрасывается каждый раз при активации возможности понижения лимита для договора. Таким образом, если возможность блокируется для договора системой, повторная активация администратором сбрасывает счётчики.

21.11. Управление статусом

У пользователя имеется возможность самостоятельно изменить статус договора.

Имеются некоторые ограничения. Пользователь может менять только со статуса "активен" на статус "приостановлен" и наоборот. Другие статусы ему недоступны. Нельзя приостановить раньше, чем завтра. Нельзя активировать раньше, чем сегодня.

Если статус договора не "активен" и не "приостановлен" - тоже не разрешена смена.

Если closed.date.enabled, то проверятся, что устанавливаемый статус не пересекается с закрытым периодом.

Смена статусов сопровождается событиями, как и при обычной смене статусов, не из Web. Только в событии ContractStatusChangingEvent устанавливается флаг isweb=true. Событие ContractStatusChangedEvent выполняется точно так же.

Список дат, которые будут отображаться, регулируются событием GetContractStatusChangeDatesEvent. Если вернули список, то будет отображён список дат. Если не обработано событие, то будет дан выбор дня,месяца,года. Если же будет возвращен пустой список, то это означает, что смена статуса запрещена, о чём сообщится пользователю вместо выбора даты.

21.12. Дополнительные действия

В данном пункте возможен вывод с помощью скриптов BGBS дополнительных действий для вызова пользователем.

21.13. Параметры договора

При необходимости можно вывести в Web-интерфейсе параметры договора. Для включения данного пункта меню необходимо в конфиге прописать web.menuItem12=Параметры договора или настроить в Редакторе web-меню

Какие параметры должны отображаться в Web-интерфейсе, задается в редакторе параметров выбором двух флагов Чтение в ЛК и Правка в ЛК

В зависимости от выбранных флагов, параметр в Web-интерфейсе не будет отображаться вообще, не будет отображаться, но его можно будет редактировать, будет выводиться, но без возможности редактирования и будет отображаться и доступен для редактирования

21.14. Примечания

В данном меню отображаются разрешённые к показу пользователю примечания договора.

22. Разграничение прав доступа

22.1. Пользователи, группы, права

Права доступа к биллингу распределяются по пользователям. Пользователи также могут принадлежать одной или нескольким группам, у которых также настраиваются права на выполнение тех или иных действий. Настройка пользователей, групп и принадлежности пользователей группам выполняется в меню Сервис => Администрирование => Пользователи и права.

Первым шагом является заведение группы действий. Для этого перейдите на вкладку Группы и нажмите Добавить на стандартной панели инструментов.

Дважды кликните по узлу Все действия для его раскрытия. После этого проставьте галочки на всех разрешённых группе действий. Далее выберите группы договоров, с которыми сможет работать данная группа, используя разрешённые ей действия. (Например, есть две группы, у одной разрешены действия с DialUp и группа договоров DLP, у другой разрешены действия с Email, и группа договоров EML, если назначить эти группы пользователю, то он не сможет работать с договорами EML используя действия DialUp)

В каждой группе помимо действий могут быть установлены фильтры по группам договоров и Запрещённые параметры - параметры договоров, которые данная группа изменять не может. Настройка действий, групп договоров и запрещенных параметров также может быть индивидуальной для каждого пользователя (см. далее).

При проверке каждого действия, сервер проверяет все группы, в которые входит пользователь (включая индивидуальные права) и ищет разрешение данного действия. Если действие в некоторой группе разрешено, то оцениваются фильтры по группе договоров и запрещённым параметрам (если это необходимо). В случае удовлетворения фильтров всем условиям действие разрешено. В противном случае - запрещено.

В связи с этим необходимо учитывать, что пустой фильтр групп договоров (не всегда, см. далее) и пустой список запрещённых параметров разрешает работу с любыми договорами и параметрами договоров. И если, например, действие изменения договоров разрешено в свойствах пользователя и не установлен фильтр запрещённых параметров, а в свойствах некой группы, куда входит пользователь, такой список присутствует, то пользователю будет разрешено изменение любых параметров.

То же относится и к группам договоров - разрешён будет максимум из присвоенных клиенту групп пользователей. Если в какой-нибудь из групп пользователей не будет фильтра по группам договоров (и будет установлен параметр ИЛИ, см.далее) - будет разрешена работа со всеми договорами.

Внимание

Если в группе пользователей или у пользователя не будет фильтра по группам договоров (не будет отмечено ни одной группы), то в этом случае поведение системы будет зависить от параметра И/ИЛИ:

  • При установленном параметре ИЛИ будет разрешена работа со всеми договорами;

  • При параметре И будет разрешена работа только с договорами, не входящими ни в одну группу.

Таким образом, если необходимо не учитывать разрешения группы или пользователя к группам договоров, то уберите все галочки и установите параметр И. А при включенном параметре ИЛИ, будет разрешено все, вне зависимости от других групп пользователей или пользователя.

На вкладке Пользователи заводятся пользователи системы, там же определяется принадлежность пользователя группам. Индивидуальные разрешения на действия, фильтры запрещённых параметров и групп договоров можно рассматривать, как уже упоминалось ранее, как добавление ещё одной группы.

Указание групп договоров непосредственно в пользователе скрывает неуказанные типы договоров при поиске. Режим совпадения и/или для Групп договоров означает, что пользователь видит договор либо при наличии всех определённых для него групп в договоре, либо хотя бы одной из определённых для него групп.

В поле E-mail может быть задан адрес электронной почты пользователя, который автоматически проставляется по умолчанию в полях, где требуется ввод почты.

В общем случае следует сначала сопоставить пользователю группы действий, пароль и прочие опции, исключая Действия. После этого сохранить пользователя. Если требуется добавление персональных действий, не включённых в указанные группы, открыть редактор пользователя снова и проставить на вкладке Действия требуемые разрешения. Выделенные серым блокированные галочки уже указаны в группах пользователя.

Поле Привязка к договору в свойствах пользователя позволяет заводить в системе агентов. При этом все агентские договоры должны иметь параметр типа Ссылка на договор (Агент в примере) и значение этого параметра должно быть равным агентскому договору (NK00001-03 для приведённого выше снимка экрана). Данному пользователю системы будет разрешена работа только со своими договорами. Они же будут выведены в результатах поиска. В договоре агента (NK00001-03 в примере) вы можете вести взаимозачёты с агентом. Правка параметра Агент должна быть запрещена для пользователя-агента!

В Конфигурации пользователя может быть установлены следующие опции:

user.actions.permit.show_errors=0 - сокрытие ошибок Доступ запрещён от пользователя, при этом сервер просто игнорирует запрещённые действия.

Включить/выключить проверку прав можно в конфигурации сервера. Права пользователя, чей код в базе равен 1, не проверяются, он может делать все. По умолчанию это admin, созданный установочным скриптом.

В дополнение к системе разграничения доступа система предоставляет возможность аудита действий пользователей. Журнал запросов доступен в меню Сервис=>Журналы=>Журнал запросов .

При просмотре списка пользователей возможна фильтрация по имени пользователя и статусу.

22.2. Настройка дерева действий

Права на выполнение различных действий внутри системы контролируются подсистемой BGSecure. Все действия в биллинге собраны в древовидную структуру. При установке модуля вместе с ним инсталлируются его действия. Действия модуля прописаны в файле, расположенном в каталоге BGBillingServer/actions.

При необходимости вы можете корректировать файл, добавляя свои собственные действия. Например, можно определить редактирование каждого параметра договора отдельным действием, либо просмотр каждого отчёта. Т.к. действия просматриваются по порядку, то свои действия необходимо добавлять перед существующими

Запросы вы можете посмотреть в файле log, запустив клиент биллинга в DEBUG-режиме скриптом bgbilling_debug.bat (.sh), либо воспользуйтесь Сервис=>Журналы=>Журнал запросов. О различиях в видах запросов к серверу вы можете посмотреть здесь.

Внимание

Файлы с конфигурациями действий перетираются при каждой установке/обновлении модуля, не забывайте заново корректировать их, если вы добавили в них собственные действия. Вы также можете создать orig-файлы конфигурации действий, что позволит корректировать файлы только, если они действительно изменились в дистрибутиве. Нумеруйте свои действия номерами больше 1000, чтобы не наступил конфликт ваших действий с добавляемыми стандартными.

22.2.1. HTTP Action

Действия определяются в следующем виде:

<group title="Модули и услуги">
 <action id="14" mask="module=service;action=GetServices" title="Просмотр услуг"/>
 <action id="15" mask="module=service;action=UpdateService" title="Обновление услуги"/>
 <action id="16" mask="module=service;action=DeleteService" title="Удаление услуги"/>
</group>

Группы предназначены исключительно для их визуального разделения в графическом дереве. Каждое действие должно иметь уникальный в пределах файла код id. Маска mask действия определяет набор параметров HTTP-запроса, по которым он будет отнесён к данному действию. В параметре запроса может быть указано и REGEXP-выражение, это позволяет выделять некоторые типы действий. Например, в модуле dialup можно выделить в отдельное действие переобсчёт сессий по конкретному договору:

"module=dialup;action=RecalculateSessions;contract=R:\d+"

Как видно из примера, REGEXP указывается после строки R:.

22.2.2. Web-сервис

Действия определяются в следующем виде:

<group title="Платежи">
   <service id="89" name="PaymentService" operation="paymentList" title="Просмотр платежей"/>
   <service id="90" name="PaymentService" operation="paymentUpdate" title="Изменение платежа" expression="payment.getId() gt 0"/>
   <service id="101" name="PaymentService" operation="paymentUpdate" title="Добавление платежа"/>
</group>

Первичным ключом действия выступает имя Web-сервиса и операция. С помощью JEXL выражения в expression возможно дополнительная фильтрация параметров метода (см. пример). Все параметры метода передаются в JEXL контекст и у них могут быть вызваны функции. В приведённым выше примере по признаку неположительного идентификатора платежа отделены добавление и изменение платежа.

22.3. Доступность пунктов меню в клиенте BGBillingClient

Для каждого пользователя, либо для группы пользователей, ко всему прочему, можно настроить также и возможность скрытия ненужных по каким-либо причинам пунктов меню в клиенте BGBillingClient. Само описание меню хранится в файле BGBillingServer/data/menu.xml в виде дерева. Например:

...
<menu title="Сервис" id="service">
    <menu title="Журналы" id="log">
        <menuItem id="query" className="bitel.billing.module.admin.bgsecure.ActionQueryLogViewer" title="Журнал запросов"/>
        ...
    </menu>
</menu>
...

Каждый элемент меню однозначно характеризуется связкой <код меню>.<код пункта меню>. При наличии вложенности нескольких меню для определения конкретного пункта меню (т.е. листа дерева), используется только последний код меню, непосредственно включающего данный пункт. Например, пункту меню Сервис => Журналы => Журнал запросов соответствует ключ log.query (см. код выше). Пункты меню, соответствующие конкретному модулю имеют код вида <код модуля>. Например, для модуля Inet c кодом 12 код пункта меню будет равен 12. Пункты меню, соответствующие плагинам, прописаны в файле plugin.xml, который находится в корне jar-архива плагина. Данный архив находится в папке <BGBilling_server_path>/lib/app.

Для того, чтобы скрыть от пользователей или их групп часть меню или элементов меню, необходимо при редактировании конкретного пользователя или конкретной группы перейти на вкладку Пункты меню. Для добавления, удаления или редактирования правила на скрытие (или, напротив, отображения) какого-либо пункта меню или целого меню необходимо нажать на соответсвующие кнопки над таблицей с правилами.

Для добавления нового правила необходимо ввести код меню (или пункта меню), которого оно касается, а также указать показывается он или является скрытым. Для скрытия целого меню используется правило вида <код меню>, а для скрытия конкретного подпункта - <код меню>.<код пункта меню>.

Важно заметить, что правила для конкретного пользователя имеют более высокий приоритет, чем групповые. Например, для группы "Операторы" можно скрыть все меню Модули, но для оператора Васи сделано исключение, и оно будет отображаться.

При наличии же нескольких групп у пользователя сложение правил видимости действует по принципу "сложения по видимости". Т.е. если некий пользователь Петров принадлежит к двум группам (группе А и группе Б), причем в группе А действует правило невидимости пункта меню Модули, а у группы Б - пункта меню Плагины, то у Петрова все равно будут видны оба этих пункта. Потому что ни у одной из этих двух групп нет общих правил невидимости пунктов меню. Если же Петров будет принадлежать либо к группе А, либо группе Б (но не одновременно к обоим), то у него не будет виден пункт либо, соответственно, Модули, либо - Плагины.

Внимание

Скрытие пунктов меню для пользователей не относится к системе BGSecure и носит чисто визуальный характер! При использовании альтернативных клиентов права действия "внутри" пунктов меню необходимо разграничивать при помощи системы BGSecure.

23. Сервис

23.1. Общие сведения

Большинство пунктов меню Сервис описано в документации в контексте подсистемы, к которой относится пункт меню. Описание прочих пунктов меню приведено ниже.

23.2. Журналы

23.2.1. Ошибки обработки логов

Ошибки обработки логов возникают в модулях, которые используют систему обработки логов с источниками. Каждая ошибка привязана к модулю, источнику и часу. Каждая запись в таблице содержит в себе ошибки обработки часа целиком. При повторной обработке логов за этот же час все ошибки удаляются, т.е. если ошибок вновь не возникнет, то за этот час ошибок в базе не будет.

Для просмотра ошибок обработки логов выберите соответствующую вкладку в меню Сервис=>Журнал ошибок. Для просмотра ошибок необходимо выбрать интересующий модуль, источник, а также указать период. Далее необходимо нажать кнопку с галочкой. Выбрав интересующую запись из таблицы, можно просмотреть конкретные сведения об этих ошибках.

23.2.2. Ошибки периодических процессов

Ошибки периодических процессов возникают при периодических (или запущенных самостоятельно) переобсчётах. Например, при переобсчёте в модуле NPay. Ошибки периодических процессов можно удалять вручную, воспользовавшись кнопкой Удалить в тулбаре. Также ошибки периодических процессов за данный месяц и по данному коду модуля удаляются в случае, если запущен полный переобсчёт по всем договорам. И если в этом случае ошибки опять возникают, то они вновь добавляются в журнал.

Для просмотра выявленных ошибок откройте вкладку Ошибки периодических процессов в меню Сервис=>Журнал ошибок. Обязательным является указание месяца, за который производился переобсчёт. Далее возможно указание подстроки, содержащейся в тексте ошибки (например, строки "npay", если необходимо найти все ошибки переобсчётов по модулю Npay), а также периода, в течение которого производился переобсчёт по выбранному месяцу. Для вывода ошибок необходимо нажать на кнопку Найти. По двойному щелчку на выбранной ошибке в таблице откроется полный текст ошибки.

Обратите внимание, что идентификаторы в сообщениях об ошибках передаются в виде числовых кодов. Для поиска договора по коду воспользуйтесь вкладкой Параметры=>ID договора окна поиска договоров.

Сопоставить услугу с ее кодом вы можете в Модули=>Редактор модулей и услуг, открыв перечень услуг конкретного модуля.

23.2.3. Журнал запросов

Данный журнал предоставляет возможность аудита действий пользователей и доступен в меню Сервис=>Журналы=>Журнал запросов. Для удобства поиска различных действий доступны следующие фильтры: по периоду, по действиям, по пользователю биллинга, по договору и по строке запроса. Фильтр по строке запроса поддреживает поиск по MySQL REGEXP в полях Параметр и Значение, для этого нужно отметить REGEXP. Если не использовать выражения с regexp, то необходимо убрать выделение REGEXP, но при этом можно указать символы % - любое кол-во символов и _ - один любой символ также в обоих полях строки запроса. Regexp и замена спец. символов производится по полям, и автоматически добавляет между ними =>. Пример поиска со спец. симоволами % и _ можно видеть на скриншоте ниже. Под таблицей с запросами выводится дополнитльная информация по выделенному запросу.

Включить/выключить журналирование действий можно в конфигурации сервера.

23.2.4. Журнал Web-запросов

Данный журнал предоставляет возможность аудита действий клиентов, а также просмотр удачных/неудачных авторизаций в личном кабинете, и доступен в меню Сервис=>Журналы=>Журнал Web-запросов. Для удобства поиска различных действий доступны следующие фильтры: по периоду, по запросу, по договору. В фильтре по запросу можно использовать спец. символы оператора LIKE в MySQL: % - любое количество символов; _ - один любой символ. Под таблицей с запросами выводится дополнительная информация по выделенному запросу.

23.3. Загрузка платежей и расходов из файла

Может использоваться как протокол обмена между внешними программами по приёму платежей и сервером биллинга. Загрузка производится из текстового, либо DBF-файла. Менеджер загрузки расположен в меню Сервис=>Автоматизация=>Загрузка платежей и расходов.

Загрузка платежей и расходов может производится из файлов различных форматов. Для каждого формата файла должен быть определён шаблон, шаблоны загрузки платежа (расхода) описываются в конфигурации сервера биллинга (меню Сервис=>Настройка=>Конфигурация).

Для загрузки строки с платежом (расходом) из файла программа выполняет следующие шаги:

  1. Разбор строки на части (только для TXT-файлов). При этом из сплошной строки образуется запись, содержащая позиции (подстроки), нумерующиеся с единицы. Очевидно, что для DBF файлов данный этап не требуется, т.к. файл изначально состоит из записей;

  2. Вычленение из записи сумм платежей (расходов), идентификатора договора, комментария платежа (расхода), даты платежа\расхода (опционально);

  3. Сопоставление записи договору в биллинге;

  4. Зачисление (снятие) суммы на договор.

Каждый шаблон обозначается уникальным числовым идентификатором (<id>), он должен присутствовать в каждой строке, описывающей шаблон. Шаблоны следует нумеровать строго по порядку. Приведённые ниже примеры описывают шаблон с кодом 1.

Внимание

Все дальнейшие примеры будут описывать шаблоны загрузки только реестров платежей. Шаблоны реестров расходов идентичны шаблонам платежей с точностью до слова payment в начале каждой строки (для расходов следует писать charge, например charge.load.pattern.1=Новый шаблон) и до указания типа payment_type (следует писать charge_type). Нумерация шаблонов расходов независима от нумерации шаблонов платежей (т.е. может быть как шаблон платежа, так и шаблон расхода с номером 1).

В каждом шаблоне должны быть обязательно определены параметры:

payment.load.pattern.<id>=<Название>
payment.load.pattern.<id>.type=<Тип>
payment.load.pattern.<id>.encoding=<Кодировка>
payment.load.pattern.<id>.payment_type=<Типы платежей>
payment.load.pattern.<id>.position_sum=<Позиции сумм>

Где:

Название - текстовая строка, обозначающая шаблон в выпадающем списке менеджера загрузки платежей
Тип - число, определяющее тип файла. 1 - для текстового файла, 2 - DBF.
Кодировка - кодировка файла (Cp1251, UTF-8, Cp866).
Типы платежей - коды типов платежа, которыми вносятся платежи в договор. Лучше, если это будет не редактируемый тип. Код вы можете посмотреть в справочнике типов платежей Справочники=>Другие=>Типы платежей.
Позиции сумм - из какой позиции записи брать суммы платежей.

Начиная с версии 4.6 появилась возможность указывать в одной строке одновременно несколько сумм для разных типов платежей. Для этого в полях payment_type и position_sum нужно указывать типы платежей и позиции сумм через запятую, в правильном, соответственном порядке. Т.е. если указать payment_type=1,2,3 и position_sum=2,3,4, то это будет означать, что на 2ой позиции расположена сумма с платежом типа 1, на 3ей позиции - типа 2 и т.п

В случае если тип формата определён как 1 (текстовый файл), то должен быть определён REGEXP разбития строки файла на позиции записи.

payment.load.pattern.<id>.regexp=<REGEXP>

Дополнительно для каждого шаблона могут быть определены следующие необязательные параметры:

payment.load.pattern.<id>.summa.replace=<Строка замен>
payment.load.pattern.<id>.position_comment=<Позиция комментария платежа>
payment.load.pattern.<id>.position_id=<Позиция уникального идентификатора>
payment.load.pattern.<id>.position_date=<Позиция даты>
payment.load.pattern.<id>.date_format=<Формат даты платежа>

Где:

Строка замен - несколько записей вида {REGEXP что}=>{На что}, разделённые вертикальной чертой;
Позиция комментария платежа - из какой позиции записи брать комментарий платежа, если параметр не указан, то комментарий - пустая строка;
Позиция уникального идентификатора - из какой позиции записи брать уникальный строковый идентификатор платежа. При указании данного поля загрузчик будет считать ошибочными платёж, если в уже загруженных реестрах с датой реестра в том же месяце, что и загружаемый реестр, уже есть платёж с таким идентификатором;
Позиция даты и Формат даты платежа - из какой позиции записи брать дату платежа и в каком формате она указана. Если параметры не указаны, то дата платежа равна дате реестра.

Макрос замен используется для приведения произвольного формата суммы к виду сплошной записи с десятичной точкой в качестве разделителя, например: 545454.55. Для приведения записи 545 454-55 к этому формату необходимо указать следующий макрос:

payment.load.pattern.<id>.summa.replace=\-=>.|\s=>

Последнее, что необходимо определить для каждого шаблона - метод сопоставления записи с договором биллинга. Для этого могут быть определены один или несколько методов поиска. По умолчанию результаты поиска по всем методам складываются, но можно соединить их условием логическое И, установив опцию:

payment.load.pattern.<id>.search.mode=and

В системе установленно жёсткое ограничение, по которому каждый тип поиска возвращает не более 10 результатов. Это реализовано в MySQL опцией LIMIT. Режимы поиска работают с учётом даты платежа, она сравнивается с периодом действия договора, логина, телефона и пр. В результаты поиска не попадают договоры, помеченные как "скрытые".

Каждый метод поиска имеет свой подход (<s_id>) в пределах шаблона. В методе поиска должны быть определены обязательно параметры:

payment.load.pattern.<id>.search.<s_id>.type=<Тип метода>
payment.load.pattern.<id>.search.<s_id>.pos=<Позиция>
payment.load.pattern.<id>.search.<s_id>.regime=<Метод сопоставления>

Где:

Тип метода - может принимать значения: cid (код договора), contract (название договора), comment (комментарий договора), parameter (текстовый параметр договора), parameter_email (параметр договора типа E-Mail), cerbercrypt (номер карты в модуле CerberCrypt), login (логин, либо алиас модуля DialUp/VoiceIP), phone (номер телефона модуля phone);
Позиция - из какой позиции записи брать идентификатор для данного метода поиска;
Метод сопоставления - какое MySQL-выражение использовать для запроса поиска. 1 - "=", точное совпадение идентификатора с записью в базе; 2 - LIKE; 3 - REGEXP.

При типах метода parameter, parameter_email необходимо указание кода параметра:

payment.load.pattern.<id>.search.<s_id>.pid=<Код параметра договора>

При типах поиска, связанных с конкретным модулем (login, phone, cerbercrypt), необходимо указать код экземпляра модуля:

payment.load.pattern.<id>.search.<s_id>.mid=<Код экземпляра модуля>

Дополнительно для каждого метода поиска могут быть указаны следующие необязательные параметры:

payment.load.pattern.<id>.search.<s_id>.groups=<Группы договоров>
payment.load.pattern.<id>.search.<s_id>.pattern=<REGEXP-фильтр>
payment.load.pattern.<id>.search.<s_id>.replace=<REGEXP замены>
# Не учитывать период действия договора при поиске
payment.load.pattern.<id>.search.<s_id>.no.contract.period.check=1

Где:

Группы договоров - список через запятую кодов групп договоров, разрешённых к поиску данным методом.Группы можно посмотреть в справочнике Справочники=>Другие=>Группы договоров;
REGEXP фильтр - ограничение искомых договоров по их названию, следует учитывать, что используется MySQL REGEXP;
REGEXP замены - преобразование идентификатора договора с помощью REGEXP-выражения. Возможно указание нескольких замен, разделённых двойной вертикальной чертой (||). Каждая замена состоит из REGEXP-шаблона, далее строка => и на что необходимо заменять шаблон. В строке-замене возможно использование макросов $0-$5, соответствующих номерам групп из REGEXP-выражения. Например при методе сопоставления LIKE (см. ранее) можно добавлять в конец строки-идентификатора "%", указав в replace-параметре: ..replace=.*=>$0%.

Пример 1.6. Пример шаблона 1

Формат строки в исходном файле (разделители полей - точка с запятой). Первым идёт название договора, далее сумма платежа и комментарий. Даты платежа нет, в этом случае она равна дате реестра.

x0000;13.4;sfdsdfdsd

Описание шаблона в конфигурации. Идентификация клиента проводится по номеру договора.

payment.load.pattern.1=Шаблон1
payment.load.pattern.1.type=1
payment.load.pattern.1.encoding=UTF-8
payment.load.pattern.1.payment_type=2
payment.load.pattern.1.position_sum=2
payment.load.pattern.1.regexp=(\w+);([\d\.]+);(\w+)
payment.load.pattern.1.position_comment=3
payment.load.pattern.1.search.1.type=contract
payment.load.pattern.1.search.1.pos=1
# 1 - eq, 2 - LIKE, 3 -REGEXP
payment.load.pattern.1.search.1.regime=1

Пример 1.7. Пример шаблона 2

Формат строки в исходном файле (разделители полей - табуляторы). На второй позиции идёт номер телефона, на четверной - сумма платежа, на пятой - комментарий договора. Дата платежа из файла не используется.

2 2775102 20.07.07 147.88 Мурева Вова Витальевна г. Самара, ул Потейская д.144 кв.17

Описание шаблона в конфигурации. Идентификация клиента производится по номеру телефона + ФИО.

payment.load.pattern.1=Шаблон
payment.load.pattern.1.regexp=(\d+)\t(\d+)\t([\d\.]+)\t([\d\.]+)\t([а-яА-я \w]+)\t(.+)
# Позиция суммы и комментария (в комментарий идёт идентификатор платежа из файла)
payment.load.pattern.1.payment_type=2
payment.load.pattern.1.position_sum=4
payment.load.pattern.1.position_comment=1
# Метод поиска по телефону
payment.load.pattern.1.search.1.type=phone 
# Код экземпляра модуля телефонии
payment.load.pattern.1.search.1.mid=1
# В какой группе REGEXP идёт номер телефона
payment.load.pattern.1.search.1.pos=2
# Номер телефона дополняется перед поиском до E.164
payment.load.pattern.1.search.1.replace=.*=>7846$0
# ФИО
payment.load.pattern.1.search.2.type=comment
# ФИО идёт на пятой позиции файла
payment.load.pattern.1.search.2.pos=5
# Проверка ФИО+телефона
payment.load.pattern.1.search.mode=and

Пример 1.8. Пример шаблона 3

Формат строки в исходном файле (разделители полей - точка с запятой). Первым идёт номер договора, далее сумма, комментарий договора и дата платежа. Обратите внимание, что комментарий договора может быть указан не полностью, только фамилия.

x0000;13-4;Иванов ;04.07.2008

Описание шаблона в конфигурации. Идентификация клиента производится по номеру договора + началу ФИО.

payment.load.pattern.2=Шаблон2
payment.load.pattern.2.type=1
payment.load.pattern.2.encoding=UTF-8
payment.load.pattern.2.payment_type=2
payment.load.pattern.2.regexp=(\w+);([\d\,\.\s\-]+);([а-яА-Я\s]+);([\d\.]+)
payment.load.pattern.2.position_sum=2
# Преобразование суммы к нужному виду
payment.load.pattern.2.summa.replace=\-=>.|\s=>
# Дата платежа берётся из файла
payment.load.pattern.2.position_date=4
payment.load.pattern.2.date_format=dd.MM.yyyy
payment.load.pattern.2.search.mode=and
payment.load.pattern.2.search.1.type=contract
payment.load.pattern.2.search.1.pos=1
payment.load.pattern.2.search.1.regime=1
payment.load.pattern.2.search.2.type=comment
payment.load.pattern.2.search.2.pos=3
payment.load.pattern.2.search.2.regime=2
payment.load.pattern.2.search.2.replace=\s*([а-яА-Я]+)\s*=>%$1%
#

Пример 1.9. Пример шаблона 4

Загрузка производится из DBF-файла, второй столбец - дата платежа, третий - сумма, шестой - номер договора. Описание шаблона в конфигурации. Идентификация клиента производится по номеру договора.

payment.load.pattern.3=Шаблон3
payment.load.pattern.3.type=2
payment.load.pattern.3.encoding=Cp866
payment.load.pattern.3.payment_type=2
payment.load.pattern.3.position_sum=3
payment.load.pattern.3.position_date=2
payment.load.pattern.3.date_format=yyyy-MM-dd
payment.load.pattern.3.search.1.type=contract
payment.load.pattern.3.search.1.pos=6
payment.load.pattern.3.search.1.regime=1

Обработка платежей осуществляется на основании реестров следующим образом:

  1. загрузка файла в реестр с проверкой ошибок формата, сопоставлением платежей договорам;

  2. проведение реестра с начислением платежей в баланс;

  3. откат реестра при необходимости.

Каждый реестр характеризуется датой и названием. Дата реестра устанавливается в дату платежа в случае, если дата не берётся из записи. Проведение реестра - процесс занесения приходов по разобранному реестру в договоры. Откат реестра - процесс удаления платежей, может быть полезен при ошибочном реестре.

Для загрузки реестра необходимо выбрать файл, дату реестра и шаблон для разбора. Если название реестра не указано, оно принимается равным имени файлу. После нажатия кнопки Загрузить реестр отображается в таблице (фильтр по дате должен включать дату реестра) и в нижнем окне выводится лог загрузки реестра и выделенные платежи.

Для проведения реестра - выбрать строку в таблице и нажать кнопку Провести реестр. Для отката - также выбор строки и кнопка Откат реестра.

23.3.1. Автоматическая загрузка реестров платежей

Внимание

Работает ТОЛЬКО для загрузки платежей.

Для автоматической загрузки реестров необходимо настроить задачу планировщика Загрузка платежей из файлов. Папка, из которой будут загружаться файлы и в которую будут перещаться в резултате обработки, должны быть в локальной файловой системе. В конфигурации задачи указываются:

report.mail=<E-Mail адрес, на который высылать ошибки разбора реестров>
load.from.dir=<полный путь к каталогу, из которого загружаются реестры>
processed.to.dir=<полный путь к каталогу, в который перемещаются обработанные реестры>

Все возможные типы файлов-реестров должны быть описаны следующим образом, <id> - уникальный для каждого типа файла код.

filetype.<id>.load_pattern=<Код шаблона загрузки>
filetype.<id>.name_pattern=<REGEXP имени файла>

Дополнительно, могут быть указаны параметры для извлечение даты реестра из имени файла. Если данные параметры не указаны, то дата реестра принимается равной дате последней модификации файла.

filetype.<id>.date_format=<формат даты>
filetype.<id>.position_date=<номер группы в REGEXP имени файла, где записана дата>

Пример 1.10. Пример конфигурации задачи

Имена реестров представляют из себя файлы вида TNEyyyMMdd.DBF.

report.mail=shamil@bitel.ru
load.from.dir=/home/shamil/tmp/payments
processed.to.dir=/home/shamil/tmp/payments/processed
filetype.1.load_pattern=3
filetype.1.name_pattern=TNE(\d{8})\.DBF
filetype.1.date_format=yyyyMMdd
filetype.1.position_date=1

23.4. Групповые операции над договорами

23.4.1. Общие сведения

Групповые операции доступны в меню Сервис=>Администрирование=>Групповые операции и позволяют автоматизировать типичные манипуляции над большим количеством договоров.

Перед применением операции договоры должны быть отфильтрованы в окне поиска договоров.

Далее открывается вкладка Групповые операции и нажатием кнопки Договоры выбранные договоры помещаются в список. В списке можно убрать пометки с ненужных договоров.

Далее выбирается галочкой Выполнить одна или несколько модификаций. Доступны следующие модификации.

  1. Установка услуг в выбранные договоры с указанного периода. Данная опция необходима при введении новых модулей, услуги которых следует добавить всем договорам, например WM. Услуги разбиты по модулям и представлены древовидным списком;

  2. Прерывание услуг на период (абонплат). Данная модификация необходима при временной недоступности услуг для абонентов для компенсации абонплаты;

  3. Для модуля Bill доступна модификация по установлению типов счетов и фактур в договоры.

Могут быть выбраны одновременно несколько модификаций. Кнопка Следующий проводит модификацию над следующим по списку договором и снимает галочку, данная функция полезна при отладке. При правильном функционировании кнопка Все применяет модификацию ко всем оставшимся договорам. Также список договоров можно получить не только на вкладке Поиск, но и из файла, для этого доступны кнопки

Из файла(номера) - загрузить номера договоров из файла, каждый номер на отдельной строке.

Из файла(коды) - загрузить коды (id) договоров из файла, каждый код на отдельной строке.

23.4.2. Операция "Изменение статуса"

Смена статуса договора. При этом происходит корректное перекрытие существующих на моменты времени статусов с тем, чтобы на каждый день была активна только одна запись о статусе.

23.4.3. Операция "Добавление группы тарифов"

Добавление групп тарифов в договоры.

23.4.4. Операция "Открытие тарифных планов"

Открытие тарифных планов в договорах с определённым периодом.

23.4.5. Операция "Закрытие тарифных планов"

Закрытие тарифных планов в договорах с определённой даты.

23.4.6. Операция "Добавление (Удаление) модулей"

С версии 4.6 появилась привязка договоров к модулям. Данная операция позволяет добавлять(удалять) модули в договоры. В договор будут добавлены только отсутствующие в нем модули.

23.4.7. Операция "Добавление разрешённых услуг"

С версии 4.6 появилась привязка договоров к модулям. Для некоторых модулей необходимо добавить разрешённые услуги. Данная операция позволяет добавлять разрешённые услуги для модулей, в которых это имеет смысл. Услуги будут добавлены только в том случае, когда модуль подключён к договору.

23.4.8. Операция "Удаление(Прерывание на период) разрешённых услуг"

Данная операция позволяет удалять, либо прерывать на период разрешённые услуги для модулей.

23.4.9. Операция "Смена тарифа"

Операция производит закрытие одного тарифа и открытие другого. Операция выполняется только в случае, когда закрываемый тариф открыт на дату закрытия.

23.4.10. Операция "Добавление скрипта"

Операция добавляет скрипт в договоры.

23.4.11. Операция "Установка шаблона комментария договору"

Операция устанавливает шаблон комментария договорам

23.5. Сообщения пользователям

Данная подсистема позволяет отправлять сообщения пользователям биллинга и доступна в меню Сервис=>Настройка=>Сообщения пользователям. Сообщения отображаются после авторизации пользователя в биллинге или во время работы, блокируя весь интерфейс, что не позволяет пользователю проигнорировать их. Для проверки новых сообщений пользователю используется таймер, промежуток времени срабатывания которого можно указать в конфигурации сервера в миллисекундах. Если параметр не задан, то значение его равно одному часу.

client.gui.time.of.check.messages4users=3600000

При создании сообщения необходимо указать заголовок, тело сообщения, пользователей и период(период не может быть бесконечным, т.е. обязательно должна быть дата по какое число сообщение является актуальным), в течение которого оно будет отображаться пользователям, если не прочитано.

Для выбора пользователей, которым необходимо отправить сообщение, можно использовать группы пользователей или же в ручном режиме на закладке "Список пользователей" можно выбрать нужных пользователей или дополнить список тех, которые были отмечены автоматически при выборе группы.

23.6. Индикатор лицензии

Индикатор лицензии вызывается из меню Справка=>Индикатор лицензии. В нём отображается состояние лицензии для каждого модуля и плагина. Отражены как временные, так и количественные характеристики.

Каждый строка отображает максимально разрешённое и текущее состояние по количеству и времени. Параметры которые превысили максимально допустимое значение выделяются красным цветом.

23.7. SQL Редактор

SQL редактор (Утилиты=>SQL-Редактор) представляет собой средство низкоуровневого доступа к БД биллинга. С помощью него можно выполнять произвольные SQL-запросы, получать результаты, сохранять их в файл и отправлять на указанный e-mail.

Каждый запрос можно сохранить в шаблон для последующего извлечения, правки и повторного выполнения. Кнопки "Загрузить" и "Удалить" сверху служат для загрузки и удаления (потребуется подтверждение) выбранного шаблона. Результаты выполнения запроса отображаются в таблице (с возможностью постраничного просмотра). Колонки соответствуют названиям столбцов результата запроса.

Ведётся локальная история выполненных запросов - между последними запросами можно перемещаться с помощью кнопок со стрелками (аналогичных по смыслу кнопкам back и forward в интернет-браузерах).

В нижнем поле "Отправить на e-mail" можно ввести адрес электронной почты и с помощью кнопки Отправить сформировать электронное письмо с вложением в виде csv, в котором будет результат текущего запроса.

Поля запроса и результата разделены подвижным Split-ом.

Редактор SQL - мощное и гибкое средство для манипулирования данными, их обработки и анализа. Но, однако, даже администратору следует применять его с большой осторожностью для выполнения запросов вида UPDATE, DELETE и подобных.

24. Администрирование и оптимизация

24.1. Конфигурация базы данных, память

Каждое приложение биллинга инициализирует пул соединений к базе данных. Необходимость пула вызвана многопоточностью приложений, т.к. в один момент времени соединение с базой данных может потребоваться разным потокам. Пул предотвращает необходимость постоянного создания TCP соединений с MySQL, экономя ресурсы как клиентского приложения, так и MySQL-сервера.

В конфигурации приложения должна быть определена как минимум одна главная (мастер) база. Эта база постоянно актуальна и может выполнять как запросы обновления, так и выборок. В *.properteis конфигурации приложения биллинга определены хост, порт MySQL, имя базы данных и учётные данные для MySQL, например так:

db.driver=com.mysql.jdbc.Driver
db.url=jdbc:mysql://192.168.184.245/bgbilling?useUnicode=true&characterEncoding=UTF-8&allowUrlInLocalInfile=true&zeroDateTimeBehavior=convertToNull&jdbcCompliantTruncation=false&elideSetAutoCommits=true&useCursorFetch=true&queryTimeoutKillsConnection=true
db.user=bill
db.pswd=bgbilling
db.maxIdle=10
db.maxActive=50

Параметр db.maxIdle определяет максимально число простаивающих в данный момент соединений с базой данных; простаивающие соединения, выходящие за данное количество, закрываются. При большом одновременном количестве запросов к приложению биллинга число активных соединений растёт, по мере надобности устанавливаются новые соединения с MySQL, добавляясь в пул. При достижении активного количества соединений db.maxActive создание соединений прекращается, потоки ожидают освобождения уже занятых соединений.

Каждое приложение биллинга способно возвращать свой статус, вызовом *_status.* скрипта (server_status.sh, radius_status.sh). Сообщение о статусе приложения обязательно содержит время старта приложения и время работы, информацию по соединениям с базой данных и используемой памяти. Рассмотрим как пример вывод server_status.sh:

BGBillingServer v 4.6  build 333 from 01.03.2009
Started: 11.03.2009 16:29:49 Uptime: 0 d 00:00:05
Memory total: 6 045 696; max: 66 650 112; free: 2 975 800
Connections pool to Master status Idle: 1; Active: 0; maxActive: 4; maxIdle: 10
Connections pool to Slave "1" status Idle: 0; Active: 0; maxActive: 4; maxIdle: 10

В верхней строке отображается версия, номер и дата билда приложения (ядра для сервера). Далее - время старта и время работы.

Затем - использование ОЗУ. Параметр max определяет максимальный объем памяти, которую Java-машина может получить у операционной системы; total - сколько реально отобрано Java-машиной памяти в настоящий момент; free - сколько из этой реально выделенной памяти свободно.

По мере работы сборщик мусора освобождает неиспользуемую память. Если использование памяти все равно растёт - увеличивается параметр total. Однако он никогда не может превысить порога, заданного max. Размер памяти max можно увеличивать, изменяя число после параметра -Xmx в скрипте запуска приложения. На 32х разрядных ОС невозможна установка параметра max более 1.5 Гб. При нормальной работе приложения total не должен достигать max.

Последние строки (одна или более) отображают статусы пулов соединений к мастер и слейв базам данных.

24.2. Поддержка репликации

Приложения биллинга могут использовать MySQL-реплику для произведения выборок, приводящих к значительной нагрузке на сервер БД и не требующих при этом немедленной оперативности выполнения. Например, выполнение отчётов модулем отчётов, получение статистики клиентом через Web интерфейс.

Для добавления реплики в *.properties файле приложения (data.properties, radius.properties) указывается после конфигурации основной (Мастер) базы:

db.slave.<slave_id>.url=jdbc:mysql://<host>:<port>/<db_name>?useUnicode=true&characterEncoding=UTF-8&allowUrlInLocalInfile=true&zeroDateTimeBehavior=convertToNull&jdbcCompliantTruncation=false&elideSetAutoCommits=true&useCursorFetch=true&queryTimeoutKillsConnection=true
db.slave.<slave_id>.user=<user>
db.slave.<slave_id>.pswd=<pswd>
db.slave.<slave_id>.maxIdle=<max_idle>
db.slave.<slave_id>.maxActive=<max_active>

Где:

<slave_id> - идентификатор Slave-базы;
<db_name> - имя базы данных;
<host> - хост с Slave-базой;
<port> - MySQL порт;
<user> - логин MySQL;
<pswd> - пароль MySQL;
<max_idle> - максимальное число простаивающих соединений в пуле, лишние будут закрыты;
<max_active> - максимальное число активных соединений в пуле.

Для каждого приложения биллинга реплики указываются отдельно в *.properties файле, что позволяет регулировать использование реплик различными приложениями. Необходимо проконтролировать, чтобы пользователь <user> имел права только на SELECT и CREATE TEMPORARY TABLES в реплике. Также хорошим вариантом является выдача полного набора прав с установкой опции --read_only=1 при старте сервера MySQL (либо установка этой же опции в my.cnf файле).

Например, конфигурация Slave-базы может выглядеть следующим образом:

db.slave.1.url=jdbc:mysql://repl:3306/bgbilling?useUnicode=true&characterEncoding=UTF-8&allowUrlInLocalInfile=true&zeroDateTimeBehavior=convertToNull&jdbcCompliantTruncation=false&elideSetAutoCommits=true&useCursorFetch=true&queryTimeoutKillsConnection=true
db.slave.1.user=bill
db.slave.1.pswd=
db.slave.1.maxIdle=10
db.slave.1.db.maxActive=20

Возможно определение нескольких Slave-серверов с разными <slave_id>. В этом случае запрос будет адресован к серверу, имеющему наименьшее отношение активных соединений в настоящий момент к максимальному числу активных соединений. В случае, если количество соединений ко всем подключённым Slave-базам исчерпано, будет возвращено подключение к Мастер-базе.

Можно отключить возможность предотвращения перерасхода slave-соединений, тогда попытки взять соединение из Master-БД делаться не будет, а будет ожидание освобождения slave-пула. Для этого в data.properties надо добавить параметр

# отключение предотвращения перерасхода slave-соединений (по умолчанию если кончаются
# slave-соединения, например при подвешивании реплики, берутся master-соединения).
db.disable.prevention.slave.overrun=1

Для отслеживания актуальности реплик установите в конфигурации сервера биллинга параметр slave.alarm.second.behind.master=<seconds>, где <seconds> - количество секунд. При отставании реплики от основной базы на <seconds> и более секунд высылается аларм. Опция, установленная в конфигурации сервера биллинга, применяется ко всем приложениям биллинга. В качестве теста возможна установка опции в 0, что должно спровоцировать высылку сообщения. Для работы опции пользователь MySQL приложения биллинга должен иметь в Slave-базах право REPLICATION CLIENT.

Также возможно включить возможность автоматического отключения сильно отстающих реплик с последующим их автоматическим же включением в случае ликвидации критического отставания. Для этого необходимо в конфигурации сервера биллинга установить параметр slave.disable.second.behind.master=<seconds>, где <seconds> - количество секунд. При отставании реплики от основной базы на <seconds> и более секунд высылается аларм, а сервер биллинга, в свою очередь, помечает данную реплику отстающий и прекращает обращения к ней. Через некоторое время, если отставание реплики стало менее <seconds>, то обращения к данной реплики биллингом возобновятся автоматически.

24.3. "Мусорные" базы данных

"Мусорная" база - это отдельная база данных на ненадёжных быстрых носителях, предназначенная для хранения слабо связанных не критичных для основного сервиса данных. Для неё не используется репликация. Выборки по такой базе производятся редко. Обрыв соединения с "мусорной" базой не критичен для основного сервиса.

В данный момент поддержано хранение в "Мусорной" базе таблиц:

log_function_process_yyyyMM - логи работы BGBS-скриптов на договорах;
log_server_<mid>_yyyуMM - логи RADIUS-запросов модулей DialUp/VoiceIp;
reject_to_accept_<mid> - подмена reject'а accept'ом при ошибке авторизации.

"Мусорная" база определяется в конфигурации сервера биллинга (Сервис=>Настройки) следующим образом:

db.trash.<trash_id>.url=jdbc:mysql://<host>:<port>/<db_name>?useUnicode=true&characterEncoding=UTF-8&allowUrlInLocalInfile=true&zeroDateTimeBehavior=convertToNull&jdbcCompliantTruncation=false&elideSetAutoCommits=true&useCursorFetch=true&queryTimeoutKillsConnection=true
db.trash.<trash_id>.user=<user>
db.trash.<trash_id>.pswd=<pswd>
db.trash.<trash_id>.maxIdle=<max_idle>
db.trash.<trash_id>.maxActive=<max_active>

Где:

<trash_id> - идентификатор "Мусорной" базы;
<db_name> - имя базы данных;
<host> - хост с Мусорной базой;
<port> - MySQL порт;
<user> - логин MySQL;
<pswd> - пароль MySQL;
<max_idle> - максимальное число простаивающих соединений в пуле, лишние будут закрыты;
<max_active> - максимальное число активных соединений в пуле.

После определения "мусорной" базы необходимо указать префиксы таблиц, которые хранятся в этой базе:

trash.table.map.<pos>.<table_prefix>=<trash_id>

Где:

<trash_id> - идентификатор "Мусорной" базы;
<pos> - порядковый номер правила для просмотра;
<table_prefix> - префикс таблицы.

Например, так можно определить хранение таблиц log_function_process в отдельной мусорной базе:

db.trash.trash_1.url=jdbc:mysql://192.168.184.2:3306/trash_1?useUnicode=true&characterEncoding=UTF-8&allowUrlInLocalInfile=true&zeroDateTimeBehavior=convertToNull&jdbcCompliantTruncation=false&elideSetAutoCommits=true&useCursorFetch=true&queryTimeoutKillsConnection=true
db.trash.trash_1.user=root
db.trash.trash_1.pswd=
db.slave.trash_1.maxIdle=10
db.slave.trash_1.maxActive=4
#
trash.table.map.1.log_function_process=trash_1

Внимание

Функционал "мусорных" хранилищ экспериментальный, рекомендуется начать использование с таблиц, не используемых критичными сервисами (log_function_process).

24.4. Настройка типа хранения помесячных и подневных таблиц в MySQL

Для периодических таблиц (помесячных вида xxx_mid_yyyyMM и подневных вида xxx_mid_yyyyMMdd) таблиц можно задавать отдельно "движок" и папку для хранения данных и индексов (эта опция поддерживается только для MyIsam). Необходимо указывать в конфигурации сервера биллинга (меню Сервис=>Настройкa=>Конфигурация).

table.create.<table_name>.data.directory=<data_dir>
table.create.<table_name>.index.directory=<index_dir>
table.create.<table_name>.engine=<engine>

Где:

<table_name> - это часть имени периодической таблицы, в которую не входит дата;
<data_dir> - каталог для хранения данных таблицы (работает только для MyIsam-таблиц);
<index_dir> - каталог для хранения индексов таблицы (работает только для MyIsam-таблиц);
<engine> - "движок" хранения таблиц (InnoDB, MyIsam).

Например:

table.create.log_session_12.data.directory=/home/mysql
table.create.log_session_12.index.directory=/home/mysql
table.create.log_session_12.engine=INNODB

Указанные значения преобразуются в атрибуты DATA DIRECTORY, INDEX DIRECTORY и ENGINE команды CREATE TABLE при создании новой периодической таблицы. Более подробно читайте об этом в документации по MySQL.

Рекомендуется использование движка InnoDb для критических таблиц с большим количеством конкурирующих операций чтения-записи и MyIsam-движка для редко считываемых таблиц (различные логи).

Внимание

Для оптимизации вставки в таблицы логов часто используется опция DELAYED INSERT, которая поддерживается только для "движка" MyIsam.

24.5. Параметры запуска клиента

В файле запуска клиента можно указывать следующие параметры:

-Dbgbilling.transfer.debug=true - выводить debug 
-Dbgbilling.client.os=linux - операционная система.   
-Dlocal.setting.file.name=config_v.4.5 - имя файла с настройками в папке пользователя.
-Dsun.net.client.defaultConnectTimeout=1000 - таймаут получения URL для клиента, если в FOP, например, есть недоступная картинка.
-Duser.home - домашаняя папка клиента (в которой хранится local.setting.file.name)
-Dshared.client.distribution=1 - при обновлении клиента в сетевой папке, все запущенные клиенты перезагружаются.

Глава 2. Расширение функциональности BGBilling

1. Назначение

BGBilling поддерживает возможность гибкого расширения функциональности системы путём написания пользовательских скриптов, которые могут: обрабатывать различные события системы, выполняться обособленно, управлять устройствами и т.д. Имеется возможность разработки расширений функциональности на следующих языках:

  • язык Java - обработчики событий могут быть реализованы в виде Java-классов, которые компилируются и загружаются динамически; использование Java в качестве пользовательских скриптов предпочтительнее как с точки зрения удобства и возможностей разработки, так и с точки зрения производительности самих скриптов (быстрее до 50 раз).

  • язык BGBS - это интерпретируемый Java-подобный язык программирования, который хорошо подходит для написания небольших скриптов, время выполнения которых не критично. BGBS представляет собой интегрированный в биллинг интерпретатор языка BeanShell (http://www.beanshell.org/) + API для управления данными биллинга и набор событий биллинга, которые можно обрабатывать. Разработка на BGBS требует знание языка Java, т.к. большинство вызовов BeanShell прозрачно переадресуются Java API. Синтаксис BeanShell также практически полностью идентичен Java.;

Пользовательские скрипты Java/BGBS могут использоваться как:

Скрипты поведения - привязанные к договорам и обарабатывающие определенные события, происходящие с ними;
Функции глобальных событий - обработчики событий системы, не свзязанных с конкретными договорами;
Глобальные скрипты поведения - выполняемые периодически или единоразово действия.

Только пользовательские скрипты в виде динамических Java классов могут использоваться как:

Скрипты пред- и постобработки запросов, скрипты управления сервисом в модуле Inet.

Только пользовательские BGBS скрипты могут использоваться как:

Скрипты предобработки RADIUS запросов, привязаных к NASам модулей DialUp/VoiceIp и производящих предобработку RADIUS запросов;
Скриптовые шлюзы модуля IPN - скрипт производит управление шлюзом.

Примеры использования скриптов доступны в базе знаний WiKi. Вы также можете публиковать там свои разработки.

2. Управление динамическим кодом

Замечание

Для более полного понимания данной секции необходимо владеть базовыми знаниями Java (прочитать об этом можно, например, на официальном сайте http://download.oracle.com/javase/tutorial/).

Параметры подсистемы динамического кода настраиваются в конфигурации сервера.

Для встраивания дополнительной функциональности посредством написания Java-классов, необходимо предварительно скомпилировать и загрузить их в базу данных биллинга. Уникальным идентификатором каждого динамического класса является его полное имя - это имя, включащее как имя пакета (своебразного пространства имён в Java - оно совпадает со структурой каталогов, в которых лежит класс) класса, так и самого имени класса. Например: ru.bitel.bgbilling.Test - это полное имя класса Test, который лежит в пакете ru.bitel.bgbilling.

Исходные коды динамического Java-кода хранятся по умолчанию в каталоге BGBillingServer/dyn.

Каждый класс для реализации конкретной функциональности (например, скрипта поведения) должен реализовывать определённый интерфейс (в каждом случае свой). После этого его необходимо скомпилировать и он станет доступен для выбора в соответствующем меню привязки динамического класса.

Для работы с динамически загружаемыми классами из клиента биллинга необходимо воспользоваться пунктом меню Сервис=>Автоматизация=>Управление динамическим кодом.

Дерево динамических классов можно видеть на панели слева. Изменённые, но не перекомпилированные классы отображаются в дереве со значком * (это будет работать ТОЛЬКО в случае, если файловая система, в которой хранятся скрипты, поддерживает хранение времени последнего изменения файла, в противном случае все исходные коды всегда будут помечены как изменённые).

Для открытия существующего класса на редактирование необходимо выбрать нужный класс в дереве классов слева и щелкнуть на кнопку Редактировать на стандартной панели инструментов, либо открыть класс двойным щелчком мыши. Каждый класс открывается в отдельной вкладке.

Для создания нового класса необходимо нажать кнопку Новый элемент на стандартной панели инструментов. Откроется диалоговое окно, в котором будет предложено ввести полное имя класса. Полное имя класса включает в себя пакет, в котором располагается класс. Пакет по своей сути представляет собой папку в файловой системе. Пакеты разделяются между собой символом "." (точка). Обратите внимание, что если в дереве классов выбрать предварительно какой-либо пакет и нажать кнопку создания нового класса, то этот пакет автоматически подставится в поле диалогового окна.

Для полной перекомпиляции всех исходных кодов необходимо нажать кнопку Скомпилировать всё. Для компиляции отдельных классов необходимо открыть их в дереве по двойному щелчку и нажать кнопку Сохранить и скомпилировать. Ошибки и предупреждения компилятора можно увидеть в открывающейся панели Сообщения компилятора. В случае ошибки в процессе компиляции некоторого класса никаких изменений в базе данных скомпилированных классов не произойдет. Это означает, что будет работать последняя работоспособная версия динамического класса.

Для удаления класса (или группы классов) необходимо выбрать их в дереве классов и нажать кнопку Удалить в панели инструментов. Перед удалением выбранных классов производится полная перекомпиляция динамических классов без участия удаляемых классов для проверки на наличие зависимостей оставшегося кода от них. В случае, если компиляция пройдет с ошибками, то удаление классов не будет произведено для сохранения работоспособности оставшегося кода!

Внимание

Обратите внимание, что привязка удаляемых классов в различных подсистемах (скрипты поведения, глобальные скрипты и т.п.) не проверяется! Удаление классов производится на свой страх и риск. В случае оставшейся привязки удалённого класса к какой-либо подсистеме, корректное поведение этой подсистемы не гарантируется!

Одним из преимуществ такого подхода к разработке расширений биллинга состоит в том, что возможна организация полноценной работы в IDE (автодополнение, проверка кода на ошибки и т.п.). Пример, как это сделать, вы можете найти в WiKi.

Для возможностей отладки и удобного запуска можно запустить код прямо из редактора.

Сначала пытается запуститься метод execute как у глобальных скриптов (можно просто добавить этот метод с такой сигнатурой). Если такой метод есть, то создаётся экземпляр класса и в него передаются объекты типа ru.bitel.bgbilling.server.util.Setup и ru.bitel.common.sql.ConnectionSet, как в глобальные скрипты. Первый содержит в себе конфигурацию приложения, второй - набор соединений к БД (основной, slave и "мусорной" и при наличии ). Если такого метода нет, то ищется стандартный метод public static void main(String[] args).

3. Скрипты поведения

3.. Общие сведения

Скрипты поведения предоставляют возможность пользователю произвольным образом обрабатывать события договоров биллинга. События делятся на два типа: синхронные (запросы) и асинхронные (сообщения).

При обработке асинхронного события (сообщения) программа не ждёт ответа обработки события, продолжая работать дальше. Само событие передается через ActiveMQ сервер данных центральному интерпретатору, работающему в процессе сервера биллинга.

Синхронное событие (запрос) обрабатывается в процесе программы, породившем его и результат обработки используется в дальнейшей работе программы. Примером запроса является событие Запрос учётного периода в модуле DialUP. Обработка синхронного запроса, порожденного сервером биллинга так же производится центральным интерпретатором и не отличается по возможностям от асинхронного.

Для модификации данных в БД можно использовать как напрямую Java SQL API так и предлагаемые с BGBilling API, описанное в разделе документации API документация для разработки скриптов. Все классы-события расширяют базовый класс ru.bitel.bgbilling.kernel.event.Event.

Для получения имени класса события воспользуйтесь горячей клавишей Ctrl + i, располагаясь на списке событий в редакторе привязки событий к скрипту BGBS, либо Java-классу (см. далее). В JavaDoc по классу события представлена полная информация по событию.

3.2. Создание скрипта поведения

Скрипты поведения заводятся в Справочники=>Другие.

В меню Сервис=>Автоматизация=>Скрипты поведения производится привязка к скрипту поведения его функций. Оно содержит две вкладки: Скрипты BGBS и Классы Java.

3.3. Привязка динамически загружаемых Java-классов к скриптам поведения

Вкладка Классы Java содержит интерфейс управления привязкой динамических классов к скриптам поведения. Добавление привязки динамически загружаемого класса Java к скрипту поведения в качестве реакции на определённое событие в целом аналогично такому же действию при добавлении функции скрипта поведения на BGBS. Однако в качестве прямого редактирования кода предлагается выбрать лишь один из динамических классов, реализующих интерфейс ru.bitel.bgbilling.kernel.script.server.dev.EventScript, можно использовать наследование от класса ru.bitel.bgbilling.kernel.script.server.dev.EventScriptBase.

В базовом классе реализованы методы print и error, позволяющие выводить отладочную информацию и сообщения об ошибках простым способом, обеспечивая их попадание в логи выполнения скриптов.

Элемент управления для выбора динамического класса универсален для всех подсистем биллинга, использующих такой вариант расширения функциональности. Он содержит выпадающий список динамических классов, реализующих необходимый интерфейс, кнопку создания нового класса этого интерфейса, а также кнопку редактирования выбранного класса.

Получение имени класса события по Ctrl + i.

3.4. Написание функций скрипта поведения на языке BGBS

Первая вкладка содержит возможность управления функциями скрипта поведения, написанными на BGBS.

Внимание

Данная подсистема оставлена для совместимости с ранними версиями биллинга. Предпочтительно использовать динамический Java код.

Получение имени класса события по Ctrl + i.

Редактор скриптов обладает подсветкой синтаксиса, индикацией строки и позиции и следующими горячими клавишами:

Ctrl+X - вырезать
Ctrl+C - копировать
Ctrl+V - вставить
Ctrl+Z - отменить
Ctrl+R - повторить
Ctrl+L - переход к строке

При редактировании скриптов нет необходимости перезагрузки запускающих их приложений, достаточно поправить и сохранить нужный скрипт. Перед сохранением скрипта производится его синтаксический анализ с выявлением ошибок, если они есть.

Если во время редактирования скрипт был изменен другим пользователем, то при сохранении выводится сообщение об этом с указанием имени и логина пользователя, внесшего изменения.

Программирование в BeanShell в целом идентично Java, но есть некоторые исключения:

print( "test" ) - вывод строки (будет видна в логе обработки) вместо System.out.println( "" ).
error( "error" ) - вывод ошибки вместо System.err.println( "" ).

При обработке события в скрипт передаются следующие переменные:

con - объект типа java.sql.Connection - соединение с базой биллинга;
conSlave - объект типа java.sql.Connection - соединение с Slave базой биллинга, либо Master, если ее нет;
setup - объект класса ru.bitel.bgbilling.server.util.DefaultServerSetup - конфигурация сервера биллинга;
event - объект, расширяющий bitel.billing.server.script.bean.event.Event - содержит класс-описание события.

Тело скрипта может выглядеть, например, следующим образом. Приведен пример обработки абстрактного события. Это оптимальная по производительности схема скрипта, когда главная функция onEvent интерпретируется один раз и далее запускается многократно.

import bitel.billing.server.contract.bean.*;
import bitel.billing.server.util.*;
import java.sql.*;
import java.util.*;
import bitel.billing.server.contract.bean.*;

includeBGBS( "bgbs://ru.bitel.bgbilling.kernel.script.common.bean.ScriptLibrary/default" );

public void onEvent( event, setup, con, conSlave ) 
{
   if( event.getActionId() != 3333 ) 
   {
     return;
   }

   gets(event);

   event.addReport(doSomething("vvv"));
}

Вот эта же функция, переписанная по-старому (работает медленнее в 8-10 раз):

import bitel.billing.server.contract.bean.*;
import bitel.billing.server.util.*;
import java.sql.*;
import java.util.*;
import bitel.billing.server.contract.bean.*;

includeBGBS( "bgbs://ru.bitel.bgbilling.kernel.script.common.bean.ScriptLibrary/default" );

if( event.getActionId() != 3333 ) 
{
   return;
}

gets(event);

event.addReport(doSomething("vvv"));

Обратите внимание на инструкцию включения библиотеки:

includeBGBS( "bgbs://ru.bitel.bgbilling.kernel.script.common.bean.ScriptLibrary/default" );

Сами библиотеки скриптов определяются в меню Сервис=>Автоматизация=>Библиотеки скриптов. Для каждой библиотеки должно быть определено уникальное имя. Библиотека представляет из себя функции, которые становятся доступными после включения в скрипте инструкции includeBGBS. На снимке ниже представлен код библиотеки default, использованной в скрипте выше.

Библиотеку можно включить из другой библиотеки, но данный подход не рекомендуется, т.к. по неосторожности можно создать зацикливание включения библиотек.

3.5. Привязка скриптов поведения к договору

Привязка скриптов поведения к договору производится выбором узла дерева карточки договора Скрипт. При добавлении нескольких скриптов в договор, событие будет передаваться в каждый из них.

На вкладке Логи выполнения отображаются логи выполнения события скриптами. Например, при описанном выше скрипте после прихода платежа в логах будет следующая запись:

Замечание

Сообщения об ошибках выполнения скриптов отправляются на E-Mail посредством системы оповещения биллинга.

4. Скрипты поведения глобальных событий

Скрипты поведения глобальных событий отличаются от скриптов поведения тем, что связанные с ними события не прикреплены к договорам. Для вызова редактора выполните Сервис=>Автоматизация=>Функции глобальных событий. Редактор аналогичен редактору скриптов поведения.

5. Глобальные скрипты

Глобальные скрипты предоставляют пользователю биллинга возможность выполнения произвольного кода для взаимодействия с API BGBilling без привязки к событийной модели. Глобальные скрипты могут быть использованы как для однократного выполнения некоторого сложного взаимодействия с данными (что сложно было бы реализовать возможностями SQL-редактора), так и для периодического (об этом см. ниже).

Для доступа к глобальным скриптам необходимо открыть меню Сервис=>Автоматизация=>Глобальные скрипты поведения. В открывшейся вкладке представлено две вкладки - Скрипты и Логи. Во вкладке Скрипты представлено две вкладки: Классы Java и Скрипты BGBS.

Вкладка Логи отображает информацию о выполнении скрипта. Абсолютно идентична логам событийных скриптов в карточке договора (см. здесь).

5.1. Глобальные скрипты с использованием динамических классов Java

Во вкладке Классы Java расположен список всех доступных глобальных скриптов, привязанных к динамически загружаемым классам. Для создания, удаления и редактирования скриптов необходимо воспользоваться соответствующими кнопками панели инструментов. Двойной щелчок по уже созданному скрипту также открывает редактор.

Как и в случае со скриптами поведения, вместо редактора кода скрипта представлена панель привязки динамического класса к глобальному скрипту.

Класс, привязанный к глобальному скрипту, должен расширять базовый класс ru.bitel.bgbilling.kernel.script.server.dev.GlobalScriptBase. Для однократного выполнения глобального скрипта необходимо нажать на кнопку Выполнить скрипт. Выполнение скрипта происходит асинхронно. Результат выполнения скрипта логируется (см. вкладку Логи).

5.2. Глобальные скрипты на языке BGBS

Во вкладке Скрипты BGBS отображен список всех доступных скриптов. Для создания, удаления и редактирования скриптов необходимо воспользоваться соответствующими кнопками панели инструментов. Двойной щелчок по уже созданному скрипту открывает редактор.

При создании/редактировании скрипта должны быть соблюдены следующие условия. Во-первых, обязательно должно быть задано имя скрипта. Во-вторых, тело скрипта обязательно должно содержать функцию main, как представлено на скриншоте выше. В функцию main передаются следующие аргументы:

con - объект типа java.sql.Connection - соединение с базой биллинга;
conSlave - объект типа java.sql.Connection - соединение с Slave базой биллинга либо Master, если ее нет;
setup - объект класса ru.bitel.bgbilling.server.util.DefaultServerSetup - конфигурация сервера биллинга.

Для однократного выполнения глобального скрипта необходимо (предварительно его сохранив) нажать на кнопку Выполнить скрипт. Выполнение скрипта асинхронно. Результат выполнения скрипта логируется (см. вкладку Логи).

5.3. Периодическое выполнение глобальных скриптов

Для периодического выполнения глобальных скриптов необходимо в Сервис=>Администрирование=>Планировщик заданий создать задачу планировщика "Выполнение глобальных скриптов по таймеру".

В качестве параметра для задачи необходимо указать tids=X,Y,Z, где X,Y,Z - коды скриптов, перечисленные через запятую.

По причине появления глобальных скриптов двух типов (BGBS и Java) был добавлен опциональный флаг type, обозначающий желаемый тип выполняемого глобального скрипта. При type=0 (по умолчанию) в качестве скриптов выполняются соответствующие указанным кодам скрипты на BGBS, в случае же type=1 - на Java.

6. Резервные копии

Для скриптов поведения и библиотек есть возможность сохранять резервные копии. Для этого в всех редакторах доступна кнопка "Сохранить резервную копию". Так же доступна возможность просмотреть список резервных копий с помощью кнопки "История".

Двойным кликом можно просмотреть конкретную версию скрипта.

7. Скрипты предобработки RADIUS запросов

Ещё одним применением скриптов являются скрипты предобработки RADIUS запросов, позволяющие модифицировать запрос приводя его к требованиям биллинга, определяет вид услуги запроса и т.п. Скрипт предобработки вводится в редакторе NASов модулей DialUp и VoiceIp. В скрипт передаются следующие переменные:

con - объект типа java.sql.Connection, соединение с базой биллинга
conSlave - объект типа java.sql.Connection, соединение с Slave базой биллинга, либо основной, если Slave нет
setup - объект класса bitel.billing.server.radius.RadiusSetup, конфигурация сервера RADIUS
request - объект класса bitel.billing.server.radius.RadiusPacket, RADIUS запрос
response - объект класса bitel.billing.server.radius.RadiusPacket, RADIUS ответ

Образец скрипта. Как и в случае со скриптами предобработки, можно не объявлять функцию, сразу размещая логику скрипта. Но скорость работы скрипта при этом будет меньше.

import ru.bitel.bgbilling.kernel.network.radius.*;
 
void processRequest( request, response, setup, con, conSlave )
{
   //логика предобработки 
}

При модификации скрипта предобработки требуется перезапуск RADIUS сервера. Вывод работы скриптов и ошибки доступны в логе script.log RADIUS сервера. Скрипты предобработки RADIUS запроса не привязаны к договору, а привязаны к NASу, т.к. выполняются сразу после получения запроса, когда еще не известно, к какому клиенту будет соотнесен запрос.

8. Интеграция с внешними системами

Из структуры биллинга можно определить два способа взаимодействия с ним извне:

обращение к базе данных - допустимо для выборок данных либо для быстрого внесения изменений, не предполагающих реакции сервера;
обращение к серверу биллинга - выполнение действий аналогично оператору из АРМ биллинга посредством обращений сторонней системы.

При выполнении обращений к серверу биллинга помимо записи данных в БД могут производится различные дополнительные обработки самим сервером. Например: разблокировка модулей по платежу.

К серверу биллинга возможно обращаться из сторонних приложений посредством HTTP запросов. Пример запросов можно изучить вызывая различные действия в клиентском приложении, запущенном в через client_debug.bat (.sh). Запросы и ответы распечатываются в log файл. Биллинг поддерживает несколько вариантов протоколов обращений для различных действий, их можно определить по внешнему виду запросов.

8.1. HTTP Action

Более ранний протокол. Подразумевает передачу параметров в HTTP запросе с получением XML ответа. Примерный вид запроса и ответа в логе клиента:

http://billing:8081/executer?module=npay&action=ServiceSetList&mid=6&BGBillingSecret=ONM13dhRxs8VDD9wFCzpPOrU&
[ length = 159 ] xml = <?xml version="1.0" encoding="UTF-8"?><data secret="B802E452DF43140146D0EC4219C847D1" status="ok"><list><item id="0" title="Полный набор услуг"/></list></data>

Дополнительно необходимо добавить в запрос параметры user и pswd с логином и паролем пользователя биллинга, от лица которого отправляется запрос. Рекомендуется добавить к запросу параметр authToSession=0, это предотвратит создание HTTP сессий, уменьшит потребление памяти на сервере.

В целях отладки запросы можно отправлять прямо в браузере.

8.2. Web - сервис

Более новые вызовы реализованы как Web-сервисы, пример обращения к ним вы можете посмотреть в WiKi. Используется Basic авторизация.

Примерный вид запроса и ответа:

http://billing:8081/executer/ru.bitel.bgbilling.kernel.module/ServiceService?wsdl -> {http://service.common.module.kernel.bgbilling.bitel.ru/}ServiceService:serviceList
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/"><S:Body><ns5:serviceList xmlns:ns5="http://service.common.module.kernel.bgbilling.bitel.ru/" xmlns:common="http://common.bitel.ru" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"><moduleId>9</moduleId></ns5:serviceList></S:Body></S:Envelope>
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/"><S:Header/><S:Body><ns5:serviceListResponse xmlns:ns5="http://service.common.module.kernel.bgbilling.bitel.ru/" xmlns:common="http://common.bitel.ru" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:S="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xml="http://www.w3.org/XML/1998/namespace"><return id="15" moduleId="9" title="Рекламный блок на Board.ufanet.ru в одном разделе (справа)" unit="0" using="true"/><return id="7" moduleId="9" title="Рекламный блок на Board.ufanet.ru в разделе &quot;Авторынок&quot; (справа)" unit="0" using="true"/><return id="12" moduleId="9" title="Рекламный блок на Board.ufanet.ru в разделе &quot;Аудио, видео, фототехника&quot; (справа)" unit="0" using="true"/><return id="6" moduleId="9" title="Рекламный блок на Board.ufanet.ru в разделе &quot;Компьютеры&quot; (справа)" unit="0" using="true"/>

8.3. Web - сервис через JSON RPC

Для более простого обращения к Web сервисам возможно использование протокола JSON RPC.

Запрос выглядит следующим образом, пример:

http://127.0.0.1:8080/bgbilling/executer/json/ru.bitel.bgbilling.kernel.contract.api/ContractService

{"method" : "contractList",
"user" :{ "user" : "shamil", "pswd" : "xxxx" },
"params" : {
"title" : "0",
"fc" : -1,
"groupMask" : 0,
"subContracts" : false,
"closed" : true,
"hidden" : false,
"page" : { "pageIndex" : 2, "pageSize" : 2 }
} }

URL запроса определяет Web-сервис, JSON запрос передаётся в теле запроса, кодировка UTF-8. Обязательные параметры:

method - вызываемая функция сервиса;
user - объект с логином и паролем пользователя, от лица которого выполняется действие;
params - объект со всем остальными параметрами сервиса.

Замечание

Обязательно указание значений всех параметров с примитивными типами: int, boolean.

Примерный вид корректного ответа:

{"status":"ok","message":"",
"data":
{
"page":{"pageSize":2,"pageIndex":2,"pageCount":49,"recordCount":97,"pageFirstRecordNumber":2},
"return":
[{"id":353023,"title":"0022010","groups":0,"password":"bg2rFZ2PEX","dateFrom":"2010-01-02","dateTo":null,"balanceMode":0,"paramGroupId":14,"personType":0,"comment":"","hidden":false,"superCid":0,"dependSubList":"","status":0,"statusTimeChange":"2010-01-13","titlePatternId":0,"balanceSubMode":0,"sub":false,"independSub":false,"balanceLimit":0.00,"super":false,"dependSub":false},
{"id":353209,"title":"06-10-10/И-Г/0","groups":0,"password":"9351220759","dateFrom":"2010-10-06","dateTo":null,"balanceMode":1,"paramGroupId":14,"personType":0,"comment":"","hidden":false,"superCid":0,"dependSubList":"","status":0,"statusTimeChange":"2010-10-06","titlePatternId":0,"balanceSubMode":0,"sub":false,"independSub":false,"balanceLimit":0.00,"super":false,"dependSub":false}]}}

В status возвращается ok в случае корректного ответа, либо error - ошибка. При этом в message выводится текст ошибки.

Там выглядит сообщение об ошибке:

{"status":"error","message":"Неправильный пароль.","data":{}}

В случае корректного ответа в data возвращаются результаты выполнения. Возвращаемый методом параметр под ключом return.

Также возможен возврат результатов из параметров сервиса посредством объекта типа javax.xml.ws.Holder.

Для работы с сервисом необходимо найти его класс в JavaDoc, например: ContractService. Далее определить имена и типы передаваемых параметров, переходя к JavaDoc описаниям других классов, если понадобится.

Некоторую сложность представляет передача параметров, в роли которых могут выступать классы-потомки указанного в JavaDoc класса. Для примера рассмотрим параметр entityFilter указанного ранее сервиса, метод contractList. В качестве параметров передаются наследники объекта FilterEntityAttr. В JavaDoc данного класса находим:

@JsonTypeInfo(use=NAME, 
               include=PROPERTY,
              property="type")
@JsonSubTypes(value={
@JsonSubTypes.Type(name="Address",value=FilterEntityAttrAddress.class),
@JsonSubTypes.Type(name="Date",value=FilterEntityAttrDate.class),
@JsonSubTypes.Type(name="House",value=FilterEntityAttrHouse.class),
@JsonSubTypes.Type(name="Int",value=FilterEntityAttrInt.class),
@JsonSubTypes.Type(name="List",value=FilterEntityAttrList.class),
@JsonSubTypes.Type(name="Text",value=FilterEntityAttrText.class),
@JsonSubTypes.Type(name="Email",value=FilterEntityAttrEmail.class)})

Данные строки означают, что объекты маркируются дополнительным полем type, в зависимости от которого определяется класс переданного объекта. Вот так, например, выглядит запрос фильтрации договоров по текстовому параметру:

{"method" : "contractList",
"user" :{ "user" : "shamil", "pswd" : "xxxx" },
"params" :
{
"fc" : -1,
"groupMask" : 0,
"subContracts" : false,
"closed" : true,
"hidden" : false,
"page" : { "pageIndex" : 1, "pageSize" : 2 },
"entityFilter" : [ { "type" : "Text", "entitySpecAttrIds" : [2], "value" : "1"  } ]
}  }

Для тестирования запросов удобно использовать плагин браузера позволяющий отправку запросов (типа HttpRequester для FF), либо штатную возможность браузера.

Глава 3. Модуль Card

1. Назначение модуля

Модуль Карточки предназначен для совместного использования с модулями DialUP и VoiceIP для автоматического создания договоров и логинов, а также для пополнения баланса договора. В модуле происходит загрузка, учёт и активация предоплаченных интернет-карт. Кроме того поддерживается учёт дилеров-распространителей. С версии модуля 3.0 для дилеров поддерживается возможность удалённых платежей.

2. Настройка модуля

В редакторе модулей и услуг создайте модуль типа Карточки и добавьте туда одну услугу, например Интернет-карты. Подключите этот модуль всем тем договорам, которым хотите предоставить возможность пополнения баланса предоплаченными картами. Услугу Интернет-карты добавьте в список разрешённых услуг договоров.

Перезагрузите клиент биллинга. Зайдите на вкладку Конфигурация модуля, с помощью кнопки Создать создайте конфигурацию и добавьте в неё следующие параметры:

#шаблон создаваемых договоров
contract.pattern=T####-##
#расшифровки статусов
status.title.lock=Заблокирована 
status.title.pay=В продаже 
status.title.contract=Договор 
status.title.balance=Баланс
#название пункта меню на странице статистики
web.menuItem1=Пополнение счета с помощью Интернет-карт
#макрос формирования комментария платежа при его приходе через дилерский интерфейс, доступны подстановки:
#${dealer} - дилер, ${trans} - код транзакции, ${contract} - номер договора, ${comment} - комментарий платежа, ${summ} - сумма
payment.comment=Оплата по дог. ${contract} через ${dealer} (${comment})
#ссылка на статистику сервера
statistics.url=http://localhost:8080/bgbilling/webexecuter

Обратите внимание на параметр contract.pattern, он задаёт шаблон имени договоров, которым дилеры могут заносить платежи. Если шаблонов несколько, их нужно ввести через ";". В данном случае разрешено пополнять баланс договоров вида T5454-04, Twr34-03 и т.д. Символ # обозначает любой символ.

3. Дилеры

Дилеры модуля карточек могут в зависимости от установленных опций заниматься реализацией карт предоплаты и/или производить платежи в пользу провайдера через Web-интерфейс дилера.

Для добавления дилера перейдите на вкладку Менеджер дилеров и нажмите кнопку Добавить на панели инструментов.

В основных свойствах дилера присутствуют название и галочки разрешения приёма им платежей и карт. Кроме того указывается скидка в % на получение карт. Скидка на приём платежей в данной версии никак не используется.

Остальные параметры дилера, относящиеся к приёму платежей и работы с картами, разделены по вкладкам и описаны в соответствующих разделах.

4. Работа с карточками

Каждая карточка характеризуется 3 параметрами: серийный код, логин и пароль. Логин и пароль карты должны быть введены пользователем для её активации как DialUP/VoIP аккаунт, либо указаны при пополнении картой баланса через Web интерфейс, либо IVR-систему.

Серийный код и логин - числа до 2000000000, пароль - строка длиной до 32 символов латинского алфавита, либо цифр. При создании карт, предназначенных для активации посредством IVR, либо иным способом, не позволяющим вводить буквы, рекомендуется делать цифровые пароли.

Серийный номер карты используется для всех операций по управлению картой; для удобства его рекомендуется делать равным логину при первом выпуске карт. В дальнейшем по мере повторного выпуска карт с теми же логинами образовывать добавлением к логину слева цифр 1, 2, 3. Карты следует выпускать сериями с возрастающими на единицу логинами и паролями.

Файл для загрузки карт должен выглядеть подобным образом:

serial1<табулятор>login1<табулятор>pswd1
serial2<табулятор>login2<табулятор>pswd2

Например:

10001 1  545454
10002 2  545dd4

Вы можете использовать стандартный генератор карт, доступный на сайте, либо реализовать свой. Стандартный генератор позволяет сохранять карты в указанном выше формате.

Жизненный цикл карты включает в себя несколько состояний:

Заблокирована - только что загруженная в базу карта, не назначенная дилеру и не поступившая в продажу, она не может быть активирована;
Активна - карта передана дилеру и может быть активирована либо для создания договора и логина DialUP/VoiceIP, либо для оплаты услуг;
Договор - карта была использована для автоматического создания договора и DialUP/VoiceIP логина в нем;
Баланс - карта была использована для пополнения баланса.

Серийный номер карты должен быть уникален и никогда не повторяться, менеджер карт не даст вам загрузить карточку, если такой код уже есть в базе.

При активации карты для создания договора и логина логин и пароль карты преобразуется в логин и пароль модуля DialUP, либо модуля VoiceIP. Использовать данный логин для новый карты повторно можно только после того, как логины в модуле DialUP/VoiceIP будут освобождены и договоры удалены. Для проверки свободных логинов во всех модулях интегрирующихся с модулем карт есть вкладка Свободные логины.

Перед выпуском очередной серии карт следует проверить во всех модулях, где возможна активация карт данного типа в качестве логина, незанятость логинов карт. В противном случае при авторизации RADIUS-сервер будет находить старый логин и писать ошибку пароля карты. Галочка Исключить карточки исключает помимо логинов модуля логины карт из подключённого карточного модуля.

Карта, активированная для пополнения баланса, привязывается к договору, на который она была активирована и может оставаться в системе неограниченно долго.

Для загрузки карточек используется первая вкладка модуля Загрузка карточек.

При загрузке карт указываются следующие параметры:

путь к файлу карт - выбирается файл с данными карт, разделёнными табуляторами, каждая карта на новой строке (см. формат выше), при необходимости можно загрузить только часть строк из файла;
шаблон договора - по этому шаблону будет создан договор при активации карты для создания договора и логина;
сумма - номинал карты;
тип платежа - такого типа платёж будет занесён в созданный договор; тип платежа должен быть создан в справочнике типов платежа с галочкой нередактируемый. Сумма платежа равна номиналу карточки;
услуга пополенения баланса - баланс договора может быть пополнен этой карточкой только, если у договора есть в разрешённых данная услуга. Нужно это затем, чтобы возможно было создать карточки, которыми можно будет только создать договор, но не пополнять баланс;
услуга активации - фильтр по услугам активации можно указывать в конфигурации NASов модуля VoiceIP, либо DialUP. Так, например, можно создать карты, активируемые только на VoiceIP NASах, и универсальные карты, активируемые везде. Реализуется заведением 2х услуг и прописыванием их двоих на VoiceIP NASах и только услуги универсальной карты на всех других;
период - в течении данного периода карта должна быть активирована;
серия - название серии карт; серия используется для более удобного управления загруженными картами в дальнейшем.

Серии следует именовать подобным образом - "Универсальные 200 ки от 24.06.07 1000 штук" - для простой идентификации группы карт в дальнейшем. Если при загрузке какие-то данные были указаны неверно, вы можете редактировать карты, используя вкладку Серии. Также возможно удаление ошибочно загруженной серии.

Внимание

Обязательно указывайте серию для загружаемых карт.

При изменении серии изменяются свойства всех карт, входящих в неё. Обратите внимание на столбец Свободно - это количество свободных карт, оставшихся в серии.

Для распределения карточек по дилерам и просмотра текущего состояния базы карточек воспользуйтесь вкладкой Менеджер карт.

Текстовая область в верхней области фильтра - для поиска карты. Введите туда номер карты, будет отображён дилер, получивший эту карту, и её статус.

Кроме ввода одиночных номеров возможен ввод конструкций вида "N+K" (вывести карту с номером N и ещё K карт после неё). Таким образом можно выбирать диапазоны карт по серийным номерам. При пустых фильтрах система выводит все карты в постраничном режиме.

С 4.0 версии в таблице карт отображается номер договора, для создания или пополнения которого была использована карта. Двойной клик по строке открывает договор.

Набор флажков сверху позволяет выбирать нужные типы карточек. Для выбора карт, отданных какому-либо дилеру, выберите этого дилера в списке слева. Кнопка Сброс возвращает все фильтры в исходное состояние и убирает выделение со списка дилеров.

Чтобы отдать карточки дилеру на реализацию, выберите дилера в списке слева и нажмите Передать дилеру.

При передаче карт можно указать как количество карт выдаваемое из каждой серии (отображаются только не пустые серии), так и перечислить серийные номера карточек. При перечислении можно использовать следующие конструкции, разделённые точкой с запятой:

n1 - одиночный номер карты;
n3-n4 - серийные номера от n3 до n4 включительно;
n5+k - серийный номер n5 и k карт после него.

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

В таблице возможна установка фильтров по типу проводки (выдача/возврат) и по дилеру. Колонка Стоимость формируется с вычетом скидки, указанной в свойствах дилера. При просмотре проводки формируются Акт передачи/возврата и Заявка на выдачу/возврат карт.

Внешний вид документов задаётся шаблоном card_action_pdf.xsl. Исходный XML документ выводится в лог server.log при установке его в режим DEBUG.

В XML документ передаётся название и дата договора с дилером, которые должны быть указаны в свойствах дилера следующим образом:

Каждую проводку можно откатить до того момента пока какая-либо карта, участвующая в проводке, не изменила свой статус (не была активирована для выдачи, либо не была передана другому дилеру для проводок возврата).

Для возврата карт от дилера в Менеджере карт выберите дилера и нажмите Забрать у дилера. При этом можно указывать только серийные номера по тем же правилам, что и при передаче карт.

5. Генератор логинов и паролей для модуля "Карточки"

5.1. Установка генератора

Генератор логинов и паролей написан на Java. Следовательно, для его работы на машине должен быть установлен JDK или JRE версии 1.5.0 или выше.

Распакуйте архив с генератором в любое место вашего диска и запускайте "run.bat"

5.2. Использование генератора

После запуска генератора отображается окно.

Допустим, вам нужно сгенерировать карточки с серийными номерами 20 - 300, логины начиная с 3.

Вводим параметры в форму, заполняем мышкой правую область (ваши движения послужат основанием для генерации случайной последовательности ):

Если все прошло благополучно, будет выдано сообщение:

Далее выводится окно выбора файла, в который нужно сохранить пароли. Файл уже пригоден для загрузки в модуль Карточки.

Внимание

Файл XML-формата, в котором возможно сохранение сгенерированных карт, в данный момент не загружается модулем карточек.

6. Web-интерфейс

Добавив какому-либо пользователю услугу из модуля Карточки, вы предоставляете ему возможность пополнять баланс карточками, которые были загружены с этим типом услуги.

7. Web-активация

В конфигурации модуля карточек можно включить активацию карт на dialup/voiceip модули.

В конфигурации заводится тип активации activate.login.service.x. :

activate.login.service.x.title - Название активации

activate.login.service.x.sids - Услуга карты, с которой возможна активация, 0 - любая

activate.login.service.x.mid - Код модуля dialup/voiceip

activate.login.service.x.tariffs - Коды тарифов через запятую, из которых клиент может выбрать нужный

activate.login.service.x.tariffs.hidden - Коды тарифов через запятую, которые будут включены в договор, дополнительно к выбранному.

activate.login.service.x.group - Группа договоров, добавляемая в договор при создании

А также параметры договора, заполняющиеся при активации activate.login.param.x:

activate.login.param.x.title - Название параметра

activate.login.param.x.pid - Код параметра

activate.login.param.x.type - Тип параметра, text - текстовый, list - список, email, flag - флаг, phone - телефон

activate.login.param.x.require - 1 - обязательно для заполнения

activate.login.param.x.require.error - Выводимая ошибка, если параметр обязателен для заполнения, но не заполнен.

activate.login.param.x.pattern - regexp параметра, если есть и не совпадает со значением, то выводится ошибка:

activate.login.param.x.pattern.error - Выводимая ошибка при несоответствии с шаблоном

Активация будет доступна по такому URL:

http://provider:port/bgbilling/pubexecuter?action=CreateContract&module=card&mid=${mid}&activateType=${activateType}

где ${mid} - код модуля карточек, ${activateType} - код типа активации

При изменении xsl-шаблона можно создать другой файл и указать его в конфигурации activate.login.xsl=... По умолчанию используется card_create_contract.xsl

Пример конфигурации:

#Тип активации с кодом 1 (activateType=1)
#название
activate.login.service.1.title=WiFi
#услуги карточки, с которыми возможна активация, через запятую, 0 - все
activate.login.service.1.sids=0
#код модуля
activate.login.service.1.mid=21
#список возможных тарифов, коды через запятую
activate.login.service.1.tariffs=52
#добавляемая группа договора
activate.login.service.1.group=25
#
#Параметры договора для активации
#Название
activate.login.param.1.title=Введите ФИО:
#Код параметра
activate.login.param.1.pid=3
#Обязательность для заполнения
activate.login.param.1.require=1
#Выводимая ошибка, если параметр обязателен для заполнения и не заполнен
activate.login.param.1.require.error=Введите ФИО
#
activate.login.param.2.title=Выберите обслуживающее лицо:
activate.login.param.2.pid=28
#Тип параметра - список
activate.login.param.2.type=list
activate.login.param.2.require=1
activate.login.param.2.require.error=Выберите обслуживающее лицо
#
activate.login.param.3.title=Выберите статус:
activate.login.param.3.pid=29
activate.login.param.3.type=list
activate.login.param.3.require=0
#
activate.login.param.4.title=Введите email:
activate.login.param.4.pid=20
#Тип параметра - email
activate.login.param.4.type=email
#Шаблон (regexp) параметра
activate.login.param.4.pattern=^([a-zA-Z0-9_\.\-])+\@(([a-zA-Z0-9\-])+\.)+([a-zA-Z0-9]{2,4})+$
#Выводимая ошибка, если введённое значение не совпадает с шаблоном
activate.login.param.4.pattern.error=Адрес email введён неправильно
activate.login.param.4.require=0
#
activate.login.param.5.title=Нужность
activate.login.param.5.pid=26
#Параметр - флаг
activate.login.param.5.type=flag
activate.login.param.5.require=1
activate.login.param.5.require.error=Поставьте галочку на нужность

#
activate.login.param.6.title=Телефон
activate.login.param.6.pid=40
activate.login.param.6.type=phone
activate.login.param.6.require=0
activate.login.param.6.require.error=Введите телефон

8. Суперкарты

Суперкарты предназначены для использования единой базы карт на нескольких серверах биллинга. При этом один из карточных модулей на одном из серверов выступает первичным хранилищем - в нем заводятся карты, идёт учёт дилеров. Остальные модули на других серверах импортируют карты из супермодуля, если карта не найдена в самом модуле.

Супермодуль должен выступать только в таком качестве. Если на этой же машине необходимы его карты следует создать ещё один модуль и установить супермодуль для него.

Подключение супермодуля производится в конфигурации клиентского карточного модуля:

# конфигурация супер модуля
# база супер модуля
super.db.driver=com.mysql.jdbc.Driver
super.db.url=jdbc:mysql://<IP адрес сервера с супермодулем>/bgbilling?useUnicode=true&characterEncoding=UTF-8&allowUrlInLocalInfile=true&zeroDateTimeBehavior=convertToNull
super.db.user=<mysql логин>
super.db.pswd=<mysql пароль>
super.db.maxActive=5
super.db.maxIdle=2
#код супермодуля
super.mid=X
#договор в супербазе, к которому привязывать активированные карты
super.cid=<код договора>
#опции карты при импорте в текущую базу
#код дилера
#дилер Суперкарты
super.dealer.id=X
#услуга активации
super.act.sid=X
#услуга пополнения баланса
super.pay.sid=X
#код шаблона договора
super.pattern.id=X
#тип локального платежа для карты
#можно указывать одно число, либо соответствия вида <утп1:лтп1>;<утп2:лтп2>.. , где утп - удалённые типы платежа, лтп - в какой локальный тип преобразовывать
super.payment.type=X

При импорте карты из супермодуля в супербазе происходит пометка карты как активированной и привязка к указанному в параметре super.cid договору. При импорте все параметры карты выставляются так, как указано в конфигурации, значения параметров в супермодуле значения не имеет. Вместо X должны быть установлены числовые параметры.

Внимание

Для активации работы с супермодулем у клиентских модулей карточек ОБЯЗАТЕЛЬНО необходимо правильно заполнить ВСЕ параметры! Если клиентский модуль при поптыке доступа к супермодулю обнаруживает какое-либо несоответствие (отсутствующий параметр, неверные реквизиты базы и т.п.), то он более не пытается осуществить подключение к супербазе до следующей перезагрузки сервера. Это объясняется тем, что, возможно, от модуля и не требуется обращения к супермодулю (вообще не указаны никакие параметры), поэтому каждый раз заново перечитывать конфигурацию нет смысла.

9. IVR-Система

Модуль карточек поддерживает следующие функции IVR: озвучивание информации о балансе пользователя и пополнение счета картой. При проверке баланса у пользователя запрашивается пароль доступа к Web-статистике, который должен быть цифровым. Система построена на VXML.

Набор тестовых IVR-скриптов вы можете загрузить с сервера. Архив ivr.zip содержит:

  • bgivr.vxml - основной скрипт

  • menu.vxml - пункты меню

  • promts - фразы

Архив необходимо распаковать и разместить на HTTP сервере, доступным с CISCO.

Общий алгоритм работы скрипта следующий:

  1. с помощью голосового меню пользователь выбирает тип требуемого договора (при этом происходит определение адреса сервера биллинга и кода типа договора);

  2. запрашивается номер договора без тире, при этом клиент вводит слитно и номер и две последних цифры года, происходит запрос на сервер для определения существования договора;

  3. пользователь выбирает вид операции: активация карты, либо произнесение остатка на счёте;

  4. если выбрано произнесение остатка, то запрашивается пароль и происходит обращение на сервер биллинга, который либо возвращает ошибку, если пароль не верен, либо генерирует VXML скрипт, произносящий баланс;

  5. если выбрана активация карты, то запрашиваются слитно логин и пароль карты, которые отправляются в запросе на сервер. Карта либо успешно активируется, либо сервер возвращает код ошибки.

Для настройки скриптов в файле bgivr.vxml необходимо настроить адреса серверов биллинга и коды карточных модулей. Также необходимо установить параметр prompt_url - путь к папке с фразами на вашем HTTP сервере.

<var name="module" expr="'card'"/>
<var name="contentType" expr="'stream'"/>
<var name="prompt_url" expr="'http://bgbilling.bitel.ru/patch/vxml/prompts'"/>

<var name="billing_ds" expr="'http://stat1.ufanet.ru/bgbilling/pubexecuter'"/>
<var name="mid_ds" expr="'8'"/>

<var name="billing_bis" expr="'http://stat2.ufanet.ru/bgbilling/pubexecuter'"/>
<var name="mid_bis" expr="'1'"/>

<var name="billing_tks" expr="'http://stat3.ufanet.ru/bgbilling/pubexecuter'"/>
<var name="mid_tks" expr="'1'"/>

Также необходимо установить адреса серверов и коды карточных модулей. В приведённом примере скрипт обслуживает 3 сервера биллинга: Кабельное ТВ, Скоростной интернет и DialUP+VOIP. Далее клиент выбирает нужный тип договора.

На сервере биллинга в модуле карт должны быть настроены:

1) правила разделения логинов+паролей карт различной длины на, собственно, логин и пароль, например, данная строка означает, что если длина логина с паролем составляет 11 символов, то 6 из них - логин

#универсальная карта
ivr.card.size.11.login.length=6

2) правила преобразования номера договора, введённого слитно (в данном примере - числовая часть и две цифры года на конце договора) в зависимости от кода типа договора (приходит в запросе)

#phone - введённая клиентом последовательность цифр, для типа договора 1 она дополняется префиксом ГТФ, далее берутся все исключая 
#2 последние цифры phone, затем - и 2 последние цифры phone
#например 444406 -> ГТФ4444-06
#
ivr.contract.type.1.pref=ГТФ
ivr.contract.type.1.prepare=phone.substring( 0, phone.length() - 2 ) + "-" + phone.substring( phone.length() - 2, phone.length() );
#
ivr.contract.type.2.pref=NK
ivr.contract.type.2.prepare=phone.substring( 0, phone.length() - 2 ) + "-" + phone.substring( phone.length() - 2, phone.length() );
ivr.contract.type.3.pref=N
ivr.contract.type.3.prepare=phone.substring( 0, phone.length() - 2 ) + "-" + phone.substring( phone.length() - 2, phone.length() );
ivr.contract.type.4.pref=NA
ivr.contract.type.4.prepare=phone.substring( 0, phone.length() - 2 ) + "-" + phone.substring( phone.length() - 2, phone.length() );
ivr.contract.type.5.pref=R
ivr.contract.type.5.prepare=phone.substring( 0, phone.length() - 2 ) + "-" + phone.substring( phone.length() - 2, phone.length() );
ivr.contract.type.6.pref=RK
ivr.contract.type.6.prepare=phone.substring( 0, phone.length() - 2 ) + "-" + phone.substring( phone.length() - 2, phone.length() );
ivr.contract.type.7.pref=ГТЮ
ivr.contract.type.7.prepare=phone.substring( 0, phone.length() - 2 ) + "-" + phone.substring( phone.length() - 2, phone.length() );

В общем случае преобразование может быть и более сложным, язык макроса - BeanShell. Запросы на IVR-сервер и ответы сервера доступны в логе server.log, для этого необходимо установить его уровень логиновария в DEBUG в файле data/log4j_server.properties.

10. Удалённые платежи

Система дилерских платежей. Стандартный клиент интерфейса дилера реализован на AJAX и, запускаясь в браузере дилера, позволяет проводить платежи в пользу провайдера. Обмен AJAX приложения с сервером биллинга происходит по протоколу, описанному в Wiki (раздел Протоколы). Данный протокол может быть использован также сторонними клиентами для интеграции систем приёма платежей с провайдером.

10.1. Настройка модуля

Добавьте в конфигурацию модуля карточек следующие параметры:

findmode.x.mode=режим поиска 
findmode.x.mid=id модуля 
findmode.x.pid=id параметра 
findmode.x.title=название поиска

Возможные сочетания.

Поиск по номеру договора:

#(режим поиска - по номеру договора)
findmode.x.mode=contract
findmode.x.title=Номер договора

Поиск по адресу:

#(режим поиска - по адресу)
findmode.x.mode=address  
findmode.x.title=Адрес
#(id параметра, т.к в договоре может быть несколько параметров с типом адрес)
findmode.x.pid=x

Поиск по текстовому параметру

#(режим поиска - по текст. параметру)
findmode.x.mode=parameter
findmode.x.title=Параметр
#(id параметра, т.к в договоре может быть несколько текст. параметров)
findmode.x.pid=x

Поиск по комментарию договора

#(режим поиска - по комментарию договора)
findmode.x.mode=comment
findmode.x.title=Комментарий договора

*id параметра в справочнике можно узнать выбрав нужный элемент и нажав Ctrl+i

Поиск по логину модуля Inet

#(режим поиска - логин)
findmode.x.mode=login_inet
#(id модуля)
findmode.x.mid=x
findmode.x.title=Логин Inet

Поиск по логину модуля DialUp (VPN и т.д.)

#(режим поиска - логин)
findmode.x.mode=login_dialup
#(id модуля)
findmode.x.mid=x
findmode.x.title=Логин Dialup 

Поиск по логину модуля IP телефонии (VoiceIP)

#(режим поиска - логин)
findmode.x.mode=login_voip
#(id модуля)
findmode.x.mid=x 
findmode.x.title=Логин VoIP

Поиск по номеру модуля телефонии (Phone)

#(режим поиска - телефон)
findmode.x.mode=phone
#(id модуля)
findmode.x.mid=x
findmode.x.title=Телефон

Поиск по карточке модуля CerberCrypt

#(режим поиска - cerbercrypt)
findmode.x.mode=cerbercrypt
#(id модуля)
findmode.x.mid=x  
findmode.x.title=Карта цифрового телевидения

Далее можно указать группы договоров или шаблон, названия договора которые разрешено находить (выбрать необходимые нужно будет в настройках параметров дилера):

dealer.allow.contract.x.title=заголовок
dealer.allow.contract.x.group=группы договоров через запятую
dealer.allow.contract.x.regexp=regexp названия договора

При установке regexp-фильтра используется MySQL REGEXP. Например, фильтр по договорам частников (префиксы AA, AD, AL и т.п.) может выглядеть так:

dealer.allow.contract.1.title=Частники
dealer.allow.contract.1.regexp=(AA*)|(AD*)|(AL*)

Еще один параметр указывает разрешать ли выдавать часть результата поиска, если было найдено несколько договоров

dealer.findcontract.fewresults= 1 | 0

В web-интерфейсе дилера существует возможность вывода тарифных планов договора при проведении платежа. Для этого следует добавить в конфигурацию параметр

idealer.tariff.ids=X,Y,...,Z

Здесь X, Y и Z - это коды тарифных планов. Порядок их расположения определяет порядок вывода тарифных планов в интерфейсе дилера. Например, сперва можно указать все тарифные планы телефонии (например, 10,11,12), а далее все тарифные планы абонплат (например, 23, 24, 26). Тогда при различных комбинациях этих тарифов у клиентов в любом случае на первом месте будет стоять один из тарифов телефонии, а затем уже какой-либо тариф абонплат. Не указанные в перечислении тарифные планы не отображаются. Для отображения персональных тарифных планов (всех сразу) следует указать код 0. При этом порядок также имеет значение.

Далее пример конфигурации:

#поиск по договору
findmode.1.mode=contract
findmode.1.title=Номер договора

#поиск по адресу
findmode.2.mode=address
findmode.2.title=Адрес
#id параметра-адреса
findmode.2.pid=19

#поиск по логину(алиасу) dialup
findmode.3.mode=login_dialup
findmode.3.mid=21
findmode.3.title=Логин Dialup

#поиск по логину(алиасу) VPN
findmode.4.mode=login_voip
findmode.4.mid=22
findmode.4.title=Логин VPN

#поиск по логину Voip
findmode.5.mode=login
findmode.5.mid=6
findmode.5.title=Логин VoIP

#поиск по телефону Phone
findmode.6.mode=phone
findmode.6.mid=20
findmode.6.title=Телефон

#поиск по картам Cerbercrypt
findmode.7.mode=cerbercrypt
findmode.7.mid=43
findmode.7.title=Карта цифрового телевидения

#

#будут выводиться только договоры из указанных через запятую групп
#номера групп указаны в справочнике
dealer.allow.contract.1.title=Поиск по VIP договорам
dealer.allow.contract.1.group=1,10,17
#будут выводиться договоры, название которых совпадает с regexp 
#(краткий список: .-любой символ,\d-цифра,\w-буква/цифра; * после одного из них - нет или любое кол-во,
#+ - один и более, ? - нет или один)
dealer.allow.contract.2.title=Поиск по физическим лицам
dealer.allow.contract.2.regexp=K.*
#если указаны и regexp и group то выводятся договоры, совпадающие по обоим параметрам
#
dealer.findcontract.fewresults=1
#
#коды тарифных планов для отображения в интерфейсе idealer'а. Сперва отображаем персональные ТП, 
#а затем ТП с кодами 10, 13, 24 (если они присутствуют у договора)
idealer.tariff.ids=0,10,13,24

10.2. Настройка дилера

В свойствах дилера по приёму платежей должны быть указаны следующие опции:

Логин - логин дилера в системе удалённых платежей;
Пароль - пароль дилера в системе удалённых платежей;
Тип платежа - каким типом могут быть обозначены платежи в приходе договора, варианты типов платежа должны быть помечены как нередактируемые в справочнике типов платежей. При проведении платежа в интерфейсе дилера имеется возможность выбрать один из указанных типов платежей;
Отмена платежа - в течении скольких минут после проведения дилер может отменить платёж;
Поисков/Найдено/Платежей - сколько было попыток поиска/найдено договоров и проведено платежей - для отслеживания попыток дилера просканировать абонентскую базу;
Разблокировать - в случае нескольких неудачных попыток ввода пароля логин дилера блокируется и может быть разблокирован этой кнопкой.
Тестовый режим - платежи дилера не будут реально попадать на баланс договора, необходим для отладки взаимодействия;

На вкладке Режимы поиска указываются признаки, по которым дилер может искать абонента. Сами признаки описываются в конфигурации модуля (см. выше).

Если не указаны Фильтры поиска, дилеру будет позволено находить любые договоры. Фильтры позволяют выделить только те договоры, на которые дилер может принимать платежи.

Начиная с 4.3 версии, каждый дилер может быть привязан к договору, на балансе которого ведётся учёт платежей от дилера с учётом комиссии.

Привязываемый договор должен быть открыт. Система поддерживает два вида комиссии: простую и сложную. Кроме того, возможна работа без комиссии. Размер комиссии указывается в процентах в свойствах дилера.

При простой комиссии на баланс договора будет положена наработка, равная сумме, оплаченной клиентом, минус агентское вознаграждение (размер комиссии).

При сложной комиссии на баланс договора начисляется наработка, равная сумме, внесённой клиентом, и начисляется отрицательная наработка, равная агентскому вознаграждению. В результате на балансе дилера образуется долг, равный сумме проведённых платежей, минус его агентское вознаграждение. Например, баланс дилера может выглядеть так:

Коды услуг наработки агента и агентского вознаграждения задаются в конфигурации модуля.

# код услуги "Платежи"
dealer.pay.sid=105
# код услуги "Агентское вознаграждение"
dealer.bonus.sid=106

При привязке дилера к договору дилер сможет проводить платежи только, если у него в договоре сумма остатка больше лимита, либо если в договоре стоит режим КРЕДИТ.

10.3. Web-клиент

Web-клиент по умолчанию находится по адресу http(s)://server:port/bgbilling/id/

web-клиент является AJAX (active javascript and xml) приложением, работающим под IE, Firefox, Opera, реализующим интерфейс удалённых платежей модуля.

Дополнительно необходимо произвести настройку файла BGBillingServer/webroot/id/conf.txt, указав код модуля карт.

//код модуля
mid = <код модуля карточек>
//записей на странице
page_size = 15

//префикс номера транзакции,
//если не определён, то берётся
//значение из cookies
//prefix = ""

//дополнение к комментарию платежа,
//(если разрешено администратором)
//если не определён, то берётся
//значение из cookies
//postfix = ""

При открытии страницы запрашивается логин и пароль дилера. Далее дилер может осуществлять поиск договора, пополнение счета, отмену платежа (при ошибочном платеже, см. Отмена платежа выше), просмотр выполненных/отмененных платежей.

10.4. Сверка платежей

Формат реестра платежей:

<номер платежа>\t<время проведения>\t<договор>\t<сумма>

\t - знак табуляции;

время проведения в формате dd.MM.yyyy HH:mm:ss или yyyy-MM-dd HH:mm:ss

Например: 2147483647 2006-03-03 13:56:39 x0000 10

Глава 4. Модуль Enaza

1. Назначение модуля

Данный модуль позволяет оплачивать покупки контента, предоставляемого платформой Enaza (http://www.enaza.ru) путём списания средств с лицевого счета абонента.

2. Базовые понятия и алгоритм работы модуля

Модуль может работать в нескольких режимах:

  • в режиме "только оплата", при котором покупки оплачиваются путём перенаправления из магазина Enaza на страничку в личном кабинете с подтверждением оплаты;

  • в режиме встраивания IFRAME на страницу в веб-кабинете.

  • в режиме встраивания Widget на страницу в веб-кабинете.

Алгоритм работы модуля следующий:

  • либо через IFRAME/WIDGET на странице статистики, либо непосредственно на сайте магазина Enaza пользователь выбирает интересующий товар и начинает оформление заказа;

  • биллинг Enaza перенаправляет пользователя на сервлет на сервере BGBilling, посредством которого происходит проверка корректности данных и перенаправление пользователя на страничку с подтверждением оплаты в личном кабинете;

  • при согласии пользователя оплатить товар и при необходимом количестве средств на счету происходит списание расхода, и пользователь перенаправляется обратно на страницу магазина.

3. Установка и настройка модуля

Модуль устанавливается с помощью утилиты bg_installer, после чего необходимо создать его экземпляр.

На вкладке Конфигурация создайте и установите конфигурацию модуля. Список опций доступен в редакторе конфигурации при выборе режима ШАБЛОН. Опции можно разделить на три группы. Первая группа общие опции для 2 и 3 версии протокола. Вторая группа - опции для 2 версии протокола. Третья группа - опции для 3 версии протокола (начинаются с префикса enaza3).

4. Инструкции по активации услуг компании Enaza

После установки и настройки модуля необходимо заключить сублицензионный договор с компанией Enaza, передающий интернет-провайдеру права на предоставление услуги подписки конечным пользователям. Далее в личном кабинете Enaza в качестве URL к серверу биллинга необходимо указать URL следующего вида:

Для 2 версии:

http[s]://<YOUR.BILLING.URL>/enaza_api/<MID>, где <YOUR.BILLING.URL> - это URL к серверу биллинга, например, provider.example.com:8080/bgbilling, а <MID> - код экземпляра модуля Enaza.

Для 3 версии:

  • http://provider.example.com[:PORT]/bgbilling/enaza_api/<MID>/access - получение access_token;

  • http://provider.example.com[:PORT]/bgbilling/enaza_api/<MID>/client - получение user_data;

  • http://provider.example.com[:PORT]/bgbilling/enaza_api/<MID>/login - авторизация по IP (в данной момент не реализована);

  • http://provider.example.com[:PORT]/bgbilling/pubexecuter?action=Enaza&module=enaza&mid=<MID> - авторизация по логину и паролю от ЛК.

Подать заявку можно по ссылке http://team.enaza.ru/ru/callback/

5. Клиентская часть

Для возможности пользоваться услугами данного модуля на договор клиента должен быть добавлен модуль Enaza. После добавления модуля к договору можно просматривать его подписки, их статусы, а также все транзакции, производимые по конкретным подпискам. Также в договоре возможно вызвать переобсчет начислений для нужного месяца.

Глава 5. Модуль Gorod

1. Назначение модуля

Модуль предназначен для интеграции системы с платёжной системой ГОРОД. Модуль поддерживает выгрузку реестров 3, 7 и 9.

2. Настройка модуля

Установите модуль на сервер, обновите клиент биллинга. Затем создайте экземпляр модуля.

Создайте в редакторе конфигурации модуля новую конфигурацию, скопируйте туда приведённый ниже текст, подправьте под ваши нужды параметры и сделайте данную конфигурацию активной.

#шаблон реестра по умолчанию
register.pattern=[${fio}][;${city}][,${street}][,${house}][${frac}][,${flat}][;${contractTitle}][;${summ}][;;;;${account}][:${contractId}]

#шаблоны, привязанные к тегам, в формате register.pattern.<tag_id>. Если для тега не будет указан шаблон, то будет использоваться шаблон по умолчанию!
register.pattern.1=[${fio}][;${city}][,${street}][,${house}][,${flat}][; ${dateTo}][;${contractTitle}][;${summ}][;;;;${account}][:${contractId}][;${dateFrom}]
register.pattern.2=[;${dateFrom}][;${city}][,${street}][; ${dateTo}][;${contractTitle}][;;;;${account}][:${contractId}][${fio}][;${summ}]
register.pattern.3=[;${city}][${fio}][dateTo: ${dateTo}][;${contractTitle}][;${summ}][;dateFrom:${dateFrom}][;${account}][:${contractId}]

#Кодировка реестра (по умолчанию, если параметр не задан, кодировка ставится как cp866)
register.encoding=Cp1251

#Кодировка реестра с привязкой к тегу. Если для тега не указана кодировка, то используется кодировка по умолчанию.
register.encoding.1=Cp1251
register.encoding.2=cp866

#формат даты для параметров шаблона dateFrom и dateTo
register.date.format=dd/MM/yyyy

#флаг, устанавливающий в заголовок реестра поле NOTE
param.note=1

#В поле NOTE ставится <дата_составления_реестра> (0 - поле пустое)
param.note.content.date=1

#в параметре summ прописывается название макроса, по которому вычисляется сумма для каждой строки реестра
#В данный момент доступны 2 варианта: 
#SALDO( стандартный режим - остаток по балансу - используется по умолчанию )
#IS_GREATER_ZERO - в строках реестра будет стоять либо 0.0 в случае положительного остатка, либо отрицательное значение остатка
register.summ.macros=SALDO

#Чтобы узнать коды параметров "Адрес" и "Полное имя" откройте справочник "Параметры договоров"
#и выберите коды из левого столбца. Параметр "Полное имя" должен быть в договоре обязательно, 
#а адреса может не быть - в этом случае подставится значение по умолчанию.
param.address=<код параметра адрес> 
param.fullname=<код параметра "Полное имя"> 

#это будет подставлено в адрес по умолчанию. Можно использовать подстановку ${cid} - код договора
default.address=Уфа,ДС,0,${cid}

#битовая маска групп, для которых выгружаются реестры. Определяется следующим образом: откройте справочник групп, 
#выделите позиции групп, начинающиеся с 0. Затем посчитайте выражение mask = 1<<gr1 | 1<<gr2...| 1<<grN
group.mask=262144

#счёт, подставляемый в файл реестра для тега с кодом 1 (Код тега можно узнать на вкладке Теги в модуле Город)
account.1=175

#счёт, подставляемый для договора с группой по маске 3 (т.е для договоров где (gr&3)>0)
#если счёт по группе договора не найден, используется счёт по фирме
account.gr.3=176

Для настройки шаблона реестра можно использовать следующие макроподстановки:

  • [${fio}] - ФИО клиента;

  • [${city}] - город;

  • [${street}] - улица;

  • [${house}] - дом;

  • [${frac}] - дробь дома;

  • [${flat}] - квартира;

  • [${contractTitle}] - название договора;

  • [${summ}] - сумма;

  • [${account}] - счет;

  • [${contractId}] - id контракта;

  • [${dateFrom}] - дата начала периода оплаты (ставится начало месяца );

  • [${dateTo}] - дата окончания периода оплаты (ставится дата формирования реестра ).

Каждая макроподстановка может встречаться в реестре только 1 раз. В шаблон не обязательно включать все поля - только те, что реально нужны. Между полями возможно вставить любой текст - он попадет в реестр в каждую строку. Важно! Квадратные скобки у полей обязательны!

Для того, чтобы настроить выгрузку реестров для договоров у них должен быть проставлен параметр Тег. Редактор тегов открывается с помощью меню Модули=>Город=>Вкладка Теги. Добавление, удаление и изменение тегов доступно через основную панель инструментов клиента биллинга c помощью кнопок Добавить, Удалить, Изменить.

3. Работа с реестрами

Для каждого дня должен быть зафиксирован реестр-сальдо 7, на основании 2х сальдовых реестров может быть созданы реестры 3 (изменений) и 9 (удаление).

Как видно из скриншота, интерфейс очевиден и сложности не представляет: в левом верхнем углу расположен фильтр, позволяющий выбрать реестры лишь за определённый период. Выбранный реестр можно сохранить в указанный в правом верхнем углу файл.

При создании реестра 7 достаточно указать дату и тег, для создания реестров 3 и 9 - период и тег, для дат из периода должны существовать 7-ые реестры.

4. Использование модуля

Подключите экземпляр модуля к договору. Слева в дереве договора в разделе Модули появится экземпляр модуляГород. Выберите его. Справа появится возможность привязки тегов к договору.

Привязка не должна вызывать трудностей. Необходимо из списка Доступные теги выбрать те теги, которые нужно привязать к договору, затем нажать кнопку с изображением знака меньше "<". Выбранные теги появятся в списке Выбранные теги.

Удаление происходит аналогично добавлению тегов: из левого списка Выбранные теги необходимо отметить те теги, которые нужно удалить, а затем нажать кнопку с изображением знака больше ">". Удаленные теги появятся в правом списке Доступные теги.

При создании договора возможна установка первоначального набора тегов и автоматическое подключение модуля Город. Это осуществляется путем добавления модуля Город в шаблон создания договора. Там же устанавливаются теги, автоматически прикрепляемые к создаваемому договору.

Глава 6. Модуль RentSoft

1. Назначение модуля

Данный модуль позволяет абонентам работать с улугами платформы Rentsoft от компании ООО "Рентсофт". Компания Рентсофт является дистрибутором программных продуктов и цифрового контента с ежемесячной оплатой по подписке. Рентсофт заключила лицензионные соглашения и осуществила интеграции с большинством производителей антивирусного программного обеспечения. Перечень программного обеспечения и цифрового контента, распространяемых по подписке, постоянно расширяется, делая предложение все более и более востребованным партнерами и конечными пользователями. Интеграция BGBilling с данной платформой производится посредством вставки IFRAME на страницу пользователя в личном кабинете.

2. Базовые понятия и алгоритм работы модуля

Модуль состоит из трех базовых частей:

  • страничка в личном кабинете, в которую посредством вставки IFRAME интегрируется площадка по продаже ПО по подписке;

  • сервлет на сервере BGBilling, посредством которого удаленные сервера Rentsoft "уведомляют" биллинговую систему о покупке, изменении статуса подписок и т.п. (должен быть доступен "извне");

  • клиентская часть (для операторов и администраторов биллинга), через которую возможен просмотр наличия и статуса подписок и платежей конкретного клиента, а также список продуктов (поплняется в реальном времени в процессе обращения пользователей к тем или иным продуктам).

Таким образом все операции по покупке, продлению подписок, отказа от них и т.п. осуществляются на серверах Rentsoft посредством встроенного в личный кабинет IFRAME. На сервер биллинг через открытое API (сервлет) отправляются уведомления об этих операциях, в соответствие с чем договорам устанавливается определенная наработка и списание средств.

3. Установка и настройка модуля

Модуль устанавливается с помощью утилиты bg_installer, после чего необходимо создать его экземпляр. После создания экземпляра модуля необходимо создать услугу (одну) для данного модуля.

На вкладке Конфигурация создайте и установите конфигурацию модуля.

#активные статусы договора, при которых возможно приобретение ПО
contract.status.active.codes=0

# cекретная строка (поля "Ключ цифровой подписи IFRAME" и то же значение
# в поле "Пароль доступа к API списания средств" на rentsoft.ru)
rentsoft.secret=some-secret-string
# Уникальное имя оператора связи (поле "Системное имя личного кабинета AG_NAME"  на rentsoft.ru)
rentsoft.ag_name=your-operator-name
# Ширина IFRAME в кабинете статистики.
rentsoft.iframe_width=880px

4. Инструкции по активации услуг компании Рентсофт

После установки и настройки модуля необходимо заключить сублицензионный договор с компанией Рентсофт, передающий интернет-провайдеру права на предоставление услуги подписки конечным пользователям.

Контакты Рентсофт:

  • e-mail: partner@rentsoft.ru

  • тел. +7 (499) 504-98-75

5. Клиентская часть

В меню модуля Rentsoft на вкладке Используемые продукты отображаются продукты, подписки на которые уже были куплены клиентами биллинга. В общем случае здесь не хранятся все возможные для покупки продукты, эта таблица носит информационный характер и заполняется по мере поступления запросов на покупку подписок от клиентов.

После добавления модуля к договору можно просматривать его подписки, их статусы, а также все транзакции, производимые по конкретным подпискам. Также в договоре возможно вызвать переобсчет начислений для нужного месяца.

6. Работа с юридическими лицами

Предоставление услуги "Подписка на ПО" для юридических лиц несколько сложнее, чем для физических лиц. Главное отличие заключается в том, что согласно правилам ведения бухгалтерии в РФ списания за услугу необходимо привязывать к отдельному договору (или субдоговору) данного юридического лица с отдельным балансом, созданному специально для услуги "Подписка". В момент заказа юрлицом услуги (набора юрлицом корзины в кабинете статистики) субдоговор для Рентсофт может еще у него не существовать. Поэтому в качестве базового идентификатора, к которому осуществляется привязка услуг системой Рентсофт, выступает идентификатор основного договора (того, под которым юрлицо заходит в личный кабинет). Это позволяет юрлицу начать пользоваться услугами с триальным периодом (которых абсолютное большинство) сразу же, не ожидая заключения нового договора, а просто приняв оферту.

6.1. Схема, когда провайдер самостоятельно подключает продукты юрлицу

Если продажа продукта осуществляется самим провайдером при посещении им клиента, реализуется следующий сценарий.

  1. Провайдер создает юрлицу договор (или субдоговор), предназначенный для работы с услугами Рентсофт, и выдает клиенту логин и пароль от этого договора (или субдоговора). Внимание: в названии или комментарии договора обязательно должна присутствовать подстрока "rentsoft". Это разрешает модулю Рентсофт осуществлять списания по данному договору, а заодно и служит целям наглядности при будущих поисках договоров по реквизитам юрлиц. Для удобства можно добавить строку "rentsoft" в шаблон названия договора – например, "rentsoft-${N6}".

  2. Клиент заходит в кабинет статистики, выбирает необходимые услуги.

  3. В некоторый момент юрлицо попадает на страницу "Пополнить счет" в IFRAME (это происходит, например, когда подключается платная услуга):

  4. Юрлицо нажимает кнопку "Выставить счет", и в бухгалтерию интернет-провайдера высылается письмо-уведомление следующего содержание: "Юрлицо с реквизитами XXX просит заключить договор (если он еще не заключен ранее) и выставить ему счет на сумму YYY руб за услуги подписки".

  5. Бухгалтерия получает письмо, находит в административном интерфейсе биллинга договор юрлица. Провайдер выставляет юрлицу счет на указанную сумму. Как только деньги поступают, провайдер зачисляет их на счет договора.

  6. Юрлицу автоматически приходит уведомление о том, что деньги поступили, и он может зайти в свой личный кабинет и включить/разблокировать услуги.

  7. В дальнейшем всякий раз, когда юрлицу будет требоваться пополнение счета, ответственному лицу в провайдере будет отправляться уведомление об этом, и работа будет продолжаться с п. 6. Для новых пополнений создавать субдоговор, конечно, уже не потребуется – можно будет использовать уже существующий.

6.2. Схема, когда юрлицо самостоятельно выбирает и подключает услуги

Отличается от случая выше тем, что в момент, когда юрлицо принимает решение воспользоваться услугами Рентсофт на витрине с продуктами, у него еще не существует отдельного договора/субдоговора для подписок. Поэтому в качестве идентификатора договора, по которому Рентсофт идентифицирует абонента, всегда выступает идентификатор основного договора. Сценарий следующий:

  1. Юридическое лицо заходит в свой кабинет статистики и в IFRAME Рентсофт выбирает продукты, которыми хочет пользоваться.

  2. Для большинства продуктов имеется триальный период, так что клиент может подключить их и начать работать немедленно: подписки активизируются и сразу же становятся доступными в личном кабинете.

  3. 3. В процессе подключения запрашиваются реквизиты юрлица.

  4. В некоторый момент юрлицо попадает на страницу "Пополнить счет" в IFRAME (это происходит, например, когда подключается платная услуга):

  5. Юрлицо нажимает кнопку "Выставить счет", и в бухгалтерию интернет-провайдера высылается письмо-уведомление следующего содержание: "Юрлицо с реквизитами XXX просит заключить договор (если он еще не заключен ранее) и выставить ему счет на сумму YYY руб за услуги подписки".

  6. Бухгалтерия получает письмо, находит в административном интерфейсе биллинга основной договор юрлица и создает к нему субдовор для услуг Рентсофт (если он еще не был ранее создан). Внимание: в имени субдоговора или в комментарии к нему обязательно должна присутствовать подстрока "rentsoft". Именно по наличию данной подстроки модуль определяет, что списания за подписки (которые, напомним, уже могут быть созданы на шаге 2) надо привязывать к данному субдоговору.

  7. Провайдер выставляет юрлицу счет на указанную сумму. Как только деньги поступают, провайдер зачисляет их на счет субдоговора.

  8. Юрлицу автоматически приходит уведомление о том, что деньги поступили, и он может зайти в свой личный кабинет и включить/разблокировать услуги:

  9. В дальнейшем всякий раз, когда юрлицу будет требоваться пополнение счета, бухгалтерии провайдера будет отправляться уведомление об этом, и работа будет продолжаться с п. 6. Для новых пополнений создавать субдоговор, конечно, уже не потребуется – можно будет использовать уже существующий.

6.3. Автоматизация: создание шаблона для договора по услугам Рентсофт

Т.к. создание договора для Рентсофт – частая операция, можно создать специальный шаблон договора со следующими параметрами:

  • Название шаблона: "Договор Рентсофт".

  • Шаблон имени договора: "rentsoft-${N6}" (к примеру). Если вы не хотите указывать строку "rentsoft" в имени договоря, можно добавить ее в комментарий, воспользовавшись функцией "Шаблоны комментариев".

  • Список модулей: добавлен модуль "Рентсофт".

  • Лицо: "Ю" (юридическое).

  • Режим: "К" (для предоплатной системы предоставления услуги) или "Д" (для предоставления в постоплатном режиме; в этом случае нужно также задать лимит).

В дальнейшем при поступлении от юрлица заявки на пополнение счета, если субдоговор еще не существует, его нужно создать с параметрами:

  • Шаблон – "Договор Рентсофт".

  • Создать субдоговор как договор для … - выбрать основной договор юрлица.

7. Web интерфейс

При добавлении модуля в договор, в web интерфейсе пользователя появляется пункт меню Ваши подписки. Здесь располагается iframe с онлайн витриной подписок от компании RentSoft.

После выбора необходимого продукта появится окно c информацией о покупке, полем для ввода E-mail, на который придет информация о ней, а также лицензионное соглашение. При согласии с условиями необходимо нажать кнопку Оплатить и подключить, после чего на указанный E-mail придет письмо с дальнейшими инструкциями.

Глава 7. Модуль TrayInfo

1. Назначение модуля

Модуль предназначен для предоставления пользователям использования утилиты TrayInfo — это маленькая программа, висящая в System Tray Windows и отображающая баланс пользователя. Кроме того она позволяет осуществлять мгновенный доступ к странице статистики, скрывая от пользователя процесс авторизации. Имеется версия TrayInfo3 под linux.

2. Конфигурация модуля

В конфигурации модуля можно указать название пункта меню Web-статистик пользователя.

В Редакторе модулей и услуг создайте экземпляр модуля TrayInfo. Зайдите в Модули=><Название созданного экземпляра>, откройте вкладку Конфигурацию модуля, создайте конфигурацию и укажите в ней.

web.menuItem1=Активация логина TrayInfo 

Подключите модуль всем клиентам, которым нужно предоставить возможность использования TrayInfo.

3. Создание типов логинов

После открытия созданного модуля TrayInfo на вкладке Логины TrayInfo — перечень видов логинов. Для каждого вида указывается его цена, тип расхода который будет добавлен в договор, период действия вида логина и срок действия логина. Для установки бесконечного срока действия, выберите соотвествующий пункт из выпадающего списка или укажите срок ноль дней. Тип расхода должен быть помечен как нередактируемый в справочнике расходов.

4. Активация TrayInfo клиентом

Для того чтобы клиент смог использовать утилиту TrayInfo необходимо подключить к договору модуль TrayInfo. После этого клиент должен зайти на страницу статистики выбрать меню Активация логина TrayInfo и выбрать PIN2. После этого клиент получит PIN1 + PIN2 и с его счета будет взыскана сумма соответствующая выбранному типу логина. Чтобы посмотреть PIN2 в таблице его нужно выделить мышью.

5. Настройка утилиты TrayInfo

Необходимо изменить ресурсы exe-файла приложения, чтобы указать URL баланса и Web-статистики.

Для этого можно воспользоваться утилитой Resource Hacker™ или любым аналогичным редактором ресурсов: http://www.google.com/search?q=exe+resource+editor

Измените строковые ресурсы 1, 2, 3 (для старой версии утилиты 65257, 65258, 25259), соответственно http://provider/bgbilling/balance_sender, http://provider/bgbilling/webexecuter, mid на адреса вашего сервера биллинга и код модуля TrayInfo (вы можете его посмотреть в редакторе модулей и услуг ).

Запускаем утилиту, жмём правой кнопкой мыши и выбираем Параметры:

Далее в PIN1 и PIN2 клиент вводит свой PIN1 и PIN2 TrayInfo, нажимает Ок и может смотреть баланс в висящем окошке.

Для того, чтобы клиент смог переходить на свою страницу статистики необходимо в настройках сервера (Сервис=>Настройка=>Конфигурация) добавить в конце значения переменной web.auth.modes точку с запятой и разрешение авторизоваться через модуль TrayInfo:

;<код вашего модуля TrayInfo>:1

Строка примет, например, такой вид (код экземпляра модуля TrayInfo равен 10, помимо этого разрешена авторизация по договору):

web.auth.modes=0:1;10:1

Затем перезагрузите BGBillingServer. Теперь клик правой мышкой по окошку TrayInfo, затем выбор в меню Статистика и вы переходите на страницу статистики клиента.

6. Настройка утилиты TrayInfo3

Утилита написана с использованием Qt, никаких ресурсов не содержит. Патчер для настройки утилиты находится внутри модуля в виде GUI-фрейма. Для его запуска необходимо запустить класс, например, в папке с корнем в клиенте или сервере:

java -cp ./*:./lib/* ru.bitel.bgbilling.modules.trayinfo.common.BinaryPatch

Далее вводятся все нужные параметры. Дефолтные PIN1 и PIN2 можно не вводить (сделано на будущее для автоматической генерации настроек пользователя на лету).

7. Настройка утилиты TrayInfo для Mac Os

Для Mac Os можно запустить виджет для Notification Center, минимальная версия Mac Os 10.10(Yosemite)

Перед распространением программы необходимо обратиться к нам, чтобы мы скомпилировали виджет с вашими данными( URL баланса, код модуля).

По желанию можно заменить изображение иконки, для этого надо пройти в Contents->Resources и заменить файл AppIcon.icns нужным, для конвертированная изображения можете воспользоваться утилитой Img2icns(MacOs)

8. Отображение в утилите произвольной информации вместо баланса

Имеется возможность генерировать любую информацию для отображения её в утилите. Возможность запроса баланса действует по умолчанию и оставлена для обратной совместимости. Для использования нового функционала необходимо генерировать нужную строку с помощью динамического кода.

# использовать следующий динамический класс для формирования ответа
# имплементировать: ru.bitel.bgbilling.modules.trayinfo.server.bean.TrayInfoReplyBuilder
replybuilder=ru.bitel.bgbilling.trayinfo.SimpleReply

Пример класса идёт в комплекте.

Для отправки суммы:

# формировать ответ с параметром summa (баланс). старый вариант. может
# использоваться как вместе, так и отдельно с кастомным ответом.
# по дефолту включено (1), для обратной совместимости.
use.summa.reply=0

Итак, если не настроить дополнительно, то будет генерироваться баланс без участия скрипта и отображаться в утилите. Можно использовать и скрипт и баланс, тогда старые утилиты будут отображать только баланс, а новые - сгенерированную строку.

Глава 8. Модуль Assist

1. Назначение модуля

Модуль Assist предназначен для проведения платежей через систему электронных платежей Assist.Ru. В данный момент система позволяет принимать следующие типы платежей:

  • оплата по кредитной карте;

  • оплата через платёжную систему WebMoney Transfer;

  • оплата через платёжную систему Яндекс.Деньги;

  • оплата через QIWI;

  • оплата кредитной картой с использованием Assist®ID.

Следует учесть, что модуль изначально создавался для оплаты только по кредитным картам. Для оплаты через систему WebMoney Transfer следует использовать предназначенный для этого модуль, остальные системы оплаты не тестировались.

Для работы в нетестовом режиме у вас должен быть заключён договор с системой и создан готовый интернет-магазин в системе Assist.

Замечание

В данный момент модуль работает только через новый протокол (конца 2011 года), работа через старый протокол больше не поддерживается.

2. Настройка модуля

Установите модуль на сервер, обновите клиент. Затем создайте экземпляр модуля. Создайте новую конфигурацию модуля в редакторе конфигурации и сделайте её активной. Шаблон конфигурации приведен ниже:

# Заголовок пункта меню веб-статистики.
web.menuItem1=Оплата через Assist.Ru 

# Тип платежа (ID), куда должны приписываться все проводимые платежи.
assist.paymenttype=1

# Код магазина в системе ASSIST.
assist.Merchant_ID=******
# Полный адрес голого webexecuter. Используется для построения обратного пути, куда будет переводиться редиректом клиент после завершения транзакции.
assist.path=http://provaider.ru/bgbilling/webexecuter
# Комментарий. Данный параметр передаётся в ASSIST и отображается в выписках по операциям (доступны только эти два макроса).
assist.OrderComment=Оплата по договору ${contract} (${contract_comment})
# Комментарий добавляемого платежа (доступны указанные макросы).
assist.payment_comment=Оплата по дог. ${contract} (${contract_comment}) через Assist (Платёж #${billnumber})(Плательщик: ${name})(Карта ${cardnumber} ${cardtype}/${cardsubtype}, держатель: ${cardholder}) от ${date}, сумма ${total}
# Признак авторизации кредитной карты при двустадийном механизме работы (0 – нормальный режим, 1 – режим авторизации кредитной карты). По умолчанию - нормальный режим.
#assist.Delay=0

# Логин sale в магазине
assist.login=******
# Пароль sale в магазине
assist.password=******

# Производить оплату по кредитной карте. (1 – использовать, 0 – не использовать). Если данный параметр не передаётся, то по умолчанию его значение установлено в 0.
assist.CardPayment=1
# Использовать платёжную систему WebMoney Transfer. (1 - использовать, 0 - не использовать).
assist.WMPayment=0
# Использовать платёжную систему Яндекс.Деньги. (1 - использовать, 0 - не использовать).
assist.YMPayment=0
# оплата кредитной картой с использованием Assist®ID (1 - использовать, 0 - не использовать)
assist.AssistIDPayment=0
# QIWI
assist.QIWIPayment=0
assist.QIWIMtsPayment=0
assist.QIWIMegafonPayment=0
assist.QIWIBeelinePayment=0

# Режим работы:
# test — магазин подключен в тестовом режиме;
# battle — магазин подключен в рабочем режиме;
# battletest — магазин подключен в рабочем режиме, но требуется совершать тестовые запросы (установка TestMode=1).
assist.ShopMode=test

# можно перегрузить (безусловно от режима работы магазина) адрес отправки параметров (если дали персональный).
assist.actionUrl=https://test.paysecure.ru/pay/order.cfm

После регистрации на сервисе Assist.Ru вам дадут параметры "код магазина", а также возможность настроить "логин" и "пароль" типа sale, которые нужно прописать в конфигурации. Чтобы узнать ID нужного платежа, выберите его в справочнике и нажмите Ctrl+i.

Необходимо получить у службы поддержки ООО «АССИСТ» (support@assist.ru) идентификатор предприятия merchant_id, логин и пароль администратора юридического лица для работы с Личным кабинетом (он находится по адресу https://account.paysecure.ru/), а также логин и пароль пользователя типа sale для работы с веб-сервисами.

Основное, на что необходимо обратить внимание при настройке магазина в личном кабинете:

  • Режим. Тестовый или Рабочий. Таким образом, режим определятся двумя настройками — в самом магазине Assist и в конфигурации модуля.

  • Для ручного запроса результатов платежей необходимы логин и пароль типа sale (см. личный кабинет).

  • Можно также настроить автоматическое перенаправление покупателя на сайт предприятия после завершения платежа в АПК ПР. Для этого необходимо выбрать действие после авторизации «Перейти на страницу магазина» в Личном кабинете по адресу https://account.paysecure.ru/ в разделе «Настройки мерчантов», вкладка «Настройки платежей». В этом случае после авторизации сразу загружается страница веб-статистики, на которой показывается предварительный результат этого платежа.

  • Настройка получения результатов операций: в личном кабинете assist поставить галку "отправлять результаты платежей", ввести URL, примерно такой: http://billing/bgbilling/assistexecuter?mid=<mid ассиста> , указать тип: SOAP. URL зависит от ваших настроек, проверьте доступность извне сервлета assistexecuter.

  • Не ставить (снять) галочку "отправлять только успешные", иначе неудачные платежи будут вечно висеть в статусе "в обработке".

Внимание

Если у вас работала до этого старая версия протокола, то нужно ОБЯЗАТЕЛЬНО ОТКЛЮЧИТЬ задачу планировщика "Получение результатов операций".

Внимание

Перед сменой состояния модуля с "рабочего" на "тестовый" необходимо убедиться, что в данный момент нет транзакций. Также необходимо решить вопрос с транзакциями со статусом "В обработке". После смены режима все ранее необработанные транзакции при обработке получат статус текущего режима! То есть, если транзакция начата как "тестовая", а запрос о подтверждении пришёл после смены режима на "рабочий", то она будет считаться проведённой в рабочем режиме, и наоборот. Платежи в договор в любом режиме добавляются одинаково.

3. Оплата через систему Assist

Если в договоре клиента подключён экземпляр модуля Assist, то у него появляется возможность произвести оплату услуг через web-интерфейс (подпункт меню Оплата через Assist.Ru). Здесь же клиент может просмотреть все проведённые им платежи через Assist и их статусы:

При нажатии кнопки Пополнить счёт клиент попадает на новую страницу с формой для ввода суммы. Там же отображается текущий баланс.

При нажатии кнопки Далее клиент переходит к системе авторизации Assist.Ru, где может выбрать удобный для себя способ оплаты из разрешённых настройками модуля. После проведения оплаты (или отказа от неё) клиент возвращается обратно к списку платежей Assist, где устанавливается предварительный статус платежа. Если статус "в обработке", то результат ещё не дошёл до биллинга.

4. Мониторинг и администрирование платежей

В параметрах договора можно посмотреть все платежи: проведённые, не проведённые и находящиеся в обработке.

В параметрах модуля есть глобальный монитор. Можно сделать выборку по многим параметрам, а также принудительно запросить статусы платежей с сервера авторизации Assist. Это можно сделать либо для конкретного платежа ( нажать правой кнопкой мыши на строке таблицы и выбрать пункт "Запросить"), либо для всех платежей за период. Период не должен превышать некоторое ограничение Assist. Ручные запросы могут пригодится при тестировании, каких-то сбоях в автоматической отправке платежей и т.д и т.п.

Имеется возможность отредактировать некоторые параметры платежа: сумму, статус, комментарий.

5. Настройка автоматической установки статусов платежей

В новом протоколе не используется.

6. Настройка сети, фаервола и т.д.

Между сервером Assist и модулем биллинга, как и во многих подобных системах, происходит некоторый обмен. С сервера Assist производится обращение к сервлету assistexecuter. Снаружи нужно открыть доступ. Изнутри надо лишь убедиться, что имеется выход на 443 и/или 80 порт для запроса ручного статусов платежей.

Внимание

Обратите внимание на ограничение Assist. В соотвествии с стандартом PCI DSS сервера Assist из продакшн среды не могут устанавливать соедения во внешую среду по нестандартным портам. Допустимо использование 80 и 443 (как с SSL, так и без) портов. Это означает, что ваш assistexecuter должен быть доступен извне по одному из этих портов. В противном случае оповещения об операциях не будут доходить.

7. Важные замечания

Обратите внимание на особенности функционирования модуля и особенности редактирования Assist-платежей.

1) Данные Assist-платежей представляют собой некий протокол проведения или не-проведения транзакции на удалённом сервере Assist. И к "платежам в биллинге" отношение имеют только в одном: в момент выставления статуса "проведён" создаётся платёж с суммой по данным транзакции с сервера авторизации Assist. Из этого следуют пункты 2 и 3:

2) Вы не можете изменить параметры Assist-платежа в протоколе, уже установленного в статусы "проведён" и "не проведён". Но в реальности возможна ситуация, когда с сервера Assist изначально приходит ненастоящий статус, а в дальнейшем выдаётся другой и, в итоге, получается ошибка (происходит крайне редко, причины не были выяснены). Или статус может по какой-либо причине зависнуть в "в обработке". Для этого существует возможность менять статус и/или сумму у платежей в реестре Assist-платежей в биллинге. Но в целом у таких платежей рекомендуется изменять комментарий. Предполагается, что этот протокол отражает реальное положение дел с транзакциями. Возможность сменить статус оставлена как запасной ход для менеджера подправить "подвисший платёж" и должна использоваться только в крайних случаях! При этом необходимо проверить выставляемую сумму.

3) Как уже сказано в пункте 1, при переводе Assist-платежа в статус "проведён" создаётся новый платёж в договоре. Это взаимодействие однонаправленное. То есть при удалении, редактировании платежа в договоре сумма и статус Assist-платежа в этом протоколе не изменится. Модуль Assist после создания платежа не отслеживает его дальнейшую судьбу. А как сказано в пункте 2, редактировать протокол вы тоже не можете, так что вопрос об обратном взаимодействии протокол->платежи договора тоже не рассматривается. Также при изменении статуса с "проведён" на "в обработке" или "не проведён" с уже добавленным платежом ничего не происходит. Нужно вручную удалить лишний платёж или выставить расход. При обратной смене статуса с любого на "проведён" платёж снова создастся с указанной суммой. Как видно, действия неоднозначные. Возможно, следует закрыть действие ActionUpdatePay (Редактирование параметров платежа) в правах, чтобы было невозможно изменять значения статуса и суммы.

4) При отмене платежа нужно также вручную разрешать несоответствия. Возможности получить автоматически информацию об этих действиях в протоколе в данный момент нет.

Глава 9. Модуль Bill

1. Назначение модуля

Модуль предназначен для автоматизации выставления/обработки счетов и счетов-фактур, совмещённых с актами выполненных работ в среде биллинга, включает в себя Web-интерфейс пользователя для создания и просмотра счетов и просмотра счетов-фактур с актами.

2. Краткий алгоритм работы модуля

Модуль поддерживает два вида документов: Счета и Счета-фактуры. Счёт - уведомление клиенту о сумме, необходимой к оплате. Счёт-фактура - документ, определяющий размер оказанных услуг абоненту. Реально он представляет из себя одновременно счет-фактуру и акт выполненных работ. В стандартном шаблоне они разделены на разных листах: на первом листе отображается счет-фактура, а на втором - акт.

Оба вида документов выставляются для конкретного договора и делятся на Типы. Пример типов: Счёт телефония физ. лица, Счёт интернет юр. лица. Тип определяет набор Позиций для документа. Позиция - строка документа, состоящая из:

названия, например "Абонплата за февраль";
суммы, например 10.40;
количества, например 10;
число знаков после запятой для количества, например 2;
единицы измерения, например Мб.

Каждый документ состоит из набора позиций и некоторых параметров для всего документа. Общие для обоих типов документов параметры:

Дата создания;
Номер;
Тип;
Номерной пул;
Сумма;
Месяц, за который выставлен документ.

Позиции могут быть гибко настроены, что позволяет выводить в счетах и фактурах различную информацию. Сформированный документ представляет из себя XML документ, который отображается в печатную форму посредством XSLT-шаблона. Данная прослойка позволяет, в общем случае, делать произвольное оформление счета. В виде квитанции физ. лицу, простого счета юр. лицу и т.п.

3. Настройка модуля

Установите модуль на сервер с помощью утилиты bg_installer, обновите клиент. Добавление модуля в договор будет означать подключение функционала модуля к договору (возможность выставления счетов и счетов-фактур договору в АРМ администратора и пользователю самостоятельно через сайт).

Перезапустите клиент, откройте в меню Модули созданный вами экземпляр модуля. Создайте в редакторе конфигурации новую конфигурацию и произведите настройку модуля. Значения параметров указаны после символа комментария (#).

Далее будет приведена конфигурация модуля, включающая в себя все имеющиеся параметры.

#-----------------------
# Web-кабинет статистики
#-----------------------
# Название пунктов меню
web.menuItem1=Счета
web.menuItem2=Счета-фактуры
# Перечень счетов, разрешенных создавать клиенту в личном кабинете. Перечень кодов типов указывается через запятую.
allowed.web.bill.types=36
# Количество, которое ставится в позиции при генерации счёта из web (по умолчанию ставится 0)
web.bill.generate.position.quantity=1
# Состояние счетов-фактур после создания - разрешено к показу/запрещено к показу в web.
# Значения параметра 1 - разрешён, 0 - запрещён.
invoice.generate.web.visible=0
#
#-----------------------
# Реквизиты договора
#-----------------------
# Список возможных реквизитов клиента:    name : title [ : regexp ] ;
# Реквизиты клиента добавляются в параметрах модуля Бухгалтерия в договоре и используются для создания печатных форм
bill.attributes=account:Счет;inn:ИНН;kpp:КПП;address:Адрес;dolz:Должность;face:Ф.И.О;osn:Основание;org_name:Полное название организации
#
#-----------------------
# НДС
#-----------------------
# Параметр с размером ставки НДС передаётся в шаблон генерации печатной формы документа
# Сумма НДС рассчитывается и отображается непосредственно в момент генерации печатной формы, по умолчанию шаблоны рассчитаны на то, что все начисления биллинга уже включают НДС.
bill.nds=18
#
#-----------------------
# INLINE-параметры
#-----------------------
# Inline-параметры позволяют выводить на распечатываемый из биллинга документ информацию, специфичную для пользователя биллинга, выполняющего печать. 
# Например: номер доверенности, имя менеджера, приказ на доверенность. Inline параметры привязываются к коду пользователя биллинга и должны быть указаны для каждого пользователя.
# Код пользователя можно посмотреть в Сервис->Администрирование->Пользователи и права первый столбец таблицы пользователей биллинга
inline.params=name;dover;dolz;prikaz
inline.param.43.name=Иванов И.И.
inline.param.43.dover=Доверенность 1
inline.param.43.prikaz=на основании приказа 33 от 12.33.06
inline.param.43.dolz=разработчик
#
#-----------------------
# Нумерация документов
#-----------------------
# Параметр определяет способ выяснения очередного номера документа и может принимать значения 0 и 1.
# При значении 0 выбирается последний созданный документ для года/месяца/абсолютно и соответствующая нумерация продолжается.
# Данный режим позволяет более гибко изменять нумерацию документов. Достаточно изменить номер последнего созданного для года/месяца документа, 
# соответствующий номер и нумерация будет продолжена после него.
# Далее изменяется номер последнего созданного документа для восстановления порядка нумерации.
# При значении 1 выбирается максимальный номер номер в году/месяце/абсолютный и соответствующая нумерация продолжается.
doc.num.mode=0
#
#-----------------------
# Настройка позиций 
#-----------------------
bill.pos.<код позиции>.title=<название, идентифицирующее позицию при сопоставлении её типу документа>
bill.pos.<код позиции>.name=<вычисляемое название позиции>
bill.pos.<код позиции>.summ=<вычисляемая сумма позиции>
bill.pos.<код позиции>.quantity=<вычисляемый объем услуги по позиции>
bill.pos.<код позиции>.qtynums=<число знаков после запятой для количества>
bill.pos.<код позиции>.unit=<строка с единицей измерения данной позиции>
bill.pos.<код позиции>.unitCode=<код единицы измерения>
# Включать ли данную позицию в сумму документа, 0 -  не включать
bill.pos.<код позиции>.insum=1
# Включать в счёт при сумме 0
bill.pos.<код позиции>.awlz=1
#
#-----------------------
# Настройка экстракторов 
#-----------------------
bill.pos.<id>.title=<обозначение экстрактора>
bill.pos.<id>.name=<обозначение экстрактора еще раз>
bill.pos.<id>.extractor=<макрос>
bill.pos.<id>.unit=<единицы измерения>
#
#-----------------------
# Выгрузка счетов
#-----------------------
# Выгрузка реестра через xsl-шаблон
# для счетов
preempt.bill.reestr.over.xsl=preempt_bill_reestr.xsl
# Выгрузка реестра через xsl-шаблон
# для счетов фактур
preempt.invoice.reestr.over.xsl=preempt_invoice_reestr.xsl
# Файл для выгрузки счетов на сервере
# для счетов
preempt.bill.reestr.to.server.path=/home/kostya/preempt.csv
# Для счетов фактур
preempt.invoice.reestr.to.server.path=/home/kostya/preemptInvoice.csv
#
#-----------------------
# Параметры e-mail 
#-----------------------
# Код e-mail параметра договора, для рассылки документов
mail.contract.param=20
# Отправлять счета субдоговора на e-mail параметра основного договора
mail.send.sub.as.parent=1
# Тема письма для рассылки документов ${fileName} заменяется на имя файла документа , макросы аналогичны mail.filename  
mail.subject=Счет от BGBilling ${fileName}
# Текст внутри письма для документов (используються макросы как в mail.subject)
mail.text=Ваш счет за интернет
# По умолчанию, текст отправляется как PLAIN, если нужно отправить как HTML, раскоментируйте параметр ниже
# mail.text.type=html 
# Шаблон для имени файла документа при рассылке.
# Возможны следующие макроподстановки
# ${type} - тип документа, 
# ${N} - номер документа, 
# ${contract.title}${contract.id} - номер и id договора, или супердоговора, если включен флаг mail.send.sub.as.parent=1 
# ${contract.title.sub}${contract.id.sub} - номер и id договора
# ${contract.comment.sub} и ${contract.comment} -  комментарий договора и супердоговора, если включен флаг mail.send.sub.as.parent=1 
# ${param_N} - текстовый параметр, номер N для договора, или супердоговора, если включен флаг mail.send.sub.as.parent=1 
# ${sub.param_N} - текстовый параметр, номер N для договора
# ${formatN} - форматированый номер документа, 
mail.filename=${type}_${N}_${contract.title}(${contract.id})_for_${param_4}_document
#
#-----------------------
# Остальные параметры 
#-----------------------
# Состояние checkbox на вкладке "Выставление документов" для новых счетов
bill.generate.new.checked=1
#
# Состояние checkbox на вкладке "Выписка счетов" для новых счетов-фактур
invoice.generate.new.checked=1
#
# Заносить платеж при пометке счета оплаченным: 0 - не заносить; 1 - заносить; 2 - заносить с подтверждением (ввод суммы и комментария к платежу)
pay=0
#
# В XML-дерево документов добавлять дополнительные данные по договору
add.contract=1
#
# Код спискового параметра, определяющего номер "пачки" клиента, см. далее про первичную подготовку для курьеров 
# package.param.id=<код спискового параметра>
#
# Код адресного параметра договора, используется при сортировке счета по адресу (улица/индекс)
# address.sort.param.id=<код параметра Адрес>
#
# Коды текстовых параметров для сортировки по ФИО/наименованию для фил. и юр. лиц соответственно
name.sort.param.id=<id для физ. лиц>,<id для юр.лиц> 
#
# Разделитель в csv файлах. Для реестра счетов по умолчанию ","
csv.separator=,
#Использовать мастер базу
#use.master.connection=1

Шаблоны оформления печатных форм описаны на языке XSLT и генерируют на выходе FO-документы, основываясь на XML-дереве с данными, предоставляемым модуле. Более подробно о настройке шаблонов описано далее.

3.1. Настройка позиций

Позиция - это составная часть документа, обладающая суммой, количеством и единицей измерения, которую биллинг вычисляет для конкретного договора и месяца и подставляет в документ. Позиции счетов и счет-фактур задаются в конфигурации модуля, каждая позиция идентифицируются числовым кодом, коды позиций счетов и счет-фактур могут пересекаться.

Позиции счетов/счетов-фактур задаются аналогично, с той лишь разницей, что префикс bill.pos заменяется на invoice.pos. Разберём более подробно различные параметры позиции.

В name может быть указана произвольная строка с подстановками $month, $nextmonth, $prevmonth, $prev2month, $prev3month. Подстановка означает строковое название месяца за который выставляется счёт, следующего месяца, предыдущего месяца, и ещё двух предыдующих месяцев. Также возможно вывести значение месяца в произвольном формате, вместо $month ($nextmonth и т.п.) указать в виде {$month,date,фомат}, например {$month,date,MMMM yyyy г.} - результатом будет апрель 2009 г.

В summ могут быть указаны следующие макросы, связанные знаками "+" и "-". Вместо <month> могут быть подставлены значения $month, $nextmonth, $prevmonth, $prev2month, $prev3month, означающие в данном контексте месяц, за который производится выборка.

DEBT(<month>) - долг на конец месяца, равен минус исходящему остатку;
IN_REST(<month>) - входящий остаток на месяц;
SERVICE_ACCOUNT(<month>, <коды услуг через запятую>) - наработка по определённым услугам;
FULL_ACCOUNT(<month>) - суммарная наработка по всем услугам;
CHARGE(<month>, <коды расходов через запятую, не обязательный параметр>) - сумма расходов за месяц;
PAYMENT(<month>, <коды типов платежей, не обязательный параметр>) - сумма платежей за месяц;
NPAY_MIN_ACCOUNT(<код экземпляра модуля абонплат>,<month>,<код услуги модуля абонплат>) - для "доводящей абонплаты" сумма, до которой она доводится;
BILL_BILL_SUM(<код экземпляра модуля бухгалтерия>,<month>,<коды типов документов>) - сумма выставленных счетов за определённый месяц для данного договора, перечень кодов типов документов через запятую - необязательный параметр;
BILL_INVOICE_SUM(<код экземпляра модуля бухгалтерия>,<month>,<коды типов документов>) - сумма выставленных счетов-фактур за определённый месяц для данного договора, перечень кодов типов документов через запятую - необязательный параметр;
CONST(<число>) - числовая константа.

В quantity могут быть указаны следующие макросы, связанные знаками "+" и "-". Вместо <month> могут быть подставлены значения $month, $nextmonth, $prevmonth, $prev2month, $prev3month, означающие в данном контексте месяц, за который производится выборка. Вместо <mid> подставляется код экземпляра соответствующего модуля. Вместо <sids> подставляются коды услуг через запятую, это уточняющий и не обязательный параметр, если он не указан, будут взяты все услуги.

KERNEL_SERVICE_COUNT(<month>, <коды услуг через запятую>) - количество разрешенных услуг, определённых перечнем, заведённых в договоре на начало указанного месяца;
NPAY_SERVICE_COUNT(<mid>, <month>, <sids>) - количество услуг абонплаты, определённых перечнем, заведённых в договоре на начало указанного месяца, учитывая параметр кол-во в свойствах услуги абонплат;
NPAY_SERVICE_COUNT_MONTH(<mid>, <month>, <sids>) - аналогично предыдущему, но считается количество услуг абонплат не на первое число месяца, а всего попавших в данный месяц отрезков данных услуг;
DIALUP_SERVICE_AMOUNT(<mid>, <month>, <делитель>, <sids>) - объем услуг DialUP модуля, делитель определяет число, на которое будет разделен объем услуги (байты для трафика, секунды для времени); Например, делитель 1048576 даст объем в МБ для услуг типа трафик;
DIALUP_MAX_SERVICE_AMOUNT(<mid>, <month>, <делитель>, <sids>) - объем услуг DialUP модуля типа "максимальный трафик", делитель определяет число, на которое будет разделен объем услуги (байты для трафика). Например, делитель 1048576 даст объем в МБ для услуг типа трафик;
DIALUP_LOGIN_COUNT(<mid>, <month>) - количество DialUP логинов на начало месяца;
VOICEIP_SERVICE_AMOUNT(<mid>, <month>, <делитель>, <sids>) - объем услуг VoiceIP модуля в секундах округлённого времени, делитель определяет число, на которое будет разделен объем услуги. Например, делитель 60 даст объем в минутах;
VOICEIP_LOGIN_COUNT(<mid>, <month>) - количество VoiceIP-логинов на начало месяца;
IPN_SERVICE_AMOUNT(<mid>, <month>, <делитель>, <sids>) - объем услуг IPN модуля в байтах, делитель определяет число, на которое будет разделен объем услуги. Например, делитель 1048576 даст объем в МБ;
IPN_MAX_SERVICE_AMOUNT(<mid>, <month>, <делитель>, <sids>) - объем услуг IPN модуля типа "максимальный трафик" в байтах, делитель определяет число, на которое будет разделен объем услуги. Например, делитель 1048576 даст объем в МБ;
PHONE_SERVICE_AMOUNT(<mid>, <month>, <делитель>, <sids>) - объем услуг Phone модуля в секундах округлённого времени, делитель определяет число, на которое будет разделен объем услуги. Например, делитель 60 даст объем в минутах;
PHONE_ZERO_SERVICE_AMOUNT(<mid>, <month>, <делитель>, <sids>) - то же, что предыдущее, но считаются только сессии с нулевой стоимостью;
PHONE_NOZERO_SERVICE_AMOUNT(<mid>, <month>, <делитель>, <sids>) - то же, но считаются только сессии с ненулевой стоимостью;
PHONE_NOZERO_SERVICE_COUNT(<mid>, <month>, <sids>) - считается кол-во сессий с ненулевой стоимостью;
PHONE_POINT_COUNT(<mid>, <month>) - количество Phone-поинтов на начало месяца;
RSCM_SERVICE_AMOUNT(<mid>, <month>, <делитель>, <sids>) - объем услуг RSCM-модуля в единицах, делитель определяет число, на которое будет разделен объем услуги;
INET_SERVICE_AMOUNT(<mid>, <month>, <делитель>, <sids>) - объем услуг Inet-модуля, делитель определяет число, на которое будет разделен объем услуги (байты для трафика, секунды для времени). Например, делитель 1048576 даст объем в МБ для услуг типа трафик;
INET_SERV_COUNT(<mid>, <month>) - количество Inet-сервисов на начало месяца.

Если quantity не указано, то позиция принимается за единицу.

Начиная с версии 4.6, добавлен необязательный параметр позиции - число знаков после запятой для количества (qtynums). По умолчанию он принимается за 0 (т.е. количество округляется соответствуя логике предыдущих версий).

В unit указывается просто строка вида "Мб", "Кб", "мин.". Если параметр не указан, то единицы принимаются за "шт.". Параметр unitCode определяет цифровой код единицы измерения. Если параметр не указан, то подставляется код 796, который, согласно Общероссийскому классификатору единиц измерений, соответствует единице измерения "шт.".

Если параметр insum не указан, позиция включается в сумму документа, для исключения необходимо установить его в 0. Данный режим может быть полезен для позиций, несущих вспомогательную информацию.

Если параметр awlz указан, позиция включается в сумму документа, даже если сумма по позиции 0. Данный режим может быть полезен в случаях, когда нужно показать отсутствие расходов по позициям.

Рассмотрим несколько примеров построения позиций.

Пример 9.1. Пример первый

Клиенту необходимо выставлять суммарный долг за услуги интернета.

bill.pos.1.title=Долг за услуги Интернет
bill.pos.1.name=Долг за услуги Интернет за $month 
bill.pos.1.summ=DEBT($month)

Пример 9.2. Пример второй

А корпоративным клиентам необходимо выставлять отдельными строчками абонплату, наработку по интернет и телефонии. За каждый месяц необходимо выставлять счета с наработкой за данный месяц и предоплатой абонплаты за следующий. Предположим, что у нас в системе установлен модуль абонплат, IPN и VoiceIP. Предположим также, что существуют следующие коды услуг:

  • Абонплата - 1;

  • Трафик -2;

  • Телефония - 3.

Так будет выглядеть настройка позиций счетов и счетов-фактур:

bill.pos.1.title=Долг за услуги Интернет и Телефонию
bill.pos.1.name=Долг за услуги Интернет и Телефонию за $month 
bill.pos.1.summ=SERVICE_ACCOUNT($month, 2, 3 )
bill.pos.2.title=Абонплата за Интернет и Телефонию
bill.pos.2.name=Абонплата за Интернет и Телефонию за $nextmonth
bill.pos.2.summ=SERVICE_ACCOUNT($nextmonth,1 )
# 
invoice.pos.1.title=Услуги Интернет и Телефонии
invoice.pos.1.name=Услуги Интернет и Телефонии за $month
invoice.pos.1.summ=SERVICE_ACCOUNT($month, 2, 3)
invoice.pos.2.title=Абонплата за Интернет и Телефонию
invoice.pos.2.name=Абонплата за Интернет и Телефонию за $month
invoice.pos.2.summ=SERVICE_ACCOUNT($month, 1)

Возможно суммирование и вычитание макросов суммы и количества. Например, следующим образом можно добавить в наработку определённые виды расходов:

invoice.pos.3.summ=SERVICE_AMOUNT($month,101,102)+CHARGE($month,14,8,1,54,32)

3.1.1. Экстакторы

Зачастую в системе присутствуют большое количество однотипных списаний и абонентских плат. В этом случае конфигурирование под каждую отдельной позиции достаточно обременительно и могут использоваться экстракторы. Позиция с экстрактором заводится в конфигурации модуля.

Параметры title и unit имеют значение, аналогичные обычным позициям. В параметр extractor может быть подставлен один из перечисленных ниже макросов. Вместо <month> могут быть подставлены значения $month, $nextmonth, $prevmonth, $prev2month, $prev3month, означающие в данном контексте месяц, за который производится выборка. Вместо <mid> подставляется код экземпляра соответствующего модуля.

KERNEL_CHARGES(<month>, <коды типов расх>) - расходы договора в каком-то месяце. Тип расхода становится названием позиции, количество расходов данного типа - количеством. При не указании кодов типов расходов выбираются все типы расходов;
KERNEL_CHARGES_EXCEPT(<month>, <коды типов расходов, которые исключаются>) - аналогичен предыдущему, но указываются коды типов расходов, которые не выбираются;
NPAY_SERVICES(<mid>, <month>, <коды услуг>) - начисления абонплат в каком-то месяце. Название услуги абонплаты становится названием позиции, количество абонплат данного типа, установленных в договоре на данный месяц - количеством. При не указании кодов услуг выбираются все начисленные на договор абонплаты;
NPAY_SERVICES_EXCEPT(<mid>, <month>, <коды услуг, которые исключаются>) - аналогичен предыдущему, но указываются коды услуг, которые не выбираются;
RSCM_SERVICES(<mid>, <month>, <коды услуг>) - начисления по услугам RSCM в каком-то месяце. Название услуги RSCM становится названием позиции, количество услуги - количеством оказанной услуги . Единица измерения услуги - единица измерения счета При не указании кодов услуг выбираются все услуги RSCM оказанные для данного договора;
RSCM_SERVICES_EXCEPT(<mid>, <month>, <коды услуг, которые исключаются>) - аналогичен предыдущему, но указываются коды услуг, которые не выбираются;
EXT-экстракторы (KERNEL_CHARGES_EXT, KERNEL_CHARGES_EXT_EXCEPT, NPAY_SERVICES_EXT, NPAY_SERVICES_EXT_EXCEPT и т.д.) - расширенные (EXTended) экстракторы, которые в отдельную позицию выделяют каждый расход (для ядра) и каждую услугу (для модулей), даже если они имею одинаковый тип (код). Аргументы для экстрактора те же, что и для аналогичных нерасширенных.

Позиция экстрактора "распадается" в момент генерации документа на множество позиций в зависимости от реального количества начислений на договоре.

В unit указывается единица измерения - простая строка.

Пример 9.3. Пример экстрактора

Получение всех расходов за месяц:

bill.pos.3.title=Расходы
bill.pos.3.name=Расход
bill.pos.3.extractor=KERNEL_CHARGES($month)

3.1.2. Детализация по тарифу

C версии 4.5 возможна детализация по тарифу, т.е. получение и вывод информации, например, по количеству и наработке по предоплаченному трафику и превышению трафика.

Для этого сначала в тарифицируемом модуле (dialup или ipn) необходимо указать коды начислений:

# Код начисления
tariff_detail.cost_type.1=Включённый трафик
# Дополнительные параметры, range_take_all=1 предназначен для ветки диапазон, 
# если установлен, то независимо от того, сколько наработал в этом диапазоне договор, 
# количество наработки будет равняться кол-ву в диапазоне
tariff_detail.cost_type.1.range_take_all=1
# Код услуги, по которому отбираются договоры для обсчёта range_take_all 
# (т.к. договор может не иметь наработки совсем)
tariff_detail.cost_type.1.range_take_all.sid=
tariff_detail.cost_type.2=Превышение трафика

В приведённом выше примере два кода начисления, Включённый трафик (60000 байт) и Превышение трафика. Т.к. опция range_take_all=1 включена, то кол-во по Включённому трафику будет всегда 60000 байт, даже если договор наработал меньше.

Для детализации максимальных трафиков необходимо для кода начисления указать calc_type=2:

#код начисления
tariff_detail.cost_type.1=Включённый трафик (макс)
tariff_detail.cost_type.1.calc_type=2

Внимание

Для вычисления детализации по тарифу необходимо запускать переобсчет за весь месяц в тарифицируемом модуле. При этом можно переобсчитывать как группу договоров, так и отдельный договор. Иначе в выставленных после этого счетах/счетах-фактурах вы можете получить неполные данные.

Рекомендуемая процедура следуюущая: по окончании расчитываемого месяца (в начальных числах следующего) запускаете вручную переобсчет, а после него формируете счета, счета-фактуры. Для модуля IPN существует еще одно решение.

Теперь для поля summ в конфигурации модуля бухгалтерии доступен следующий параметр:

TARIFF_DETAIL_COST(<mid>, <month>, коды начисления) - сумма начисления в детализации по тарифу для модуля.

а для поля quantity:

DIALUP_TARIFF_DETAIL_AMOUNT(<mid>, <month>, <делитель>, коды начисления) - объем начисления в детализации по тарифу для модуля dialup;
IPN_TARIFF_DETAIL_AMOUNT(<mid>, <month>, <делитель>, коды начисления) - объем начисления в детализации по тарифу для модуля ipn.

3.2. Номерной пул

Номерные пулы - это сущности, в рамках которых выдаются номера очередному созданному документу. Номерной пул может быть один общий для нескольких документов. Обязательными и неудаляемыми являются номерные пулы По умолчанию (счета) и По умолчанию (счета-фактуры).

Для каждого документа запоминается его номерной пул, номер порядковый абсолютный, номер порядковый в пределах года и номер в пределах месяца. Отображаемый номер документа формируется из данных номеров, его вид определяется шаблоном.

Для настройки номерных пулов необходимо указать шаблон, по которому будет формироваться номер документа. Номер документа может состоять из произвольных символов и следующих макроподстановок:

$number{X} - абсолютный порядковый номер;
$number{START,X} - абсолютный порядковый номер, начиная со START;
$number_in_year{X} - номер в пределах года;
$number_in_month{X} - номер в пределах месяца;
$month - номер месяца (двузначный - от 01 до 12);
$year - номер года (четырёхзначный);
$contract_title - номер договора
Здесь X - это количество цифр, выделяемых под соответствующий номер, т.е. подставляемые номера дополняются нулями слева до длины, определенной этим числом.

3.3. Типы документов

Тип документа определяет, какие позиции включает счет или счет-фактура. Типы определяются отдельно для счетов и счетов-фактур на вкладке Типы документов конфигурации модуля.

Для каждого типа документа указываются активные позиции, название. Поле XSLT-шаблон задаёт имя шаблона, используемого для создания печатной формы. Шаблон располагается в каталоге BGBillingServer/webroot/xsl. Если шаблон не указан, то для счетов используется bill_pdf.xsl, а для счет-фактур invoice_pdf.xsl. О генерации печатных форм будет подробно описано далее.

Далее переходим во вкладку Настройка. Здесь можно указать номерной пул, по которому будет формироваться очередной номер для документа. Опция Создавать при сумме счета <= 0 означает требование к созданию документов данного типа даже с неположительной суммой. Опция Создавать при сумме счета < 0 означает требование к созданию документов данного типа во всех случаях, кроме случая равенства суммы нулю. Опция Позиции субдоговоров вызывает генерацию в исходное XML-дерево документа вычисленных значений позиций с разбивкой по субдоговорам. В шаблоне счета и счет-фактуры по умолчанию эти данные не используются, использование опции возможно только с модификацией шаблонов документов.

.

Для более тонкой настройки типа документа возможно указывать ключи в текстовом поле конфигурации. Возможные ключи для типов документов:

create.only.when.pos.positive=x,y,...,z - создание счета\счета-фактуры только в том случае, если указанные позиции с кодами x,y,...,z положительны.

Внимание

Т.к. файлы bill_pdf.xsl и invoice_pdf.xsl перетираются при каждой установке обновления модуля, мы рекомендуем вам скопировать их в файлы с иными именами (bill_pdf_my.xsl, invoice_pdf_my.xsl) и ссылать ваши типы документов уже на ваши файлы.

3.4. Настройка банков

Каждый счёт в системе выписывается на какой-либо счёт провайдера в каком-либо банке. Все банки должны быть указаны на вкладке Банки конфигурации модуля. Информация о банке используется для генерации образца платёжного поручения в счёте.

Параметр Название задаёт обозначение счета для идентификации его внутри модуля. Название банка - точное название банка, используемое в образце платёжного поручения.

Тип платежа - не редактируемый тип платежа, который будет заносится в договор при пометке счета оплаченным и установленной опции pay=1 в конфигурации модуля.

Внимание

должен быть занесён счёт хотя бы в одном банке, реквизиты которого будут указаны в счетах.

4. Настройка параметров договора

Реквизиты позволяют указывать в свойствах договора специфичные для него параметры. В отличие от параметров договора атрибуты поименованы, а не идентифицируется числовыми кодами. Следует учитывать, что в шаблоне генерации печатной формы можно использовать как атрибуты, так и параметры договора.

Выбор (между параметрами и реквизитами) места хранения данных по ИНН, полному названию организации производится администратором биллинга. Возможна и комбинация этих способов. По-умолчанию шаблоны счета и фактуры ссылаются на реквизиты, указываемые в конфигурации. Реквизитов может быть сколь угодно много, добавляются через точку с запятой. Двоеточием разделяются название для использования в шаблоне и человеко-читаемое обозначение.

Для выставления документов необходо добавить модуль в договор. Далее необходимо добавить реквизиты и выбрать какие документы будут вытсавлятся договору. Также вместо реквизитов при генерации документов могут использоваться параметры договора, в таком случае реквизиты добавлять не нужно.

Для добавления реквизитов выберите в дереве модуль бухагалтерии и перейдите на вкладку Реквизиты.

Для добавления документов договору перейдите на вкладки Виды счетов и Виды счетов-фактур. Затем выделите и переместите в левую часть необходимые документы.

Замечание

Для массовой установки типов документов и услуги модуля договорам можно использовать Групповые операции. С 4.4 версии требуемые типы документов можно указывать в шаблонах договоров.

5. Выставление счетов и счетов-фактур администратором

Для выставления счетов и счет-фактур используется вкладка Выставление документов

В левом верхнем углу выбирается месяц, за который выставляются документы. В выпадающем списке Тип документа выбирается вид документа для генерации: либо Счета, либо Счета-фактуры. На вкладке Договоры/группы возможно задание фильтров для генерации документов конкретным договорам и группам договоров. На вкладке Типы устанавливаются типы документов для генерации.На вкладке Условия устанавливаютя дополнительные условия фильтрации договоров. На данный момент существует возможность выставления счетов только тем договорам, у которых исходящий остаток на месяц выставления документа находится в заданных пределах. Крайние точки указанного предела включаются в поиск. Если же одно из двух значений не указано, то это означает "до бесконечности".

На скриншоте показан пример фильтра, по которому будут сгенерированы документы для договоров с исходящим остатком менее, либо равным минус одной копейке.

Все вышеперечисленные фильтры можно использовть одновременно. Если фильтры не установлены, генерируются все возможные типы документов для всех договоров в базе, к которым привязан модуль. Для договора генерируются только те типы документа, которые прописаны в свойствах модуля договора на вкладках Виды счетов и Виды счетов-фактур. Период договора должен пересекаться с месяцем, за который генерируются документы. После установки фильтров нажмите кнопку Сгенерировать.

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

Вы можете сохранять промежуточные результаты правки в файл, используя область внизу окна (поле выбора файла, кнопки Сохранить и Восстановить).

Отредактируйте позиции, если необходимо, уберите галочки в таблице с документов, которые создавать не нужно и нажмите кнопку Создать счета, либо Создать счета-фактуры. Создадутся только те документы, сумма которых больше нуля! Чтобы документ создавался с отрицательной позицией в типе документа должна стоять опция Создавать при сумме счета <= 0. Начальное состояние галочек в таблице задаётся опциями конфигурации модуля. При создании счетов необходимо выбрать счёт в банке, это делается в выпадающем списке Банк. счет, к которому привязывается документ, данные используются для генерации образца платёжного поручения в печатной форме счета.

Выставить счета можно также без предварительного просмотра сгенерированных счетов и редактирования их позиций. Для этого сначала задаются все необходимые фильтры и потом нажимается кнопка Сгенерировать+Создать.

Созданным документам присваиваются номера и они сохраняются в базе, дальнейшая работа с ними происходит на вкладках Счета и Счета-фактуры модуля, либо в отчёте модуля бухгалтерии в карточке договора.

6. Работа со счетами

Производится на вкладке Счета.

Здесь доступны множество различных фильтров для счетов, с помощью которых легко найти необходимые счета. При нажатии кнопки Поиск происходит поиск счетов и вывод их в таблицу. Возможно отсортировать найденные документы при помощи выпадающих списков Сортировка 1 и Сортировка 2 (сперва сортируется по сортировке 1, затем по сортировке 2). Поддерживаются следующие режимы сортировки документов:

договор/номер - стандартный режим, сортировка по номеру договора;
договор (учитывая суб.) - стандартный режим, сортировка по номеру договора с учетом номеров суб договоров;
номер - сортировка по номеру документа по возрастанию;
номер обр. - сортировка по номеру документа по убыванию;
ID - сортировка по коду документа в БД (по возрастанию);
ID обр. - сортировка по коду документа в БД (по убыванию);
улица/дом - сортировка по улице/номеру дома/квартире;
индекс - сортировка по индексу/улице/номеру дома/квартире;
город/квартал - сортировка по городу/кварталу;
ФИО/наименование - сортировка по параметру ФИО/наименование договора.

При использовании 4-х последних режимов сортировки в конфигурации модуля должены быть установлены соответствующие параметры - код параметра договора типа Адрес и код параметра договора типа Текст.

Для выбора нескольких строк таблиц воспользуйтесь кнопками Ctrl, Shift, либо комбинацией Ctrl+A для выбора всех строк. Нажатием правой кнопки мыши может быть вызвано всплывающее меню, применяющее одно из следующих действий ко всем выбранным документам:

При пометке счета оплаченным автоматически проводится платёж с типом, указанным в банковском счёте, на который создан счёт и текущей датой. Автоматическое проведение платежей можно отключить, установив опцию в конфигурации модуля.
Оплачено сегодня(dd.MM) - все выбранные счета помечаются как оплаченые с сегодняшней датой;
Оплачено вчера(dd.MM) - все выбранные счета помечаются как оплаченные вчерашней датой;
Оплачено на дату - все выбранные счета помечаются как оплаченные с выбранной датой;
Не оплачено - снять метку оплаченности с выбранных документов;
Просмотр - поместить выбранные документы в панель просмотра (вкладка Просмотр документов). В панели просмотра вы можете распечатать выбранные документы, сохранить их, либо отправить на почту (см. далее про панель просмотра документов);
Вставить в просмотр - документы вставляются в окне просмотра вслед за документами, принадлежащими тому же договору. Таким образом для распечатки 2х копий счет-фактур и одной копии счета необходимо выбрать счета-фактуры, выбрать Просмотр, затем это же выделение Вставить в просмотр, после чего выбрать счета для этих же договоров, а также Вставить в просмотр. В окне просмотра появится последовательность листов "счет-фактура - счет-фактура - счет";
Отослать на почту - создается задание для планировщика, которое отправляет все выбранные документы на почту. Код параметра договора для почты устанавливается в конфигурации модуля.

Двойным щелчком мыши по любой из строк вы можете вызвать редактор документа:

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

Перечень счетов и счет-фактур можно выгрузить в реестр CSV-формата. В реестре отображается номер счета, сумма, дата выставления, тип и адрес. Параметр адреса задаётся переменной конфигурации модуля. Для выгрузки используется панель под таблицей счетов. Также можно настроить формат выгрузки счетов и счет-фактур при помощи шаблонов xsl. Для использования этого способа выгрузки необходимо в конфигурации модуля указать шаблоны для счетов и счетов-фактур. Шаблоны по умолчанию для выгрузки счетов и счет-фактур лежат в дериктории BGBillingServer/webroot/xsl и называются соотсветственно preempt_bill_reestr.xsl и preempt_invoice_reestr.xsl. Собственные шаблоны выгрузки необходимо разместить в той же директори, где находятся базовые шаблон, а имена шаблонов прописать в конфигурации модуля. Если параметры для выгрузки через шаблоны не будут указаны, то выгрузка будет происходить в старом формате, т.е. будет выгружаться таблица со списком найденных счетов или счетов-фактур.

Также возможно выгрузить реестр на стороне сервера. Для этого необходимо перед выгрузкой в клиенте указать данную опцию, выбрав галочку, и в конфигурации модуля указать следующие параметры: preempt.bill.reestr.to.server.path=<Path> - для выгрузки счетов и preempt.invoice.reestr.to.server.path=<Path> - для выгрузки счетов-фактур, где <Path> - путь с именем файла, куда будет происходить выгрузка. Необходимо проветить права на запись у указанной директории, чтобы сервер смог туда записать фалы. При выгрузке реестра, если файл не существует, то он будет создан, а если существует, то все данные, содержащиеся в файле, будут заменены нвовыми.

6.1. Первичная подготовка для курьерской службы

Модуль позволяет проводить первичную подготовку пакетов документов для курьерской службы: осуществляет сортировку по улице/дому и группировку по пачкам (маршрутам). Для активизации данной функции в конфигурации модуля должны быть указаны параметры package.param.id и address.sort.param.id. Параметр package.param.id определяет код параметра договора типа Список, который задаёт маршрут (пачку) для договора. Перечень допустимых значений данного параметра указывается в Справочники=>Другие=>Значения списков. Параметр определяется для каждого договора и задаёт маршрут, к которому относится договор.

Если код спискового параметра указан верно в фильтре Пачка, в окне управления счетами будут отображаться допустимые значения спискового параметра договора. Например, это может быть: Запад, Центр, Восток. Или иное деление. В общем случае, пачка может нести любой смысл, позволяя разделить документы.

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

7. Работа со счетами-фактурами

Производится на вкладке Счета-фактуры.

По сравнению со счетами набор фильтров уменьшен.

В всплывающем меню доступны опции добавления и вставки в панель просмотра, а также дополнительные пункты Разрешено к показу и Запрещено к показу. Разрешённый к показу документ доступен на странице статистики пользователя. Возможность реализована для проведения предварительной сверки и корректировки фактур.

Разрешённость к показу сгенерированного счета-фактуры в Web задаётся опцией в конфигурации модуля.

Двойным щелчком мыши по любой из строк вы можете вызвать редактор документа:

Поле Исправление предназначено для подстановки в счет-фактуру при выгрузке печатной формы порядкового номера исправлений, внесенных в счет-фактуру. Поле Платежно-расчетный документ позволяет сделать ссылку на документ, к которому относится данная счет-фактура (например, счет).

В случае, если поля Платежно-расчетного документа пустые, а поле Исправление равно 0, то в счет-фактуре будет отображаться прочерк на соответствующем месте.

8. Панель просмотра документов

На панели просмотра отображаются счета и счета-фактуры добавленные, либо вставленные в просмотр.

Элемент управления в верхней части окна позволяет перелистывать документы. Список документов также находится в левой части окна просмотра и позволяет быстро перейти к нужному документу. Следующий элемент - перелистывание страниц в пределах одного документа. Кнопка XML позволяет просмотреть исходный XML-документ, на основании которого генерируется печатная форма. Этот режим полезен при модификации и отладке XSLT-шаблонов для генерации печатных форм (см. далее). Возврат в режим просмотра печатной формы осуществляется повторным нажатием кнопки XML. По нажатию на кнопку Разослать на почту происходит добавление задачи в планировщик «Задача рассылки документов с компоновкой». В этом режиме для отправки документа e-mail берется из конфигурации модуля. Отправляются все документы, добавленные в просмотрщик, по всем договорам, у которых они добавлены.

Кнопки сохранения и отправки на почту позволяют сохранить/отправить текущий просматриваемый документ. Печать документов производится в поблочном режиме, размер блока печати задаётся в окне. После отправки на печать каждого блока выводится новый диалог печати. Данная функция предназначена для потоковой печати большого количества документов.

Печать по номерам документов позволяет печатать диапазон добавленных в просмотр документов. Клик на звёздочку - быстрый переход к просмотру документа с введённым номером .

9. Генерация печатных форм

Генерация печатной формы производится XSLT-шаблоном, указанным в типе счета или счета-фактуры. Если шаблоны не указаны, используются шаблоны по умолчанию bill_pdf.xsl, который используется при генерации визуального представления счета и invoice_pdf.xsl для счет-фактуры. Все XSLT-шаблоны располагаются в каталоге BGBillingServer/webroot/xsl.

Минимальная настройка стандартных шаблонов включает в себя изменение реквизитов организации:

<!-- РЕКВИЗИТЫ ПРЕДПРИЯТИЯ -->

<xsl:variable name="postal_address" select="'450001, г.Уфа, проспект Октября, д.4, адм. здание'" />

<xsl:variable name="INN" select="'ИНН 0275023387'" />
<xsl:variable name="KPP" select="'КПП 027801001'" />
<xsl:variable name="title" select="'ООО фирма &quot;БИС&quot;'" />

<xsl:variable name="OKVED" select="'ОКВЭД 82000'" />
<xsl:variable name="OKPO" select="'ОКПО 45219144'" />

<!-- РЕКВИЗИТЫ ПРЕДПРИЯТИЯ -->

Они используется для построения верхней части PDF-документа (см. ниже). В каталоге BGBillingServer/webroot находится изображение печати - файл stamp.gif. Замените его на отсканированную копию печати вашей организации.

Внимание

При каждом обновлении модуля bill файл перетирается, так же как и шаблоны по умолчанию. Вы можете переименовать файл и ссылки на него в шаблонах счетов и счетов-фактур.

Шаблоны по умолчанию используют для оформления печатных форм реквизиты договора из свойств модуля (перечень приведён в конфигурации модуля по умолчанию). Вы можете использовать для этих же целей параметры договоров, но это потребует модификации XSLT-шаблонов.

Банковские реквизиты берутся из справочника банковских реквизитов (текущий указывается при создании счета). В графе Плательщик указывается комментарий договора. Вычисление суммы НДС производится в момент генерации печатной формы.

В базе данных информация о счёте, либо счёте-фактуре сохраняется в виде XML-документа и содержит следующие поля:

  1. сумму документа;

  2. набор позиций с суммами;

  3. параметр НДС из конфигурации модуля;

  4. параметры договора;

  5. реквизиты модуля Бухгалтерия из договора;

  6. INLINE-параметры - специфичные для текущего пользователя (номера доверенностей, Ф.И.О.).

Модуль осуществляет подстановку INLINE-параметров в XML-документ в зависимости от пользователя, просматривающего документы. Перечень INLINE-параметров определяется в конфигурации модуля. Для просмотра исходного XML-документа, из которого генерируется печатная форма, необходимо воспользоваться панелью просмотра документа.

Замечание

При модификации и отладке XSLT-шаблона следует отключить кэширование XSLT-шаблонов (опция xslt.cache в конфигурации сервера биллинга).

10. Отчёты договора модуля

В сводном отчёте отображаются счета и счет-фактуры договора с обратной сортировкой по месяцу, за который они выставлены.

Для редактирования счетов или счет фактур вызовите редактор двойным кликом по строке.

Также имеется возможность выставление счетов и счет-фактур в отчетах договора.

Для выбора документов в таблице воспользуйтесь мышью с зажатыми клавишами Shift и Ctrl. При нажатии правой кнопкой мыши появляется контекстное меню, позволяющее просмотреть выбранные документы (пункт Просмотреть). Для счетов доступны пункты Оплачено сегодня, Оплачено вчера, Оплачено на дату и Не оплачено. Панель просмотра отображается на месте таблицы, для возвращения к таблице документов воспользуйтесь кнопкой Вернуться к списку.

11. Web-интерфейс пользователя

В личном кабинете пользователь может просматривать счета и счет-фактуры в пунктах меню Счета и Счета-фактуры (названия пунктов меню могут быть изменены в конфигурации модуля). Отображаются все документы договора в режиме обратной сортировки по месяцу, за который они были выписаны.

Замечание

Счета-фактуры не отображаются в личном кабинете до тех пор, пока не будут разрешены к показу администратором (пункт Разрешено к показу во всплывающем меню таблицы счетов-фактур). Данная возможность реализована для возможности предкорректировки документов.

Нажав на ссылку PDF, пользователь получит готовый для распечатки счёт в виде PDF-документа:

При нажатии на кнопку Новый счёт под таблицей просмотра счетов пользователь попадает на страницу создания счета. Если в справочнике банковских реквизитов несколько записей, то рядом с кнопкой Принять отображается выпадающий список. Далее он может использовать либо подготовленный счёт, либо ввести свою сумму и создать собственный счёт.

Перечень типов счетов, разрешённых к созданию пользователем через Web, задаётся опцией конфигурации модуля. Также тип счета должен быть добавлен в договоре.

Замечание

Для того, чтобы узнать код типа счета выберите в таблице типов документов нужный тип и нажмите Ctrl+i.

Пользователь может скорректировать сумму счета. Разумеется, самостоятельное создание счетов разрешается только для договоров, работающих по предоплате.

Пользователь может удалять неоплаченные счета, созданные самостоятельно.

Количество, которое ставится в позиции при генерации счетов из web можно настроить в конфигурации модуля (хотя это число не имеющее особого значения).

12. Тонкости интеграции с внешними (1С) системами

В запросе выдачи счетов и счет-фактур (action=Bill, action=Invoice) возможна передача параметра get_xml=1. При этом в таблице документов будут выдаваться полные XML со счетами и счет-фактурами.

В запросе пометки счета оплаченным (action=SetPayed) возможна передача параметра pay=0. При этом счёт просто будет помечен оплаченным, а приход на баланс проведён не будет.

13. Групповые операции над договорами

13.1. Операция "Добавление ( Удаление ) типов документов"

Операция позволяет добавить или удалить счета и счет-фактуры в договорах.

Глава 10. Модуль Buyemoney (beta-версия)

1. Назначение модуля

Модуль предназначен для покупки электронной валюты из личного кабинета пользователя.

2. Структура и настройка модуля

Модуль содержит несколько различных "драйверов", связанных одинаковым API и реализующих несколько протоколов. Все драйверы зашиты в модуль, в конфигурации можно привязать каждый из протоколов, подразумевающихся к использованию к нужной электронной валюте.

В общем виде конфигурация выглядит так:

# обязательные:
currency.1.title=yandex RUR
currency.1.code=yandex RUR
currency.1.protocol=ru.bitel.bgbilling.modules.buyemoney.server.protocols.yd.YDProtocol
# id параметра договора, в котором лежит номер кошелька
currency.1.pursePid=35
# тип расхода, которым будут оформляться покупки денег
currency.1.chargeType=55
# шаблон, по которому формируется комментарий к платежу, формируемуму по продаже
currency.1.chargeCommentTemplate=Покупка ${sumcur} ${cur} за ${sumtotal} (курс ${rateprice}, дата ${date}, транзакция ${id}) на кошелёк ${purse}
# шаблон, по которому формуруется комментарий к платежу на сервер авторизации ("основание зачисления")
currency.1.transactCommentTemplate=${contract} (${contract_comment}), транзакция ${id}, комментарий: ${user_comment}
# режим кошелька 
# 1 - принудительно использовать кошелёк из параметра догогора;
# 2 - принудительно использовать только форму;
# 3 - если есть в параметрах догогора кошелёк то его, иначе -  брать из формы (и давать подсказку, что можно вбить намертво)
currency.1.purseMode=1
# специфичные для валюты:
# url до шлюза
currency.1.url=https://bo-demo02.yamoney.ru/onlinegates/maglan.aspx
# код валюты (643 – рубли, 10643 – тестовая валюта (демо-рубли))
currency.1.curcode=10643
# пароль для ключа из хранилища ("пароль" ключа, по нему идентифицируется ключ)
currency.1.GpgPassPhrase=123456
# путь до утилиты gpg
currency.1.GpgFullPath=/usr/bin/gpg
# Адрес доставки реестра успешных операций, проведенных за предыдущие сутки
currency.1.registryMail=onlinegate@yamoney.ru
# уникальный идентификатор Агента (предоставляется Агенту Оператором платежной системы, шесть цифр)
currency.1.Agent_ID=123456
# Юридическое наименование Агента
currency.1.Agent_name=ООО «Предприятие»
# Номер договора
currency.1.Сontract_number=2000.998.001
# Идентификатор ключа (яндекса) для шифрования реестра операций перед отсылкой
currency.1.registryGpgKeyID=BCD3ACEF

currency.2.title=webmoney WMR
currency.2.code=WMR
currency.2.protocol=ru.bitel.bgbilling.modules.buyemoney.server.protocols.wm.WMProtocol
currency.2.pursePid=53
currency.2.chargeType=55
currency.2.chargeCommentTemplate=Покупка ${sumcur} ${cur} за ${sumtotal} (курс ${rateprice}, дата ${date}, транзакция ${id}) на кошелёк ${purse}
currency.2.transactCommentTemplate=${contract} (${contract_comment}), транзакция ${id}, комментарий: ${user_comment}
currency.2.purseMode=1
# Сертификат WebMoneyCA.crt, полный путь
currency.2.WebMoneyCA=/home/dimon/projects/webmoney/WebMoneyCA.crt
# WMID, которым подписывается
currency.2.wmid=323446780013
# Полный путь к копии файла ключей
currency.2.kwm=/home/dimon/projects/webmoney/323446780013.kwm
# Пароль к копии файла ключей
currency.2.kwmpass=123456
# Кошелёк с этого wmid
currency.2.purse=R198105158104

#currency.3.title=webmoney WMZ
#currency.3.code=WMZ
#currency.3.protocol=ru.bitel.bgbilling.modules.buyemoney.server.protocols.wm.WMProtocol

Примечание: ${user_comment} не будет виден в шаблоне комментария расхода (за исключением ситуаций, когда результат был известен сразу после транзакции, а не при выполнении периодичской задачи лишь), а только в шаблоне транзакции.

3. Настройка gpg-подписи для Yandex.Деньги

Нам необходим ключ для подписывания наших запросов. Для работы с PGP используется нативная утилита GnuPG (gpg), установленная в системе, и её хранилище ключей. Вкратце рассмотрим настройку и работу утилиты. Инструкция приведена для версии gpg (GnuPG) 1.4.11 под linux.

Предположим, что работа с gpg только что началась и до этого никаких операций не проводилось. Иначе при необходимости надо скорректировать свои действия, возможно, пропустить некоторые этапы.

Прежде всего нужно сгенерировать свою пару открытый/закрытый ключ:

$gpg --gen-key

При этом выбирается нужный тип ключа (например, для работы Yandex.Money выбирается "(4) RSA (только для подписи)" ); выбирается длина; выбирается срок действия.

Далее формируется UserID (имя, e-mail, комментарий) в таком виде: "dimon (first key) <dimon@***.ru>". Три параметра вводятся по очереди или сразу, зависит от реализации.

Наконец, вводится пароль для доступа к ключу. Предположим, мы ввели "123456". По этому паролю в некоторых реализациях и в некоторых случаях будет идентифицироваться ключ. В вышеприведённой конфигурации этот пароль указывается в параметре GpgPassPhrase для соответствующей валюты.

После некоторых дополнительных указаний сгенерируются (открытый и закрытый) ключи.

Можно посмотреть на ключ:

$ gpg --list-key
/home/dimon/.gnupg/pubring.gpg
------------------------------
pub   2048R/F99D7F2B 2010-11-08
uid                  dimon (first key) <dimon@***.ru>

Аналогично смотрятся секретные ключи:

$ gpg --list-secret-keys
/home/dimon/.gnupg/secring.gpg
------------------------------
sec   2048R/F99D7F2B 2010-11-08
uid                  dimon (first key) <dimon@***.ru>

Чтобы отослать свой ключ получателю (в нашем случае менеджерам Yandex.Деньги) его надо экспортировать в файл. Выгрузим в текстовом (не бинарном) виде:

$gpg --export --armor > mykey.asc

Получится файл mykey.asc с вашим ключом:

-----BEGIN PGP PUBLIC KEY BLOCK-----
Version: GnuPG v1.4.11 (GNU/Linux)

mQENBEzXmH8BCADJE6LkH9i4+Q96OzuvrSnAK9u9xxmp3x05FtGLswUNn6n0Ux7X
eBLGTQn+aT1KG1gc6O8c0l87A1hWk/VIE9ipCIbccY8xa1SWBcjHHtZIxYPG5ToM
q4jWuW7WJzgpZV6TuJYrfzz+iX/SQOfn0gav61ZoNCcLQ+Ypzz075r1Ax/S/Kfin
fiUyjjqDZI1ajfE1jWgXn/nxnWQ7DD5P2FJ4/HBR7HF7EABqo+TLk74hbYISoPWw
pAnYPzVn0tlXlhWI6CgIHx8YC9xhBA5LsmZk1SBKZhviSMCFuGCQnFpXFyX8fmfU
TCfJTFMDnBFAEPRJKeG5G2/Ahe2IrlwoSXB7ABEBAAG0ImRpbW9uIChmaXJzdCBr
ZXkpIDxkaW1vbkBiaXRlbC5ydT6JATgEEwECACIFAkzXmH8CGwMGCwkIBwMCBhUI
AgkKCwQWAgMBAh4BAheAAAoJEE3+EBD5nX8rWdcH/2w/VpmlgYOHAphC9zXsTv09
K4jNaLV6BwG0XqW1Af3Y49tDYpv9zaobtV/yRd0gaZo2rONTXlb4GGpBsbPBWwkg
eYb/z+7AZm0auCEYlc4Fk9J7QN0NvbGccw+I6dRIrykK+VwZUS4+nQB+EIDoR33U
zaT47IPqi1HkYiRpxB3B/4axMiTjfx28gdzX3EICQtMNEDczcPCYsYCB9A2y2XBd
N4OUWanrceEvUeEhPa4rR/sYpvg3JZv44Asm7du3GprYnlFcoeSdmeJ/Bl/au+eU
8gvzDCEVBmUNRyG1cTXgfoJqcFVLULoASwfAYVfJQVRMBP60ecz4wPMxhHvV2Gc=
=Cgdy
-----END PGP PUBLIC KEY BLOCK-----

Дальше нужно импортировать выдаваемые второй стороной ключи. Нужный в данный момент имеет имя "Yandex.Money Payment Gate.asc".

$ gpg --import ./Yandex.Money\ Payment\ Gate.asc
gpg: ключ B0B2F0D8: открытый ключ "Yandex.Money Demo Payment Center (Yandex.Money Demo Payment Center) <demopaymentcenter@yamoney.ru>" импортирован
gpg: Всего обработано: 1
gpg:                  импортировано: 1

Второй ключ - "Yandex.Money Online Registry Key.asc" - тоже пригодится в последующем.

$ gpg --import ./Yandex.Money\ Online\ Registry\ Key.asc
gpg: ключ ACE74CE2: открытый ключ "Yandex.Money Online Registry Key <onreg@yamoney.ru>" импортирован
gpg: Всего обработано: 1
gpg:                  импортировано: 1

Можно убедиться, что теперь открытых ключей стало больше (наш закрытый, конечно, остался один):

$ gpg --list-key
/home/dimon/.gnupg/pubring.gpg
------------------------------
pub   2048R/F99D7F2B 2010-11-08
uid                  dimon (first key) <dimon@***.ru>

pub   1024D/B0B2F0D8 2008-05-29
uid                  Yandex.Money Demo Payment Center (Yandex.Money Demo Payment Center) <demopaymentcenter@yamoney.ru>
sub   2048g/2A9A05C6 2008-05-29

pub   1024D/ACE74CE2 2006-10-05
uid                  Yandex.Money Online Registry Key <onreg@yamoney.ru>
sub   2048g/BCD3ACEF 2006-10-05

Пример того, как это все работает (вывод на экран в бинарном виде).

Подпись файла test.txt:

$ gpg --armor --output - --sign --passphrase 123456 test.txt
-----BEGIN PGP MESSAGE-----
Version: GnuPG v1.4.10 (GNU/Linux)

owEBPgHB/pANAwACAXzF27f83iK8AawOYgR0ZXN0S6h2SXRlc3SJARwEAAECAAYF
AkuodkkACgkQfMXbt/zeIrwE6Qf/bNGgTUytFAuPaInkx49L8DQyUx72Lra9uOin
TCfaRPZJlwjt4wdsF0FYYLuFYoQ25WwfVmdZwTwfvd1qV+drWBJKZx/s8t0WDrnw
0rQL9JainBkojNdmcGfa3UMEAYLQgXezpGwZtQ4iURjVbChH52lR3NFDGjt+fR8p
dVSdjz7owhTldC08ceVSKLDagW+XFYC9OaeWjDvLKN2dsYbeWL1g0VjmzSHHPjFG
XL8J90FpTymL/DZZsnOWUxUmEU7ymZ14NAwtOV9jjyGjYL8bGSDymJEqttXKJWbO
ZlHUbzJG23m2YK1BoW7ojNbAD8ilrIMWyjCa6id+OB29lJXzzA==
=IhW8
-----END PGP MESSAGE-----

Подпись и шифрование для отправки сверки на Яндекс:

$ gpg --armor --output - --encrypt -r BCD3ACEF --sign --passphrase 123456 ./test.txt

В данном случае файл будет зашифрован указанным ключём Яндекса и подписан нашим ключом по умолчанию (он устанавливается командой gpg --default-key), либо первым ключом в секретном хранилище.

Могут возникнуть проблемы:

Недоверие ключу:

gpg: BCD3ACEF: Нет свидетельств того, что данный ключ принадлежит пользователю, указанному в User ID ключа

и запрос всё время доверять или нет. Надо установить уровень доверия ключу:

$ gpg --edit-key BCD3ACEF

И далее вводится "trust" и выбрать "доверять абсолютно", потом "quit".

Также, как вариант, можно использовать --trust-model always или --always-trust, но не нужно.

4. Настройка WebMoney

В данный момент находится в alpha-тестировании.

5. Использование модуля

Настройка модуля не вызывает особых трудностей. Прежде всего есть список всех протоколов валют, настроенных в конфигурации модуля. Для каждой валюты есть набор некоторой информации, читаемой из конфигурации и с удалённого сервера, соответствующего этой валюте (в случае неправильно настроенного модуля это, конечно, не прочитается).

Далее для каждой физической валюты надо настроит её курс. Курс включает в себя цену единицы валюты (в рублях системы) для какого-то определённого промежутка времени. Таким образом, можно настроить определённый курс валюты и её активность на разные числа. Цена единицы определяется как сумма, списываемая со счёта клиента при покупке единицы соответствующей валюты, за счёт этого можно настроить комиссию, как положительную, так и отрицательную.

Имеется список транзакций, как общий, так и для каждого договора.

Для пользователя в web-интерфейсе имеется список его транзакций. Для каждой операции имеется описание подробностей операции - сколько куплено какой валюты и за какую цену. Каждая операция находится в статусе "в обработке", "успешно" или "неуспешно".

Ниже находится форма, которая позволяет произвести покупку палюты. Можно вводить как необходимую сумму валюты, так и конечную сумму затраченных денег. Для каждой валюты будет испольован текущий на сегодня курс. Если курса нет, то валюты в списке не будет. В зависимости от параметра конфигурации purseMode кошелёк для вывода денег будет задан жёстко, или дана возможность его ввода.

Глава 11. Модуль BVCom

1. Назначение модуля

Модуль BVCom предназначен для проведения платежей через платежный шлюз BVCom (Arius) c использованием пластиковых карт. Для проведения платежей вашими клиентами у вас должен быть заключен договор с системой.

2. Настройка модуля

Установите модуль на сервер, обновите клиент. Затем создайте экземпляр модуля. Создайте в редакторе конфигурации модуля новую конфигурацию, скопируйте туда приведённый ниже текст и введите требуемые параметры. После этого сохраните конфигурацию и сделайте её активной.

#===========ОБЩИЕ ПАРАМЕТРЫ========================
#версия протокола системы: 1 - старая, 2 - новая
bvcom.protocol.version=2
#клиент-оператор, заключивший договор с BVCom/Arius. Например: bitel. Также это является логином
bvcom.client=bitel
#формат транзакции. Например: BG00000000
bvcom.trans.format=BG00000000
#тип платежа
bvcom.payment.type=32
#тип расхода
bvcom.charge.type=57
#Комментарий платежа
bvcom.comment=Оплата через BVCom
#url-адрес, куда будет перенаправлен пользователь после оплаты
bvcom.url.result=http://localhost:6080/bgbilling/webexecuter
#===========СТАРЫЙ ПРОТОКОЛ========================
web.menuItem1= Оплата через BVCom
#секретный ключ каждого клиента. Например: secretkey
bvcom.key=]FR{EPz(
#===========НОВЫЙ ПРОТОКОЛ========================
#параметр выдается BVCom
bvcom.endpointid=16
#ключ, выдаваемый системой BVCom
bvcom.merchant.control=4B613C8C-F5C2-4B33-B9D3-8C4D29F8EBC2
#адрес скрипта, к которому будут направлены результаты транзакции
bvcom.callback.url=http://<billing_server>/bgbilling/bvcomexecuter/<mid>
#код валюты. RUR по умолчанию, для некоторых банков нужно использовать RUB
bvcom.currency=RUR
#адрес сервера БВКом
bvcom.server.url=https://sandbox.ariuspay.ru/paynet/api/v2/

Замечания:

  1. Прежде, чем задавать bvcom.payment.type, bvcom.charge.type необходимо создать соответствующие типы платежей и расходов в Справочниках ( Справочники->Другие->Типы платежей, Справочники->Другие->Типы расходов).

  2. Номер транзакции создается следующим образом: берется ID транзакции из таблицы bvcom_transaction_<mid> и соединяется с шаблоном. Например: если шаблон "BG0000", а ID пусть будет 34, тогда номер транзакции, отсылаемый на платежный шлюз BVCom, будет иметь вид: BG0034.

  3. После заключения договора с системой BVCom им нужно передать адрес скрипта на машине биллинга, который ждет результаты от платежной системы. URL скрипта выглядит следующим образом: http://<адрес_машины_биллинга>/bvcomexecuter/<mid>. Например, если у вас биллинг находится по адресу http://billing.example.com/bgbilling/ и модуль BVCom имеет mid=16, то результирующий URL, который нужно дать компании BVCom, выглядит следующим образом: http://billing.example.com/bgbilling/bvcomexecuter/16.

3. Оплата через систему BVCom

Если у клиента подключен экземпляр модуля в дереве договора, то он может осуществлять оплату через платежный шлюз BVCom, используя личный web-интерфейс (пункт меню Оплата через BVCom).

В личном кабинете на странице отражается история платежей, совершенных клиентом:

Ниже таблицы с платежами расположена кнопка Пополнить счет, нажав на которую клиент попадает на страничку, где отображается его текущий баланс, а также форма с запросом суммы платежа.

Щелкнув по кнопке Далее, клиент попадает на страницу подтверждения оплаты. На данном этапе уже сформирован запрос на платежный шлюз и от клиента требуется нажать на кнопку Далее для продолжения оплаты, либо Отмена для отмены платежа.

В случае, если клиент подтверждает оплату, то он перенаправляется на платежный шлюз, где может ввести информацию о своей пластиковой карте.

Правильно заполнив предложенную форму и нажав кнопку OK, платежный шлюз отобразит информацию о результате платежа.

В случае положительного результата платежа биллинговая система начислит клиенту указанную им сумму на счет.

4. Мониторинг платежей

В клиенте билинга есть возможность отслеживать историю платежей по каждому абоненту. Для этого необходимо выбрать модуль BVCom в дереве параметров договора. Здесь присутствует фильтр по статусу платежей (проведенные/непроведенные/возвращенные/все) с указанием периода, когда производилась оплата.

Для просмотра ВСЕХ платежей, проведенных через систему BVCom, существует глобальный монитор в параметрах модуля. В открывшейся вкладке модуля BVCom у Вас есть возможность просмотреть все платежи, совершенные вашими абонентами за указанный временной период. Также можно установить фильтр платежей по группам договоров, по имени договора, по номеру платежа, по статусу.

5. Возврат платежей

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

Задача называется BVCom => Проверка результатов запроса на возврат денежных средств. Периодичность можно выставить раз в час. Параметром задачи является код модуля, который указывается на вкладке Параметры запуска планировщика заданий ( Сервис -> Администрирование -> Планировщик заданий ):

mid=<mid>

Возврат платежа осуществляется только через клиент биллинга, щелкнув правой кнопкой на ПРОВЕДЕННОМ платеже.

Глава 12. Модуль CerberCrypt

1. Назначение модуля

Модуль предназначен для управления системой цифрового вещания. Поддерживаются несколько систем: CerberCrypt ставропольского завода "Сигнал", система условного доступа Irdeto Pisys, система CTI/NordE, система conax (beta-версия). Поддерживается ведение каналов, их пакетирование, обсчёт и автоматическое управление подпиской абонентов средствами биллинга, отсылка сообщений и т.п., в зависимости от используемой системы условного доступа.

Далее в тексте все эти системы обозначены как «система условного доступа», система УД, УД.

2. Настройка модуля

Предполагается, что у вас уже установлена и настроена система условного доступа, произведена настройка каналов и вам известны уникальные коды каналов/пакетов.

#активные статусы договора
contract.status.active.codes=0

#название пункта Web меню
web.menuItem1=Управление подпиской CerberCrypt
web.menuItem2=Виртуальный кинотеатр CerberCrypt
#Проверка наличия каналов на пакете при добавлении новых каналов
#0 - проверки нет
#1 - проверка только при действии Открыть пакеты
#2 - проверка при действии Открыть пакеты и при открытии пакета через веб-статистику
#3 - проверка при действии Открыть пакеты, открытии пакета через веб-статистику и при добавлении пакета через клиент биллинга
cerbercrypt.cardpacket.addcheck=1
#количество выводимых ошибок в периодических процессах
max.periodic.errors=30
#----------------------------------------
#выборочное отключение проверки закрытого периода
#Начисление
#closed.date.disabled.ActionRecalculate=1
#Изменение карты в закрытом периоде
#closed.date.disabled.ActionUpdateUserCard=1
#Изменение карт пакета в закрытом периоде
#closed.date.disabled.ActionUpdateCardPacket=1
#----------------------------------------

2.1. CerberCrypt

Для системы CerberCrypt указажите адрес, порт и логин с паролем для обращения к серверу CerberCrypt:

sa=ru.bitel.bgbilling.modules.cerbercrypt.server.CerbercryptServiceActivator
server.0.host=192.168.168.10
server.0.port=8100
server.0.login=admin
server.0.pswd=xxxxx

Поддерживается всё железо аналогичное: CerberCrypt, DVCrypt, Teleview и прочие, в том числе настраивающиеся согласно документации CerberCrypt. Обратите внимание на права пользователя CerberCrypt, под которым происходит авторизация на удалённом сервере CerberCrypt (в примере выше — admin), ему нужно дать необходимые права для того, чтобы использовать все функции протокола (установление, чтение подписки и прочие).

2.2. Pisys Irdeto

Для Pisys Irdeto укажите адрес, порт и код оператора:

sa=ru.bitel.bgbilling.modules.cerbercrypt.server.PisysServiceActivator
server.0.host=192.168.168.10
server.0.port=80
server.0.operatorTag=
server.0.nationality=RUS
#регион (MO, BA, SA)
server.0.regionTag=

2.3. NordE/CTI

Для системы NordE/CTI примерная конфигурация такова:

sa=ru.bitel.bgbilling.modules.cerbercrypt.server.NordE2ServiceActivator

server.0.host=localhost
server.0.port=7000
server.0.timeout=5000

server.0.smsNumber=1
server.0.providerId=1
server.0.charset=ISO8859-1
server.0.providerName=Test Provider

server.0.emailEnable=1
server.0.emailDurationTime=1
server.0.emailInterval=1
server.0.emailTitle=Заголовок письма
server.0.emailFrom=Письмо от

server.0.osdEnable=1
server.0.osdTimes=1
server.0.osdInterval=1
server.0.osdTitle=Заголовок сообщения
server.0.osdFrom=Сообщение от

# период в днях, на сколько каждый раз продлевается активация (при подписке пакета на открытый период).
# для активаторов, которые (опционально) продлеваются постепенно: NordE2, .
# чтобы продлять на "бесконечно", ставится либо 100500 дней, либо параметр вообще не прописывается (по дефолту возьмётся опять же какое-то большое кол-во дней).
# если стоит небесконечный период, то обязательно запускать задачу "Постепенное продление подписки", которая будет сдвигать период по исходу этого кол-ва дней.
period.gradually.subscription=30

В данном случае режим работы с пакетами: заводим в биллинге пакеты и управляем пакетами (из удалённой системы), каналы настраиваем извне. Т.е. каналы не синхронизируются из биллинга. Параметры типа "emailEnable" или "charset" больше относятся к оборудованию и, возможно, будет удобнее помимо размещения их в конфигурации модуля разместить их в конфигурации устройств (см. ниже), которые затем привяжутся к картам пользователей (в карточке договора). Также здесь удобно использование возможности "автопродление подписки" (см. ниже и см. настройку в днях кол-ва дней продления активации).

Вкладка «каналы» остаётся на месте, всеми игнорируется, при обмене с сервером, учёте и т. д. не используется. Обмен идёт только через пакеты, для этого используются коды пакетов, которые задаются на соответствующей вкладке.

Номера пакета — вводится вручную при добавлении или редактировании пакета в поле «Номер пакета (код)».

Пример конфигурации оборудования, с которым тестировался данный протокол: сремблеры двух компаний родные Compunicate, и компании Gospell, любые современные железки от них совместимы с CAS. Oracle можно использовать любой. Версии модулей софта Conditional Access System : CAS Encryption Control System V2.02, CAS ECMG V2.545, CAS EMMG V2.5.4, CA Manager V2.0.2, SMS Console V2.00 2007.09. Для обмена данными между системами биллига различных разработчиков служит ПО SMS Console, версия консоли зависит от версии системы кодирования.

Для OSD сообщений задаётся количество повторов (сколько раз пробежит строчка) и интервал в минутах (хотя в описании протокола сказано про секунды). В данный момент реализовано только из конфигурации.

2.4. Conax

Система conax (beta-версия) требует подобную конфигурацию:

sa=ru.bitel.bgbilling.modules.cerbercrypt.server.ConaxServiceActivator
# Параметры сервера (т.е. ftp-аккаунт)
server.0.host=localhost
server.0.port=21
# Параметры аккаунта логин/пароль
server.0.username=anonymous
server.0.password=
# Корневой каталог относительно текущего-каталога-сразу-после-входа,
# относительно него уже ищутся каталоги autreq/req, autreq/ok, autreq/err
# (они тоже должны существовать)
# по умолчанию "." (точка, текущий каталог, т.е. никуда не делаем переход)
server.0.pwdroot=pub/conax

2.5. Gospell

Система Gospell. Режим работы — с пакетами. Везде подразумевается один сервер; коннект берётся везде нулевой.

# активатор Gospell
sa=ru.bitel.bgbilling.modules.cerbercrypt.server.GospellServiceActivator

# настройки соединения
server.0.host=localhost
server.0.port=2888
server.0.timeout=5000

# заголовок email
server.0.emailTitle=email

# параметры osd (см. протокол)
server.0.osdShowTimeLength=30
server.0.osdShowTimes=0
server.0.osdPriority=0
# expired time, в секундах (1 день = 24*60*60)
server.0.osdExpiredTimeSecond=86400

2.6. Тестовый

Тестовый активатор, просто выводит всё в лог с уровнем DEBUG:

sa=ru.bitel.bgbilling.modules.cerbercrypt.server.TestServiceActivator

2.7. Настройка каналов/пакетов

Далее производится заведение каналов в биллинге, к каждому каналу должен быть привязан код канала системы УД.

Пакет - это логическая единица, включающая в себя несколько каналов. Пакеты используются для более простого управления подпиской абонентов. Все пакеты необходимо завести в справочнике пакетов с указанием привязанных к ним каналов.

К каждому пакету должна быть указана услуга, на которую будет начислена наработка за пользование этим пакетом. Если необходима возможность включения/выключение пакета через Web, то следует установить флаги "Добавление через WEB" и "Закрытие через WEB". Если пакет должен быть всегда доступен пользователям ("социальный пакет"), то необходимо установить галочку "Не блокируемый". Такой пакет не будет блокироваться задачей "Блокировка CerberCrypt".

Также каждому пакету должен быть присвоен код, которым он нумеруется в системе УД, если используемый протокол предполагает пакетное управление.

Все используемые карты условного доступа должны быть загружены в модуль. Загрузка происходит в менеджере карт из файла формата:

<номер карты>\t<пароль карты>

Пароль карты - уникальная последовательность для активации карты через Интернет, что позволяет провайдеру организовывать продажу карт с приемниками вне офиса.

Для загрузки карт в систему следует нажать кнопку Загрузить и выбрать файл.

После загрузки карта должна быть передана дилеру. Дилер должен быть заведён на вкладке Дилеры. Для осуществления передачи в менеджере карт выбирается дилер и нажимается кнопка Передать дил.

Формат перечисления карт приведён под окошком. Формат "n+k" означает k карт начиная с номера n. Отбор карты у дилера производится аналогично. Дилеры представляют из себя как реальных агентов по продаже карт, так и фиктивные контейнеры для учёта повреждённых карт, утерянных и т.п.

Также менеджер карт позволяет производить простейший учёт карт. Так, можно определить количество свободных карт, либо количество карт, выданных определённому дилеру.

3. Настройка клиентов

Каждому клиенту, использующему услуги модуля должны быть сопоставлены карты.

Карта должна быть заведена в системе, передана дилеру и не присутствовать у другого договора. В случае если необходимо предоставить клиенту возможность изменения подписки через Web необходимо установить дату, с которой эта подписка возможна. При включении этой возможности клиенту будет разрешено включать только те пакеты, которые разрешены к смене через Web.

Номер карты можно не вводить вручную, а выбирать из списка (с быстрым поиском при вводе). Карты и так уже вбиты в менеджере карт и назначаться могут только те карты, которые уже зарегистрированы в системе.

Также реализовать выбор «Базовой карты». При выборе оной, текущая карта становится дочерней. Информация о базовой карте наглядно отображается в табличке на вкладке. Информация о базовой карте отображается, как отдельная колонка. Для каждой карты приписывается её родитель, если есть. А для родителей - количество дочерних. Все они в порядке как есть (будто связей нету).

Ещё параметр «Тип оборудования». Выбирается из справочника. Можно, например, использовать для определения кодировки для отправки сообщений, а также для возможности отправки по Mail и OSD и т.п. См. "Типы оборудования" ниже.

На вкладке Пакеты каждой карте сопоставляются пакеты с определённым периодом.

Пакеты можно добавлять и закрывать как по одному, так и группами, используя кнопки Открыть пакеты и Закрыть пакеты (выделены красным). В течение периода жизни каждый пакет на карте может быть заблокирован (в случае окончания средств), приостановлен (по просьбе клиента) и активен. Заблокированные пакеты автоматически разблокируются при пополнении договора.

С версии 4.3 возможно добавить проверку на наличие в добавляемом пакете канала, который уже есть в открытых пакетах в карте. Для этого в конфигурации модуля указать:

cerbercrypt.cardpacket.addcheck=1
#значения:
#0 - проверки нет
#1 - проверка только при действии Открыть пакеты
#2 - проверка при действии Открыть пакеты и при открытии пакета через веб-статистику
#3 - проверка при действии Открыть пакеты, открытии пакета через веб-статистику
# и при добавлении пакета через клиента биллинга

Возможно контролировать копии карт. Копии карт реализуют логику наличия нескольких одинаковых карт у клиента. Контроль за их количеством позволяет правильно тарифицировать наличие нескольких карт. Если у клиента есть карта и копия, то они будут тарифицировать как 2 карты и нароботка будет удваиваться. На вкладке "Копии карт" отражаются карты в выпадающем списке и копии к ним в таблице. Для добаления, редактирования и удаления используются стандартные кнопки. Для добавления новой копии, необходимо выбрать основную карту в выпадающем списке и нажать кнопку Добавить. Срок действия копии ограничен сроком действия основной карты. Тарифицируются копии с даты начала по дату окончания действия включительно.

4. Дополнительные возможности для Irdeto Pisys, CTI/NordE итд

В менеджере карт, а также на закладке Карточки в договоре в параметрах модуля доступно контекстное меню. Irdeto Pisys позволяет отправлять сообщения/письма, устанавливать/сбрасывать PIN(родительский) код,

Отправить сообщение - отправка сообщения на клиентский STB (SetTopBox), привязанный к выбранной (первой из выбранных) карточке. Отправить сообщение найденным - отправка сообщения на STB, привязанным к карточкам, найденным по указанному фильтру, т.е. карточкам с первой по последнюю страницу. Отправить сообщение всем - отправка сообщений всем карточкам.

Отправить письмо - аналогично отправке сообщения.

Установить/сбросить PIN код - установка/сброс на по умолчанию PIN (родительского) кода.

Загрузка прошивки - указание STB, привязанной к выбранной карточке, что необходимо обновить программное обеспечение.

Привязать/отвязать карту к/от STB - привязка/отвязка карты к/от SetTopBox.

Автонастройка STB - автонастройка SetTopBox, привязанной к карте c IRD.

Активировать карту - повторная активация карты.

Запрос подписки — отображение актуальной подписки с сервера.

Все дополнительные возможности зависят от их поддержки протоколом и возможности их использования при этом в биллинге.

Имеется возможность насильно запустить по карте синхронизацию, при этом ставится в очередь синхронизатор по этой карте и всем зависимым от неё.

Имеется возможность изменения PIN-кода карты из интерфейса модуля CerberCrypt-Менеджер карт (правой кнопкой) и возможность изменения PIN-кода карты из интерфейса модуля CerberCrypt в договоре (правой кнопкой). Фактически это тот же PIN-код, который вводится при создании договора из карты пользователем. Возможность сменить PIN-код дана для возможности использования его как пароля доступа к карте в некоторых системах. Также этот PIN-код можно видеть через интерфейс формирования печатной формы карты регистрации. Есть возможность изменения PIN-кода карты через интерфейс Web-статистики клиента (с указаннием старого кода).

При назначении карты договору возможно автоматически отправлять на неё команду открытия карты (команда поддерживается/требуется, например, в протоколе CTI/NordE). При снятии карты с договора автоматически отправлять команду отмены регистрации карты. Делается это через скрипты. См. события, возникающие при добавлении (из клиента биллинга) карты на договор и при удалении карты с договора. В скриптах, повешенных на эти события? возможно, например, посылать команды авторизации и отмены авторизации. Активация/деактивация карты также доступна через контекстное меню.

5. Типы оборудования

Существует справочник «Типы оборудования» для указания типов оборудовния, поддерживаемых кодировок (при формировании посылки SMS/OSD/MAIL) и т.д. Это справочник внутри модуля на отдельной вкладке в админке. Справочник: название оборудования — конфигурация — примечание. Где в конфигурации в каком-то нативном для каждого активатора виде расположена конфигурация, которая понятна только этому активатору. Например, для протокола CTI/NordE это будет что-то типа: Поле название: железка1. Поле примечание: какая-то железка. Поле конфигурация: osd=1 email=0 encode=utf-8. Потом в каждой вкладке в карточке можно привязать к каждой карточке устройство из комбобокса. При работе с устройством эта конфигурация передаётся в активатор и активатор будет его учитывать согласно карте. Т.е. возможно просто перекрывать поля из конфигурации модуля для каждой конкретной карты пользователя.

6. «Мультирум»

Основная настройка в конфигурации модуля:

# Максимальное кол-во мультирумных зависимых карт ("копий карт") от другой карты на договоре (по умолчанию 0, т.е. возможность выключена!)
multiroom.max.slavecards=2

При редактировании карты в редакторе список:

1) только основные;

2) исключая саму редактируемую карту;

3) исключая все основные, которые уже имеют максимально разрешённое кол-во копий.

Все действия по удалению базовой карты (мультирум) всё происходит в периодическом синхронайзере во вкладках в договоре "пакеты", "виртуальный кинозал" и "копии карт" рисуются только основные карты.

Мультирум в данной реализации работает как полностью копируемая подписка одной карты на другую. Тарификации мультирумных карт в данный момент нет.

7. Настройка задач планировщика

Для корректной работы модуля должны быть настроены следующие задачи планировщика. Рекомендуемое время запуска задач:

Установка договоров картам CerberCrypt - 0 часов 0 минут
Установка статусов пакетам карт CerberCrypt - 0 часов 0 минут
Начисление CerberCrypt - 0 часов 40 минут
Блокировка Cerber Crypt - 1 час 50 минут
Синхронизация CerberCrypt - 2 часа 0 минут

7.1. Сопоставление договоров картам

В менеджере задач каждой загруженной карте указывается сопоставленный в настоящий момент договор. В случае, если карта заносится на договор текущей датой, то привязка договора к карте обновляется сразу, иначе это делает задача планировщика Установка договоров картам CerberCrypt. Задача должна быть установлена на 0 часов 0 минут каждого дня.

В конфигурации задачи указывается код модуля.

mid=<код модуля>

7.2. Установка актуальных статусов пакетов в картах договоров

Задача Установка статусов пакетам карт CerberCrypt устанавливает картам договора актуальные статусы, основываясь на заданиях по смене статуса. Должна запускаться в 0 часов 0 минут каждых суток, в параметрах указывается код экземпляра модуля. Данная задача необходима для случаев, когда статусы пакетов карты изменяются будущим числом.

mid=<код модуля>

7.3. Начисление CerberCrypt

Осуществляется задачей планировщика Начисление CerberCrypt. Рекомендуемая частота запуска - один раз в сутки. Целесообразно запускать задачу в первом часе каждых суток (например, в 0 часов 30 минут каждые сутки), тарификация производится включая текущие сутки с учётом актуальных статусов пакетов, установленных задачей Установка статусов пакетам карт CerberCrypt.

В конфигурации задачи указывается код модуля.

mid=<код модуля>

7.4. Блокировка должников

Осуществляется задачей Блокировка Cerber Crypt. Минимальная частота запуска - один раз в сутки после задачи начисления (например 2 часа). Если в договоре присутствуют иные виды списаний кроме начисления за использование цифрового ТВ, то задачу можно установить несколько раз в сутки.

В конфигурации задачи указывается код модуля. При блокировке пакеты всех договоров, баланс которых менее лимита, переводятся в статус заблокировано. Параметр forgive.hours определяет сколько часов от суток "прощать" клиенту. Под "прощением" понимается, что если задача запускается ранее указанного часа суток, то блокировка производится мгновенно и прошедшие часы достаются клиенту даром. Если задача запускается после этого часа, до добавляется задание на блокировку с 0 часов последующих суток, клиент может смотреть канал до конца суток.

"Прощение" определённого числа часов предотвращает недовольство клиентов в связи с отключением каналов в 0 часов, как это должно следовать из требования корректности начислений (при снятии денег посуточно блокировка должна происходить на границе суток).

mid=<код модуля>
# сколько часов от суток "прощать" при блокировке
forgive.hours=2

В данном примере если блокировка производится после 2х часов ночи, статус заблокировано устанавливается со следующего дня, позволяя абоненту доработать день.

Если у пакета установлен параметр "Не блокируемый", то в этой задаче он обрабатываться не будет.

7.5. Обновление подписок

Осуществляется задачей планировщика Синхронизация CerberCrypt. Для всех активных в текущий день карт открываются указанные на текущий момент пакеты со статусом активен. Данная задача производит синхронизацию подписок по результатам работ задач Установка статусов пакетам карт CerberCrypt и Блокировка Cerber Crypt. Обновление подписок при их смене оператором, либо клиентом через Web интерфейс происходит мгновенно.

В параметрах задачи указывается код модуля и адрес E-Mail на который высылаются сообщения о недоступности сервера CerberCrypt.

mid=<код модуля>
error.mail=bill@bill.ru
#через запятую можно указать номера карт, подписку для которых обновлять не следует
#ignore.cards=
#указываются группы договоров, подписку на которых обновлять не следует
#ignore.contract.groups=

7.6. Постепенное продление подписок

Специфика некоторых систем (CTI/NordE, conax и т.д.) такова, что при указании подписки они требуют период активации, в отличие от протокола CerberCrypt, например, где подписка ставится/снимается сиюминутная. В данном случае существует примерно такое стандартное поведение:

* открываем пакет с закрытой датой закрытия — так и отсылаем;

* открываем пакет с бесконечностью — ставим большой правый период.

Встаёт задача: как-то решить недостаток от продления пакета в бесконечность и последующим отключением пользователем самого себя от системы с целью пользоваться картой вечно. Сократить подобное пользование до разумного периода. Т.е. в том числе это защита от "хитрых клиентов".

Как написано в конфигурации для активатора CTI/NordE при активации на бесконечный срок можно сделать период активации, например, 30 дней от начала периода, после, если есть деньги, перепосылать активацию (т.е. каждый день, выходит, ибо карты в разные дни активируются).

Это делается через задачу планировщика Постепенное продление подписок пакетов». Приэтом в БД создается отдельная таблица «продление пакетов/каналов», поля: entityId — идентификатор картпакета, date — дата последнего продления «сущности». Таблица не критичная, её содержимое можно удалить, тогда просто считается, что последний раз для закрытых периодов картпакетов уже было отослано, а для открытых было отослано в начале открытия на месяц, так что при следующем запуске этой задачи все они снова продлятся. В любом случае всё продлится и заново начнётся отсчёт при любом редактировании картпакета.

Сам алгоритм имеет такую логику: запускается раз в сутки, перебирает все картпакеты, активные в текущий момент. Активные картпакеты могут быть:

а) либо с закрытым периодом, тогда ничего не делаем, ибо полагаем, что уже было всё отослано один раз;

б) либо с открытым, тогда берётся для каждого картпакета из указанной таблички одна дата — дата последнего успешного продления (точнее, до какого числа РЕАЛЬНО было продлено).

Если истекает эта дата (а системный открыт), тогда он заново отсылает команду с датой начала из картпакета (т.е. дата начала всегда одинакова будет, а конец каждый месяц отодвигаться) и датой конца из этой таблички+месяц . После этого новая реальная дата снова записыватся в БД и через месяц снова будет использоваться.

Период (например, как выше названо «месяц») настраивается в задаче самой конфигурации модуля (т.е. в конфигурации данного активатора).

period.gradually.subscription=30

Если в конфигурации указан небесконечный период, то это обязует использовать эту задачу для периодического продления подписки. Этот период используется как в самом модуле (для информации о том, на сколько конкретно продлить при открытии на бесконечный период), так и в этой задаче для информации о том, на сколько сделать последующее продление.

Пользователь открывает пакет в биллинге, указывает дату начала активации и конца активации: на карту шлются эти периоды, в таблице реальный период и системный совпадают.

Пользователь открывает пакет в биллинге, указывает только дату начала активации пакета: на карту шлётся период ДАТА_НАЧАЛА — ДАТА_КОНЦА, где ДАТА_КОНЦА = ДАТА_НАЧАЛА + 30 дней; в таблицу записывается реальный период и системный (реальный — ДАТА_НАЧАЛА — ДАТА_КОНЦА, а системный ДАТА_НАЧАЛА — (открытая_дата))

Пользователь меняет период активации пакета в биллинге, даты активации перепосылаются и перезаписываются в базу с учетом вышестоящих двух пунктов.

7.7. Контроль синхронизации

Имеется специальная задача контроля синхронизации, которая отвечает за корректную отправку синхронизаций по картам. То есть, если в момент синхронизаций сервер УД был недоступен, то подписка уйдёт только в лучшем случае при следующем изменении карты или на границе суток, когда запустится задача общей синхронизации (если она будет успешна). Задача контроля синхронизации следит за картами с флагом "требует синхронизации" и при наличии карт с ним ставит синхронизатор по ним снова в очередь. Задача необязательна, период настраивается также по желанию нужной оперативности при возможных сбоях сервера УД.

У каждой карты пользователя для этого есть флажок "требует синхронизации". При любом изменении карты он ставится, т.е. это значит "надо синхронизовать", после успешной синхронизации (в синхронизаторе) оно сбрасывается и это значит "карту уже не надо синхронизовать", т.е. "подписка актуальна". Это же поле выводится в табличке для карт пользователя (см. выше).

При нормальной работе эта задача будет просто проверять, что ошибок синхронизации нет (отсутствуют "грязные" несинхронизованные карты) и завершаться. Использовать с осторожностью в плане периодов. Если система подразумевает таймауты обращения и синхронизаторы не просто завершаются с ошибкой при ошибке доступа, а висят и ждут, то при использовании этой задачи их может скопиться слишком много в запущенном состоянии.

8. Настройка тарифных планов

В тарифном плане должны быть определены цены за каждый пакет в день, либо месяц. Также дополнительно могут быть определены скидки в зависимости от числа пакетов, на которые подписан пользователь. Логика поиска тарифа соответствует Алгоритму 1.

Также возможен формат дерева следующего вида:

Модуль предоставляет возможность выставления скидки в зависимости от количества пакетов, при этом можно указать пакеты, не участвующие в расчёте скидки. Т.е. они не учитываются при определении количества пакетов, в зависимости от которого выдаётся скидка и на них не применяется скидка.

Есть скидка по количеству копий карт, данная скидка применяется после начисления всех скидок по пакетам.

9. Возможности Web-интерфейса модуля

Через Web интерфейс пользователю предоставляется текущая подписка его карт. При разрешении администратором пользователь может устанавливать задания на смену подписки с определённой даты.

С помощью скриптов поведения можно формировать вид и поведение смены подписки через web. Можно формировать (при желании) списки дат открытия и закрытия, а также обрабатывать события "перед открытием" и "перед закрытием".

Итак, для смены подписки через web действуют следующие события:

1) Получение списка пакетов, которые можно открыть через Web;

2) Получение списка пакетов, которые можно закрыть через Web;

3) Перед открытием/закрытием пакета через Web. С возможностью передать ошибку и прервать изменение подписки;

4) Подписка изменена.

События и скрипты для них аналогичны действиям при "смене тарифного плана через веб". Например, можно прервать смену, при условии малого баланса.

// Если у абонента баланс ниже какой-то суммы, нужно прерывать выполнение события
if( balance.compareTo( changeCost ) < 0 )
{
  // установка флага обработанности скриптом прервет стандартную смену подписки
  event.setProcessed( true );
  event.setError( "Недостаточно средств" ); 
  return;
}

Закрытые карты отображаются в Web для истории, но сделать с ними ничего нельзя. По старым подпискам пользователь может посмотреть историю пакетов как для активных, так и для закрытых карт.

10. Создание договоров пользователем через Web

Модуль поддерживает создание договоров самим пользователем через специальную страницу. Таким образом возможно распространение карт и приемников через агентскую сеть.

URL страницы активации:

http://<адрес сервера биллинга>:8080/bgbilling/pubexecuter?action=CreateContract&module=cerbercrypt&mid=<код модуля>

Шаблон страницы - файл cerbercrypt_create_contract.xsl - в нем необходимо подправить параметр формы mid на правильный код модуля.

Дополнительно необходимо указать в конфигурации модуля:

#опции активации карты
#код шаблона договора
web.create.pattern=<код шаблона>
#через сколько дней от активации можно менять подписку, если пользователь выразил такое желание
web.create.subscr.offset=<количество дней>
#код параметра Адрес
web.create.address.param=<код параметра>
#код параметра ФИО
web.create.fio.param=<код параметра>
#шаблон создаваемого договора
web.create.name.pattern=ЦК#######
#какие пакеты на сколько дней открыть код пакета - количество дней, 0 - неограниченно
web.create.packet.<код пакета 1>=<кол-во дней>
web.create.packet.<код пакета 2>=<кол-во дней>

11. Виртуальный кинозал

Виртуальный кинозал - это тип пакета, который может быть активирован на сутки. При активации с Web-статистики - с текущего момента времени, при активации с клиента биллинга - либо с текущего момента, либо с момента в будущем. Если кинозал активирован текущим числом, то деньги снимаются со счета в момент активации, иначе - при тарификации в дату активации.

В модуле должна быть дополнительно создана услуга "Виртуальный кинозал". Активация кинозала через Web-интерфейс доступна договору только при наличии в нем данной услуги. Код услуги указывается в конфигурации модуля следующим образом:

#код услуги, кому показывать услугу виртуальных кинотеатров на статистике
cerbercrypt.virtual_cinema.serviceId=<sid>

В пакете необходимо указать, что это Виртуальный кинозал, а также включить подписку через Web, если нужно дать возможность клиенту самому активировать кинозал через Web-статистику.

При активации кинозала через клиент биллинга можно указать дату и час активации, если час активации пуст, а дата текущая, то кинозал активируется с текущей минуты, если дата активации в будущем, то активируется с 0 часов. В клиенте отображаются кинозалы, активные на указанную дату.

При активации с Web-статистики сначала проверяется наличие уже активированного в данный момент времени такого же кинозала, период карточки и наличие средств на счёте для активации.

Также через Web-статистику возможно удаление кинозалов, активированных будущим числом.

12. Лог синхронизаций

Имеется возможность ввести низкоуровневый лог синхронизаций с удалённым сервером, где в дополнение к полям: юзер_карта, время, общий результат, пишется произвольной строкой некоторая полезная информация. Конфигурация модуля:

# Логгирование операций обмена с сервером. По умолчанию выключено.
# Если одного хотя бы из двух параметров нет - выключено.
# Эти настройки нельзя перекрыть в конфигурации устройства.
# Промежутки карт, которые надо записывать в лог:
logging.card.range=1-10,58
# Команды, которые надо записывать в лог, полный список:
# create, modify, cancel, sendMessage, parentalPin, downloadCode, marrySmartcard,
# tune, patchSmartCard, recvrSectDtcode, activate, deactivate, getsubscribeinfo
logging.commands=create,modify,cancel

Лог синхронизаций видится из общей вкладки настройки модуля. При клике на комментарий его можно развернуть. Для логов ведётся периодическая таблица в БД.

Например, для CerberCrypt помимо битовой маски выводятся также номера каналов, которые были отправлены.

При нажати на карту пользователя в договоре можно из всплывающего меню выбрать "Лог соединений по карте" и автоматически открыть модуль с логом соединений, уже отфильтрованым по номеру карты.

Глава 13. Модуль DBA

1. Назначение модуля

Модуль предназначен для выявления старых таблиц в базе данных по заданной конфигурации и генерации скриптов их резервного копирования и удаления из БД.

Замечание

На данный момент модуль не предназначен для создания актуальных бакапов системы, только для очистки старых данных.

2. Установка и настройка модуля

Модуль устанавливается с помощью утилиты bg_installer, после чего создаётся его экземпляр. На вкладке Настройка модуля необходимо выбрать какие таблицы в течении какого срока хранить и нужно ли резервное копирование при их удалении.

3. Использование модуля

После произведённой настройки по времени жизни таблиц на вкладке Скрипт очистки БД можно сгенерировать BASH или Batch файл для резервного копирования и очистки БД.

Имя БД сервер биллинга подставляет из data.properties.

В первой части скрипт сохраняет все требуемые таблицы с помощью утилиты mysqldump. Если какая-то из таблиц не будет сохранена успешно, скрипт прерывает свою работу. Далее при успешном резервном копировании удаляются все требуемые таблицы из БД.

Полученный скрипт можно перенести в файл копированием через буфер обмена, либо использованием кнопки Сохранить, выбрав предварительно файл в поле ввода файла внизу окна.

Внимание

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

Глава 14. Модуль DialUp

1. Назначение модуля

Модуль DialUp предназначен для подсчёта времени и трафика клиентов, работающих по выделенным телефонным линиям,либо через VPN-туннели. Обсчёт трафика возможен на основании данных из RADIUS пакетов (суммарный трафик), либо NetFlow потока (трафик может быть разбит по категориям).

Модуль может производить лимитирование трафика и времени, ограничивать клиентов по телефонам доступа, времени доступа, динамически раздавать IP-адреса из пулов, либо устанавливать их жёстко. Поддерживается принудительный разрыв соединения по достижению нуля на счету, либо наступлению какого-либо иного ограничения, обсчёт соединений производится в "горячем" режиме.

В общем случае модуль DialUp способен обсчитывать любое коммутируемое соединение, единственным условием является поддержка оборудованием протокола RADIUS - стандартного протокола аунтификации и аккаунта, поддерживаемого большинством производителей.

Замечание

В настоящее время для данного модуля разработана более современная замена - модуль Inet. Модуль DialUp оставлен для совместимости и постепенно будет удалён.

2. Базовые понятия и алгоритм работы модуля

Структура взаимодействия основных частей модуля DialUp изображена на рисунке.

NAS (Network Access Server) - сервер, через который происходит выход клиента в интернет.

В роли NAS может выступать как специализированное оборудование (Cisco, Huawey), так и обычные компьютеры с модемами, либо с программой поддержки VPN.

Основное назначение NAS - осуществлять доступ пользователей к внешней сети, при этом может происходить туннелирование трафика пользователя (VPN), преобразование протокола канального уровня (PPP -> Ethernet) и другие преобразования.

NAS посылает на RADIUS-сервер два типа запросов: авторизационные (запросы с просьбой установки соединения, содержащие логин и пароль) и запросы аккаунта (уведомительные, содержат информацию о начале - Start - или окончании - Stop - соединения, а также о протекании хода соединения - Update).

Базовые сведения о протоколе RADIUS и конфигурировании атрибутов.

Протокол RADIUS основан на UDP, представляет из себя пакет определённого типа с набором атрибутов. Рассмотрим ход типового соединения по логу RADIUS запросов (radius.log):

INFO   17.01.2008 05:37:49   AUTH:
Type=AUTHENTICATION_REQUEST
Attributes:
        User-Name=1579
        NAS-Identifier=drs1.igs.ufanet.ru
        CHAP-Password=^ï.Â.ÆÉ  .î麪
«Ó^
        NAS-IP-Address=89.189.150.67
        NAS-Port=1
        Service-Type=2
        Framed-Protocol=1
        Calling-Station-Id=10.47.33.2
        NAS-Port-Type=5
        CHAP-Challenge=»^hÃãs&{{2Êi ñÓÕ½åH°vÛÝc^bô..é`¬¯¸o.+.^§


INFO   17.01.2008 05:37:49   RESPONSE:
Type=AUTHENTICATION_ACCEPT
Process time:113
Attributes:
        Service-Type=2
        Framed-Protocol=1
        Framed-IP-Address=89.189.151.3
        mpd-limit=out#1=all shape 128000 pass
        mpd-limit=in#1=all rate-limit 10000000 pass
        mpd-limit=in#1=all rate-limit 10000000 pass


INFO   17.01.2008 05:37:49   ACCOUNT:
Type=ACCOUNTING_REQUEST
Attributes:
        User-Name=1579
        NAS-Identifier=drs1.igs.ufanet.ru
        NAS-IP-Address=89.189.150.67
        NAS-Port=1
        Service-Type=2
        Framed-Protocol=1
        Framed-IP-Address=89.189.151.3
        Acct-Status-Type=1
        Acct-Session-Id=530269-p0001
        Acct-Authentic=1
        Acct-Link-Count=1
        Acct-Multi-Session-Id=530269-p0001
        NAS-Port-Type=5
        Calling-Station-Id=10.47.33.2

INFO   17.01.2008 05:37:49   RESPONSE:
Type=ACCOUNTING_RESPONSE
Attributes:

INFO   17.01.2008 05:47:49   ACCOUNT:
Type=ACCOUNTING_REQUEST
Attributes:
        User-Name=1579
        NAS-Identifier=drs1.igs.ufanet.ru
        NAS-IP-Address=89.189.150.67
        NAS-Port=1
        Service-Type=2
        Framed-Protocol=1
        Acct-Input-Octets=1250
        Framed-IP-Address=89.189.151.3
        Acct-Output-Octets=1327
        Acct-Status-Type=3
        Acct-Session-Time=600
        Acct-Input-Packets=56
        Acct-Session-Id=530269-p0001
        Acct-Authentic=1
        Acct-Link-Count=1
        Acct-Multi-Session-Id=530269-p0001
        Acct-Output-Packets=56
        Acct-Output-Gigawords=0
        Acct-Input-Gigawords=0
        NAS-Port-Type=5
        Calling-Station-Id=10.47.33.2

INFO   17.01.2008 05:47:49   RESPONSE:
Type=ACCOUNTING_RESPONSE
Attributes:
...
INFO   17.01.2008 18:22:16   ACCOUNT:
Type=ACCOUNTING_REQUEST
Attributes:
        User-Name=1579
        NAS-Identifier=drs1.igs.ufanet.ru
        NAS-IP-Address=89.189.150.67
        NAS-Port=1
        Service-Type=2
        Framed-Protocol=1
        Acct-Input-Octets=59455380
        Framed-IP-Address=89.189.151.194
        Acct-Output-Octets=75469553
        Acct-Status-Type=2
        Acct-Session-Time=39570
        Acct-Input-Packets=159904
        Acct-Session-Id=536566-p0001
        Acct-Authentic=1
        Acct-Link-Count=1
        Acct-Multi-Session-Id=536566-p0001
        Acct-Terminate-Cause=6
        Acct-Output-Packets=140465
        Acct-Output-Gigawords=0
        Acct-Input-Gigawords=0
        NAS-Port-Type=5
        Calling-Station-Id=10.47.33.2

INFO   17.01.2008 18:22:16   RESPONSE:
Type=ACCOUNTING_RESPONSE
Attributes:

Каждый пакет содержит информацию о NASе (NAS-Identifier и/или NAS-IP-Address), на основании которой RADIUS-сервер сопоставляет пришедший пакет NASу в модуле. При сопоставлении сначала производится поиск NASа с названием, идентичным атрибуту NAS-Identifier пакета, затем, если результат отрицательный, идёт поиск NASа c IP-адресом, равным NAS-IP-Address. Если пришедшему пакету NAS не сопоставлен в radius.log, выводится ошибка NAS not found for Packet!!!.

Обмен сообщениями с каждым NASом шифруется определённым кодовым словом - секретом. Секрет должен совпадать для NASа в биллинге и для конфигурации самого NASа. При несовпадении секретов проверка пароля будет все время выдавать неверный результат, т.к. секрет используется при шифровании пароля.

Идентификатором соединения в пределах NASа для RADIUS-сервера выступает атрибут NAS-Port. Обратите внимание, что он идентичен для всех пакетов в пределах сессии. NAS должен контролировать, чтобы в один момент времени одинаковый NAS-Port не проставлялся в RADIUS пакетах, относящихся к разным сессиям.

Далее рассмотрим попакетно обмен данными между NASом и RADIUS-сервером по ходу соединения.

1. AUTHENTICATION_REQUEST

Запрос авторизации отправляется NASом RADIUS-серверу и содержит помимо идентификационной информации соединения, указанной выше, информацию о логине и пароле пользователя. Логин передаётся в открытом виде, пароль шифруется. Поддерживаются протоколы шифрования PAP, CHAP, MS-CHAP v.2 с генерацией 128 битных MPPE ключей. Протокол авторизации определяется RADIUS-сервером автоматически на основании набора атрибутов.

Протокол PAP является самым ненадёжным, пароль шифруется обратимым способом с помощью секрета. RADIUS-сервер дешифрует его и сравнивает с паролем, указанным для логина в базе данных. Данный режим авторизации можно использовать для проверки секретов. При некорректном секрете пароль в PAP режиме не расшифровывается и отображается в radius.log и в мониторе ошибок не в том виде, в котором был введён пользователем.

Протоколы CHAP, MS-CHAP v.2 поддерживают необратимое шифрование, когда RADIUS-сервер сравнивает не открытый пароль, а результаты криптопреобразований открытого пароля, выполненного им самим и NASом.

MPPE ключи, передаваемые в AUTHENTICATION_ACCEPT пакете в режиме MS-CHAP v.2 авторизации, могут использоваться NASом для шифрования VPN-туннеля пользователя.

Порядок обработки авторизационного пакета следующий: запрос -> скрипт предобработки -> антиспам (блокировка) -> биллинг (проверка наличия логина/пароля, баланса и т.д.) -> штатный Reject-To-Accept -> обработка события "RADIUS-аутентификация" -> антиспам (сбор статистики) -> ответ.

2. AUTHENTICATION_REJECT

Отказ в авторизации, данный пакет не содержит атрибутов. Детальную причину отказа в авторизации пользователя можно посмотреть в Мониторе модуля в режиме ошибок.

3. AUTHENTICATION_ACCEPT

Пользователь авторизован. В данном пакете могут содержатся атрибуты, устанавливающие характеристики соединения пользователя (IP адрес, скорость, максимальную длину сессии, частоту UPDATE пактов и т.п.).

4. ACCOUNTING_REQUEST

Запросы аккаунтинга могут быть трёх типов: Start, Stop, Update. Различаются они атрибутом Acct-Status-Type, который равен 1, 2 или 3 соответственно. Данный тип запросов передаёт на RADIUS-сервер информацию о ходе соединения (соединение началось, завершилось или текущее состояние соединения).

5. ACCOUNTING_RESPONSE

Ответ RADIUS сервера о том, что он получил запрос аккаунтинга. Ответ не содержит никаких атрибутов. Исключение составляет ответ MPD серверу, который может содержать атрибут, информирующий NAS о необходимости разрыва соединения.

2.1. SNMP и NetFlow

Кроме одноимённого протокола RADIUS-сервером применяется протокол SNMP - для постоянной проверки активности соединения и его принудительного разрыва. Т.к. RADIUS-сервер обсчитывает соединение в реальном режиме времени, нужна постоянная информация о статусе соединения, чтобы предотвратить обсчёт соединения, если клиент вышел, но по какой-либо причине Stop сигнал не пришёл. Кроме того по SNMP происходит посылка сигнала на окончание сессии, если клиент вышел за 0 своего баланса.

На основании пакетов Update или Stop может осуществляться подсчёт трафика, т.к. они могу содержать информацию об отправленных и принятых байтах. Вся конфигурация берётся RADIUS-сервером из базы данных, которая может правиться с помощью клиента.

Начиная с версии 3.5_p4 модуль содержит встроенный NetFlow-коллектор, позволяющий анализировать NetFlow потоки NASа и делить трафик соединения по типам.

2.2. Режимы работы RADIUS сервера

RADIUS-сервер для модуля DialUp может работать в двух режимах:

а) Режим активной проверки существования соединения (CHECKER). В этом режиме происходит постоянная посылка запросов на NAS с целью выяснения, активно ли соединение. В случае, если соединение активно, через каждые update.time (настраивается в конфигурации модуля) секунд происходит выделение мини аванса времени с начислением в баланс и поток обсчёта засыпает до следующего обсчёта.

Параметр sleep.time задаёт интервал в секундах, через который необходимо проверять нужен ли новый аванс времени. В случае, если аванс не может быть выделен, посылается сигнал завершения соединения.

Update-пакеты с информацией о трафике могут быть использованы, но они не обязательны и обсчёт трафика также происходит по таймеру. Т.е. сначала начисляются деньги за скачанный трафик, после чего вычисляется время, которое клиент может проработать при условии, что он не будет потреблять трафик.

Преимущества: Точное время сброса клиента, если не идёт обсчёт трафика.

Недостатки: Требуется поддержка на NASе запросов активности соединения, дополнительная вычислительная нагрузка.

б) Режим пересчёта по Update-пакетам (UPDATE). Пересчёт происходит по получению Update-пакета, если после этого баланс будет отрицателен, идёт сигнал на завершение соединения.

Преимущества: Уменьшенная нагрузка на сервер обсчёта, обсчёт происходит только по сигналам Update.

Недостатки:

- Необходима поддержка на NASе Update-пакетов;

- Невозможно довести клиента до полного нуля, он всегда его немного пройдёт, насколько - зависит от частоты Update-пакетов.

Предпочтительным режимом работы является Update, режим работы может быть установлен как глобально на BGRadiusDialup в конфигурации модуля, так и персонально для каждого NASа.

2.3. Статус соединения

Каждое соединение в ходе своей жизни проходит несколько статусов: wait, sleep, active. После авторизации статус соединения становится wait до прихода Start-пакета. Таймаут максимального ожидания старта задаётся переменной max.wait.timeout конфигурации модуля. Если в течении указанного времени Start-пакет по Nas-Port не будет получен, соединение удаляется.

После прихода старта статус становится sleep до момента подтверждения активности по SNMP (CHECKER режим) или посредством Update-пакета (UPDATE режим). При положительном результате проверки статус переходит в active, соединение учитывается при подсчёте активных соединений логина, идёт обсчёт его времени и трафика.

Если в течении некоторого времени не приходят UPDATE-пакеты (для режима UPDATE, таймаут задаётся переменной max.update.timeout конфигурации модуля в секундах), либо результат проверки по SNMP показывает, что соединение неактивно - оно вновь переходит в статус sleep.

Соединение, слишком долго пребывающее в статусе sleep, может быть закрыто автоматически. В ином случае оно будет закрыто только, если придёт авторизация на такой же NAS-Port, что и у данного соединения.

2.4. Работа с соединением

По ходу работы соединения RADIUS-сервер постоянно производит его тарификацию, информация о лимите договора и его статусе перечитывается постоянно, позволяя прервать текущее соединение, либо наоборот, оставить его работающим при временном понижении лимита.

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

Все соединения RADIUS-сервера должны быть сброшены после наступления нового месяца. Для этого можно устанавливать опцию в конфигурации NASа month.break=1, либо производить корректное завершение сессий на NASах иными средствами. Требование разрыва на границе месяца связано с особенностью тарификации биллинга.

2.5. Порядок тарификации

Замечание

Понимание порядка тарификации очень важно для построения тарифных планов и понимания механизма их работы.

Рассмотрим в каком порядке происходит тарификация трафика и времени в разных режимах обсчёта. В каждом соединении ведутся счетчики байт, посчитанных и потреблённых. При этом NetFlow-коллектор по мере получения потоков увеличивает счётчики потреблённых байт в памяти, также они могут изменятся по приходу UPDATE, либо STOP-пакетов (зависит от настройки трафиков в NASе). Ещё одна характеристика соединения - время его окончания - это то время, до которого было обсчитано соединение.

1) При режиме тарификации UPDATE, после получения UPDATE-пакета:

Увеличиваются счётчики потреблённых байт, если настроено извлечение трафика из RADIUS-пакетов.
Тарифицируется потреблённый трафик как разница между счётчиками потреблённых и посчитанных байт. Весь трафик считается потреблённым единоразово в текущее время окончания сединения (время предыдущего UPDATE-пакета).
Тарифицируется потреблённое время. Считается, что в момент текущего времени окончания, было потреблено количество секунд до текущего времени. Если при этом был переход часа, то тарификация времени осуществляется в два этапа. Считается, что в момент текущего времени окончания было потреблено количество секунд до границы часа, а на границе часа было потреблено оставшееся количество секунд.
Изменяется время окончания соединения на текущее время. При необходимости (исчерпан баланс, смена зоны в тарифе) может быть послан сигнал сброса соединения, либо CoA пакет.

Обратите внимание, что каждая услуга считается потреблённой в какой-то определённый момент времени. Это время передаётся в тарифном запросе и используется узлами тарифных планов Фильтр по типу времени, Период и т.п.

2) При режиме тарификации CHECKER (устаревший режим). Тарификация осуществляется по таймеру, периодически просыпающимся потоком. При каждом обсчёте:

Тарифицируется потреблённый трафик, как разница между счётчиками потреблённых и посчитанных байт. Весь трафик считается потреблённым единоразово в текущее время окончания сединения (время предыдущего обсчёта).
От текущего времени окончания соединения отсчитывается аванс времени в update.time секунд. Обсчёт идет в будущее, при переходе часов осуществляется разбивка секунд аналогично режиму UPDATE.
Изменяется время окончания соединения (время может стать в будущем). При необходимости (исчерпан баланс, смена зоны в тарифе) может быть послан сигнал сброса соединения, либо CoA пакет.
Поток засыпает, просыпаясь каждые sleep.time секунд для проверки прохождения времени окончния соединения и, следовательно, необходимости нового обсчёта.
При получении STOP-пакета возможен обсчёт времени в обратном направлении, т.к. соединение может завершиться раньше уже просчитанного времени окончания.

2.6. RADIUS атрибуты

Посредством RADIUS-атрибутов производится весь обмен информацией между NASом и RADIUS-сервером. Набор поддерживаемых RADIUS атрибутов меняется для каждого NASа, ниже рассмотрены общие для всех атрибуты.

Таблица 14.1. Таблица атрибутов

АтрибутТипы пакетовНазначение
Framed-IP-AddressAUTHENTICATION_ACCEPT, ACCOUNTING_REQUEST

IP-адрес, выдаваемый клиенту RADIUS-сервером, либо NASом.

Для выдачи сервером адрес может быть указан в свойствах логина на вкладке IP-адрес, либо Атрибуты RADIUS. Также адрес может быть выдан из пула адресов.

Если адрес не выдаётся сервером в ответе авторизации - он может быть выдан NASом и передан в Start-пакете.

Адрес используется RADIUS-сервером для регистрации его на встроенном NetFlow-коллекторе и привязке потоков к сессии клиента.

Framed-Pool

AUTHENTICATION_ACCEPT

Именованный пул адресов, из которого NAS должен выдать адрес клиенту.

RADIUS-сервер может обрабатывать этот атрибут самостоятельно, выдавая при наличие данного атрибута в ответе авторизации свободный IP-адрес из указанного пула посредством Framed-Ip-Address атрибута.

Framed-Route

AUTHENTICATION_ACCEPT

Маршрутизируемая через тоннель сеть, например:

10.80.0.0 255.255.255.0 10.60.0.1 100 (IP-адрес сети) (маска) (куда маршрутизировать) (вес маршрута)

Либо можно вместо маски указать длину префикса: 10.80.0.0/24 10.60.0.1 100 - то же самое, что и в предыдущем примере.

Данный атрибут поддерживается не всеми VPN-шлюзами. RADIUS-сервер анализирует передачу информации о сетях в ответе авторизации и использует её при разнесении NetFlow потока на соединения.

Acct-Interim-Interval

AUTHENTICATION_ACCEPT

Период в секундах между Update-пакетами, не может быть меньше, чем 60 секунд.
Calling-Station-Id

ACCOUNTING_REQUEST, AUTHENTICATION_REQUEST

Номер звонящего для DialUP-соединения, MAC-адрес клиента для PPPoE-соединения, IP-адрес клиента для PPtP-соединения.
Called-Station-Id

ACCOUNTING_REQUEST, AUTHENTICATION_REQUEST

Вызываемый номер для DialUP-соединения, MAC-адрес сервера для PPPoE-соединения, IP-адрес сервера для PPtP-соединения.
Acct-Session-Time

ACCOUNTING_REQUEST

Длительность соединения в секундах; информация используется при завершении соединения для точного обсчёта времени и корректировки длительности соединения в БД.

При установке в конфигурации модуля опции ignore.acct.session.time=1 RADIUS-сервер игнорирует этот атрибут, сам вычисляя длительность, как разницу во времени между пакетами Start и Stop.

Acct-Input-Octets

ACCOUNTING_REQUEST

Исходящий для пользователя трафик в байтах.
Acct-Input-Gigawords

ACCOUNTING_REQUEST

Исходящий для пользователя трафик в 2^32 байтах (gigaword), атрибут используется как старший разряд Acct-Input-Octets в случае, если количество отправленных байт более 2^32.
Acct-Output-Octets

ACCOUNTING_REQUEST

Входящий для пользователя трафик в байтах.
Acct-Output-Gigawords

ACCOUNTING_REQUEST

Входящий для пользователя трафик в 2^32 байтах (gigaword), атрибут используется, как старший разряд Acct-Output-Octets в случае, если количество принятых байт более 2^32.
User-Name

ACCOUNTING_REQUEST, AUTHENTICATION_REQUEST

Введённый пользователем логин.

Описание атрибутов, специфичных для NASа, необходимо смотреть в документации к NASу.

3. Настройка модуля

Установите модуль на сервер, создайте экземпляр. Определите в Редакторе модулей и услуг услуги, обсчитываемые этим модулем. Например: Входящий трафик, Исходящий трафик, Время. Услуга, соответствующая времени соединений, обязательна, хотя может и считаться по нулевой цене. Названия и количество услуг трафиков могут быть расширены в дальнейшем, исходя из предоставляемых модулем сервисов.

В конфигурации модуля установите:

#активные и приостановленные статусы договора
contract.status.active.codes=0
contract.status.suspend.codes=3,4

#минимальная и максимальная длина пароля 
password.length.min=5
password.length.max=10
#длина автоматически генерируемого пароля
password.length.auto=6
#допустимые в пароле символы
password.chars=1234567890

#пункты Web - меню
web.menuItem1=Просмотр сессий DialUp
web.menuItem2=Наработка по логинам DialUp
web.menuItem3=Смена пароля на логины DialUp
web.menuItem4=Учётные периоды
web.menuItem5=Управление динамическим ДНС
#сколько лет отображать в просмотре сессий через web 
showyears=5
#в просмотре сессий на Web-странице - кол-во выводимых на странице сессий 
show.sessions.on.page=25
#XSL для печати и отправки на почту сессий
xslt.1=dialup_login_sessions.xsl
xslt.1.csv=dialup_login_sessions_csv.xsl 
reportTitle.1=Отчет по сессиям DialUp
#XSL для печати и отправки на почту наработки по логинам 
xslt.2=dialup_login_amount.xsl 
xslt.2.csv=dialup_login_amount_csv.xsl 
reportTitle.2=Отчет по наработке на логины DialUp

#вендоры - производители оборудования и их коды
vendors=9=Cisco;2011=Huawei;2021=Unix PPP;529=Lucent;6618=Quintum;529=Ascend;311=Microsoft;12341=MPD;14988=Mikrotik

#коды услуг, не затрагиваемых при перерасчёте, например, если услуга используется для занесения наработки скриптом
#service.recalc.ignore=

#атрибуты RADIUS, доступные в списке атрибутов в редактировании логина
radius.attributes=Service-Type;Framed-Protocol;Framed-IP-Address;Framed-IP-Netmask;Framed-Routing;Filter-Id;Framed-MTU;Framed-Compression;Login-IP-Host;Login-Service;Login-TCP-Port;Old-Password;Reply-Message;Callback-Number;Callback-Id;Expiration;Framed-Route;Framed-IPX-Network;State;Class;Session-Timeout;Idle-Timeout;Termination-Action;NAS-Identifier;Proxy-State;Framed-Pool

#----------------------------------------
#выборочное отключение проверки закрытого периода
#Перенос логина с даты
#closed.date.disabled.ActionWrapLogin=1
#Обсчет максимальных трафиков
#closed.date.disabled.ActionMaxRecalculate=1
#Удаление учетного периода
#closed.date.disabled.ActionPeriodDelete=1
#Удаление учетного периода
#closed.date.disabled.ActionPeriodUpdate=1
#Начислений сессий
#closed.date.disabled.ActionRecalculateSessions=1
#Редактирование логина
#closed.date.disabled.ActionUpdateLoginInfo=1
#----------------------------------------

#шаблон имени файла при помесячной детализации
#{dd1}{MM1}{yyyy1} - день, месяц, год начала периода, {dd2}.{MM2}.{yyyy2}-день, месяц, год конца периода, {dd2}.{MM2}.{yyyy2} день, месяц, год даты заказа выписки.
#file.detail.template={cid}_{dd1}.{MM1}.{yyyy1}_{dd2}.{MM2}.{yyyy2}_{dd_now}.{MM_now}.{yyyy_now}

############### опции RADIUS-сервера #######################
#граница некарточных логинов
top.nocard.login=10000
#код модуля "карточки", 0 - модуль "карточки" не используется
card.module.id=0
#количество одновременных сессий, разрешённых карточным логинам
#card.login.session.count=1

#1 - проверять наличие в договоре всех требуемых услуг при авторизации, иначе ошибка авторизации "Услуга запрещена" 
check.service=0

#режим работы радиуса
#1 - режим UPDATE - пересчёт во время прохождения UPDATE-пакетов
#2 - режим CHECKER - пересчёт по таймеру, UPDATE-пакеты используются для получения информации о трафике
dialup.workmode=1
#для режима UPDATE - время в секундах после последнего UPDATE-пакета, по истечении которого сессия считается неактивной 
#(не учитывается в подсчёте числа одновременных соединений)
max.update.timeout=120
#сколько максимально секунд соединение в статусе wait ждёт Start-пакета
max.wait.timeout=120
#время в секундах, через которое происходит пересчёт в режиме CHECKER
update.time=60
#время в секундах, через которое проверяется необходимость пересчёта в режиме CHECKER
run.sleep=3
#игнорировать длительность соединения в Acct-Session-Time-атрибуте с NASа, вычислять самостоятельно
#ignore.acct.session.time=1

#задержка закрытия сессий в секундах, используется при тарификации по данным NetFlow
#для исключения потери "хвостов" сессий, т.е. информации о трафике, пришедшей после завершения сессии
#delay.stop=5

#прерывать сессии с того же Calling-Station-Id, если при авторизации произошла ошибка "Превышен лимит сессий"
#(может быть полезно, если на NASе остаются несуществующие сессии и клиент не может переподключится)
#check.duplicate.session=1
#Не разрывать сессии, при изменении действующего тарифного плана в ходе обсчёта. 
#При установке этой опции разрывы и отправку CoA пакетов нужно контроллировать установкой зон в тарифах.
#no.session.break.on.tariff.change=1

#глобальный пул адресов
#pools.global=

#если установлено в 1 - принудительная передача Service-Type=2;Framed-Protocol=1 (рекомендуется передача этих атрибутов иными способами, см. выше realm.default)
add.service.type.and.framed.protocol=0
#если установлено в 1 - добавление в Auth Accept при MPPE-128-авторизации атрибутов MS_mppe_encryption_types (поддержка 128 битного шифрования) и MS_mppe_encryption_policy=1 (шифрование поддерживается)
#согласно http://rfclibrary.hosting.com/rfc/rfc2548/rfc2548-25.asp
add.mppe.enc.types.and.policy=1
#удалять из Accept-пакета атрибуты Framed-Pool в случае, если адрес был успешно выдан RADIUS-сервером
#drop.framed.pool.attr=1
#удаление из атрибута User-Name данных перед \ (в случае его наличия), используется для Windows-клиентов, от которых при авторизации зачастую приходит имя пользователя, предваряемое именем домена, 0 - отключить
remove.user.name.before.backslash=1

#разрешение пользователям без определённой группы REALMов использовать группу default
realmgr.default=default
#атрибуты, передаваемые в AUTH_ACCEPT-пакете при авторизации по реалму default
#в данном случае это интервал между отправкой Update-пакетов, в секундах, протокол PPP, и тип сервиса, см: RFC2865
realm.default=Acct-Interim-Interval=60;Service-Type=2;Framed-Protocol=1
#удаление пробельных символов из начала и конца User-Name
trim.user.name=0
#округлять сессии в отчете перед сложением
report.round.before.sum=1

Параметры xslt.1 и xslt.2 указывают название XSLT-шаблонов преобразования для печати сессий клиента, либо отправки их на E-mail. Параметры reportTitle.1 и reportTitle.2 задают название отчёта, отображаемое сверху и тему письма, содержащего этот отчёт (1 - по сессиям, 2 - по наработке). Это сделано для возможности редактирования оформления отчётов.

Пулы адресов определяются следующим образом:

pools.pool_1=10.0.0.1-10.0.0.3;34.4.4.1

После ключевого слова pools. указывается имя пула (pool_1). После символа равенства - один или несколько одиночных адресов, либо диапазонов с разделителем точка с запятой. Для каждого NASа пул адресов может быть переопределён, как это сделать читайте в разделе о настройке NASов.

С версии 4.5 появилась возможность добавлять параметры для логинов DialUp. Параметры применяются для действий, связанных с логинами (см "Динамическое управление ДНС сервером"). Параметры прописываются в конфигурации модуля в следующем виде:

#параметры для логина
login.parameter.1.name=dialup.dns  #символьное имя параметра, идентифицирует параметр
login.parameter.1.title=Тип ДНС #название, которое показывается в редакторе
login.parameter.1.type=5 # тип параметра ( 1 - строка, 2 - булевое значение, 3 - целое, 4 - десятичное, 5 - перечисляемый список )
login.parameter.1.default=0 #значение по умолчанию (для типа 5 соответствует номеру перечисленного значения, нумерация начинается с 0)
login.parameter.1.listValue=Выключен;Цифровой логин;Логин входа #только для 5 - список возможных значений 

4. REALMы

REALMы - это зоны, в которых может работать ваш клиент, используя один и тот же логин. Фактически, REALM - это суффикс, добавляемый пользователем после своего логина, например login@local - пользователь хочет попасть во внутреннюю сеть, login@www - во внешнюю.

RADIUS-сервер в зависимости от REALMа, указанного клиентом, выдаёт ему определённый набор RADIUS-атрибутов, например, Framed-IP-Address - IP-адрес, который нужно выдать клиенту. Все REALMы должны быть определены в конфигурации модуля DialUp следующим образом:

realm.local=Framed-IP-Address=192.168.168.2;<другие атрибуты>
realm.www=Framed-IP-Address=172.33.3.3;Service-Type=1

REALMы объединяются в группы следующим образом:

realmgr.dialup_user=local;www
realmgr.vpn_user=local

Теперь логины, имеющие группу REALMов dialup_user (группа REALMов устанавливается в свойствах логина), могут попасть как во внешнюю сеть, так и во внутреннюю, а логины с группой vpn_user - только во внутреннюю.

Если пользователь после своего логина не указал REALM, считается, что он хочет попасть в зону default. Также, если в свойствах логина не указана группа REALMов, значит он входит в группу default.

Таким образом, даже если вы не используете REALMы, у вас в конфигурации DialUp должна присутствовать строка.

realmgr.default=default

Это позволит логинам с не указанной группой REALMов использовать REALM default, т.е. входить без указания суффикса после логина. Если же этой строки не будет, то пользователь не сможет авторизоваться, т.к. для группы default не разрешено использование никаких REALMов.

REALMы удобно использовать для разделения услуг доступа к различным сетям, для задания перечня стандартных атрибутов RADIUS, которые нужно высылать всем пользователям, например:

realm.default=Framed-Pool=pool1;Acct-Interim-Interval=120

Атрибуты, передаваемые при логине с определённым REALMом, можно переопределить в конфигурации NASа.

5. Наборы атрибутов

Наборы атрибутов позволяют просто назначать логину, либо тарифному плану определённые RADIUS-атрибуты, которые будут переданы в AUTH ACCEPT-пакете. Наборы определяются в конфигурации модуля следующим образом.

attrset.<id>.title=<Название группы атрибутов>
attrset.<id>.attributes=<перечень атрибутов через ;>

например (значения атрибутов приведены случайно, для примера)

attrset.1.title=Набор 1
attrset.1.attributes=Cisco-AVPair=multilink:min-links=1
attrset.2.title=Набор 2
attrset.2.attributes=cisco-Fax-MDN-Address=1

Наборы атрибутов можно использовать для:

  1. быстрого назначения определённого набора опций логину, не перечисляя каждый раз все атрибуты (например, ACL-список, либо скорость соединения) (см. далее настройку клиентов);

  2. задания опций работы для тарифного плана (см. далее настройку тарифов).

Набор атрибутов может быть переопределён в конфигурации NASа.

6. Выдача атрибутов соединения и выделение IP адресов

При успешной авторизации в пакете AUTHENTICATION_ACCEPT выдаются атрибуты RADIUS, атрибуты выбираются в следующем порядке:

  1. Атрибуты в ответ авторизации может установить скрипт предобработки запроса, данные атрибуты добавляются как при успешной, так и при неуспешной авторизации;

  2. Выбираются наборы атрибутов сначала логина (в свойствах логина на вкладке Атрибуты RADIUS - Наборы атрибутов), а затем из тарифного плана. Каждый набор может быть отправлен только один раз;

  3. Выбираются атрибуты, установленные в свойствах логина на вкладке Атрибуты RADIUS - Атрибуты;

  4. Если на вкладке Атрибуты RADIUS установлена опция присваивания атрибутов Глобальные+локальные, то выдаются атрибуты для текущего REALMа соединения, указанные в конфигурации модуля и NASа;

  5. Атрибуты ответа могут быть изменены скриптом поведения договора при обработке события "RADIUS-аутентификация".

IP адрес соединению присваивается по следующему алгоритму. Если на каком-либо шаге адрес установлен - последующие пропускаются.

  1. Просматриваются установленные в AUTHENTICATION_ACCEPT атрибуты и если среди них присутствует Framed-Ip-Address, считается что у соединения установлен указанный адрес.

  2. Просматривается список адресов указанных в свойствах логина на вкладке IP адрес. Если адресов несколько - выдаётся любой свободный из них, устанавливается атрибут Framed-Ip-Address.

  3. Просматриваются установленные в AUTHENTICATION_ACCEPT атрибуты и если среди них присутствует Framed-Pool атрибут - делается попытка поиска свободного адреса в указанном пуле, описание самого пула последовательно ищется в конфигурации NASа и модуля.

  4. Делается попытка выдачи адреса из глобального пула, определённого в конфигурации модуля как pools.global.

  5. Если адрес не был выдан RADIUS сервером, он берётся из Start пакета для регистрации на встроенном коллекторе.

При успешной выдаче адреса и установленной опции конфигурации модуля drop.framed.pool.attr=1 атрибуты Framed-Pool удаляются из пакета.

При исчерпании пула адресов система шлет специализированный аларм. Дополнительно в конфигурации модуля можно определить пороговый процент для любого из пулов. При проценте использовании пула больше или равном указанному будет высылаться предварительный аларм. Данная мера позволяет заблаговеменно увеличивать размер пулов. Процент указывается следующим образом:

pool.alarm.fullness.<имя пула>=<процент заполнения>

Например (высылка аларма по глобальному пулу после его расходования более чем на 20 целых и 4 десятых процента):

pool.alarm.fullness.global=20.4

7. Настройка NASов

Основная информация, которую должна содержать конфигурация NASа - это его идентификатор, IP-адрес и секрет (необходим для шифрования пароля пользователя, должен совпадать на RADIUS-клиенте и сервере).

Кроме того, к нему должны быть привязаны услуги, определены параметры инспектора (осуществляет управление NASом с целью проверки активности соединения, либо его завершения).

Настройка сервера доступа происходит в два шага.

Сначала кнопкой Новый элемент создаётся новый NAS, ему прописывается идентификатор (что будет приходить от него в атрибуте NAS-Identifier), IP-адрес (что будет приходить от него в атрибуте NAS-IP-Address), RADIUS-секрет, вендор и комментарий. Список вендоров задаётся в конфигурации модуля. После нажатия кнопки Ок должна появиться новая строка в таблице.

Внимание

Обязательно устанавливайте правильного вендора для NASа.

Двойным кликом мыши откройте её для редактирования и кнопкой Создать добавьте текстовую конфигурацию. Название - произвольное.

Внимание

Возможна также настройка общих конфигураций для NASов. Создание общих конфигураций происходит аналогично описанному далее, за исключением того, что они могут использоваться в нескольких NASах. При этом локальные настройки имеют больший приоритет (т.е. если оба флага присутствуют и во включенной общей, и в выбранной локальной конфигурациях, то будет использован локальный).

Содержимое конфигурации может меняться в зависимости от типа NASа, но обязательно содержит следующие данные:

#телефоны по портам, * - все порты (если параметр не указан, вызываемый номер берётся из Calling-Station-Id)
#nas.port_phone.*=900111
#числовые коды услуг времени, трафика входящего и исходящего
nas.port_time.default.*=XXX
nas.port_traffic.default.*=XXX
#разрешение активировать все типы карточек на этом NASе
card.activate.service=0
#поддержка CallBack (1-включено)
callback.support=0
#принудительный разрыв соединений на границе месяца
month.break=1
#время в секундах после начала месяца, в течении которого должны быть сброшены соединения предыдущего месяца с NASа
month.break.period=3600
#интервал между посылками на проверку, либо сброс соединения в секундах
nas.inspector.sleep_time=60
#максимальное число попыток сброса соединения
nas.inspector.kill.max_messages=5

Режим работы UPDATE, либо CHECKER может быть задан независимо для каждого NASа опцией dialup.workmode аналогично конфигурации модуля DialUP. Если режим не установлен - используется значение режима из конфигурации модуля.

Наиболее важной настройкой каждого из NASов является конфигурация услуг. Она определяет, с какими услугами модуля будут сопоставлены трафики соединения и его время. Конфигурация услуг должна быть определена для каждого сочетания REALM+NAS-Port, доступного на данном NASе, в противном случае при авторизации будет выведена ошибка Not found service id.

Разделение по REALMу позволяет выделять отдельные услуги на разные сервисы, потребляемые пользователем. Например, вход просто с логином являет из себя услугу VPN-время, для которой определена цена 0 в тарифном плане и для данного типа входа обсчитывается трафик. А вход под REALMом time (login@time) определяет услугу время как VPN-повременный, для которой в том же тарифе определена ненулевая цена, а трафик при данном входе не учитывается (пустая конфигурация трафиков).

Разделение по порту предоставляет возможность разделения услуг для многоканальных и обычных телефонов доступа в пределах одного NASа.

Строка привязки услуги типа "время" к REALMу и порту выглядит следующим образом:

nas.port_time.<realm>.<port>=<sid>

где:

<realm> - REALM под которым авторизуется пользователь (если после логина ничего не указано - REALM считается default);
<port> - NAS-Port на который авторизуется пользователь, возможность привязки отдельной услуги типа время на выделенные порты полезна, например, для выделения многоканальных телефонов, * - любой порт;
<sid> - числовой код услуги типа "время".

Привязка услуг типа "трафик" к REALMу и порту выглядит следующим образом:

nas.port_traffic.<realm>.<port>=<service1>;<service2>;...<serviceN>

где значения <realm> и <port> идентичны таким же параметрам в указании услуги типа "время", а записи <serviceX> представляют из себя строку следующего вида:

<sid>:<keyword>

где <sid> определяет код услуги типа "трафик", а <keyword> может принимать следующие значения:

RADIN - объем услуги в байтах, получается на основании RADIUS-пакета (атрибуты Acct-Output-Octets, Acct-Output-Gigawords);
RADOUT - объем услуги в байтах, получается на основании RADIUS-пакета (атрибуты Acct-Input-Octets, Acct-Input-Gigawords);
RAD(<vcode>,<atrcode>,<prefix>) - объем услуги в байтах, получается на основании RADIUS-пакета, строкового атрибута с кодом <atrvcode> вендора с кодом <vcode>, трафик указывается после префикса <prefix> и одного символьного разделителя. Например: 7:RAD(12341,10,local) - получение трафика по седьмой услуге из атрибута MPD mpd-output-octets после префикса "local:";
COLLECTOR - объем услуги в байтах, получается по информации NetFlow-коллектора (коллектор определяет тип услуги на основании привязок услуг из конфигурации модуля, см. настройку встроенного коллектора);
MAX(<sid2>,<sid3>) - услуга <sid> вычисляется как максимум из услуг <sid2>, <sid3> на каждый из моментов обсчёта;
SUM(<sid2>,<sid3>, <sid4>, <sid5>) - услуга <sid> вычисляется как сумма услуг <sid2>..<sid5> на каждый из моментов обсчёта, количество параметров функции может быть от двух до четырёх

Замечание

При получении трафика посредством NetFlow, либо sFlow-протокола необходима соответствующая настройка встроенного коллектора и конфигурации NASа.

В случае, если трафик не нужно тарифицировать и учитывать, вы можете оставить в конфигурации только:

nas.port_traffic.<realm>.*=

Услуга времени должна быть определена всегда.

Рассмотрим несколько примеров записи конфигураций услуг для NASа:

Пример 14.1. Простейший случай

Ставится задача обсчёта суммарного входящего трафика клиента. При этом в вашем модуле DialUP заведены 3 услуги - Время (1), Входящий трафик (2), Исходящий трафик (3). А в тарифном плане клиента указаны цены за эти услуги (включая нулевые за время и исходящий трафик). В этом случае конфигурация времени и трафиков будет выглядеть следующим образом:

nas.port_time.default.*=1
nas.port_traffic.default.*=2:RADIN;3:RADOUT

Пример 14.2. Обсчёт максимального трафика

Ставится задача обсчёта времени работы и максимального из трафиков клиента. При этом в модуле DialUP заведены 4 услуги - Время (1), Входящий трафик (2), Исходящий трафик ( 3), Максимальный трафик (4). В тарифном плане клиента должны быть указаны 4 цены (2 из них нулевые - за входящий и исходящий трафик). Конфигурация будет выглядеть следующим образом:

nas.port_time.default.*=1
nas.port_traffic.default.*=2:RADIN;3:RADOUT;4:MAX(2,3)

Начиная с 4.2 версии в конфигурации трафика возможно использование функции SUM - суммарный трафик. Её использование аналогично MAX, но параметрами могут выступать до 4х кодов услуг.

Пример 14.3. Обсчёт суммарного трафика

Ставится задача обсчёта времени работы и суммарного из трафиков клиента. При этом в модуле DialUP заведены 4 услуги - Время (1), Входящий трафик (2), Исходящий трафик (3), Максимальный трафик (4). В тарифном плане клиента должны быть указаны 4 цены (две из них с нулевой ценой - за входящий и исходящий трафик). Конфигурация будет выглядеть следующим образом:

nas.port_time.default.*=1
nas.port_traffic.default.*=2:RADIN;3:RADOUT;4:SUM(2,3)

Пример 14.4. Обсчёт трафика с делением по типам в пределах сессии

Ставится задача обсчитывать по разным ценам локальный и глобальный входящий трафик клиентов. В модуле DialUP заводится 3 услуги: Время (1), Локальный входящий (2), Глобальный входящий (3). В тарифном плане определены все 3 стоимости.

nas.port_time.default.*=1
nas.port_traffic.default.*=2:COLLECTOR;3:COLLECTOR

Ключевое слово COLLECTOR в последнем случае обозначает, что трафик данного типа будет предоставляться со встроенного коллектора. О установке и настройке встроенного NetFlow-коллектора для BGRadiusDialup читайте далее.

Пример 14.5. Использование REALMов

Ставится задача предоставления доступа по трафику и двух видов повременного доступа на скоростях 64 кбит/с и 256 кбис/с с различной оплатой часа. Для повременного соединения пользователь вводит имя пользователя login@64k, login@256k. Для данных REALMов в конфигурации модуля должны быть определены атрибуты RADIUS, устанавливающие параметры скорости.

В модуле DialUP заводятся 5 услуг: Время обычное (1), Входящий трафик (2), Исходящий трафик (3), Время 64k (4), Время 256k (5). В тарифном плане определены цены: 1 - нулевая стоимость, 2 и 3 - стоимость трафиков обычного соединения, 4 - стоимость соединения на скорости 64кбит/с за единицу времени, 5 - стоимость соединения на скорости 256kбит/с за единицу времени.

nas.port_time.default.*=1
nas.port_traffic.default.*=2:RADIN;3:RADOUT
nas.port_time.64k.*=4
nas.port_traffic.64k.*=
nas.port_time.256k.*=5
nas.port_traffic.256k.*=

Обратите внимание, что для повременного доступа конфигурации услуг трафиков пустые, т.е. трафики не учитываются вовсе.

Пример 14.6. Разделение по портам

Ставится задача тарификации DialUP-доступа по времени, при этом определённые порты NASа (1 и 5) являются многоканальными, стоимость часа на них выше, чем на остальных. В модуле DialUP заводятся 3 услуги: Время простое (1), Время многоканальный (2). В тарифном плане клиента определяются стоимости часа по каждой из услуг.

nas.port_time.default.1=2
nas.port_time.default.5=2
nas.port_time.default.*=1
nas.port_traffic.default.*=

Чтобы прописать пул IP-адресов, добавьте в конфигурацию NASа строку (пример пула из 3х адресов):

nas.pools.myPool=192.168.169.3-192.168.169.4;192.168.169.33

После ключевого слова nas.pools. указывается имя пула (myPool). После знака равенства определяются один или несколько диапазонов, либо единичных адресов, разделённых точкой с запятой. Пулы, определённые в конфигурации NASов, более приоритетные, чем определённые в конфигурации модуля. Т.е. если пользователю атрибутами сопоставлен некий пул, и пул с таким именем определён как в конфигурации NASа, так и модуля, будет выбран пул из NASа.

Обратите внимание на параметр card.activate.service - это ограничение по типам Интернет-карточек, которые можно активизировать на данном NASе.

0 означает, что на нем можно активизировать любую карточку, в противном случае через точку с запятой необходимо перечислить коды услуг активации карт, разрешённых к активации на данном NASе.

Опция month.break означает, что RADIUS-сервер будет принудительно разрывать соединения на границе месяца для данного NASа. Сделано это для того, чтобы в ходе работы в следующем месяце у клиента не изменялся баланс за предыдущий, т.к. изменяется баланс того месяца, где началось соединение.

Остальная часть конфигурации NASа различается для серверов различного типа и отвечает за настройку инспектора - управляющим ходом соединений подсистемы. Задача инспектора - проверка активности соединения (для режима CHECKER) и сброс соединения по событию биллинга.

Все инспекторы, кроме универсального PoD, работают по протоколу SNMP. SNMP-порт и community устанавливаются следующим образом (дополнительно можно скорректировать размеры входящего/исходящего буферов сокета):

#SNMP порт и пароль (не нужны для PoD инспектора)
nas.inspector.snmp.port=161
nas.inspector.snmp.community=XXXXX
#входящий буфер в мегабайтах
nas.inspector.snmp.buffer.in=4
#исходящий буфер в мегабайтах
nas.inspector.snmp.buffer.out=4

Далее, в зависимости от типа NASа, устанавливаются опции.

1. Huawei Expert (vendor=2011).

snmp.version=1
nas.inspector.snmp.kill.oid=1.3.6.1.4.1.2011.2.3.4.3.5.2.1.3.0
nas.inspector.snmp.check.oid=1.3.6.1.4.1.2011.2.3.4.3.5.2.1.5.0
nas.inspector.class=ru.bitel.bgbilling.kernel.network.radius.inspectors.SNMPNasConnectionInspectorHuaweiExpert

2. Unix PPP (vendor=2021).

snmp.version=2
#возможные значения 2.4.2 и 2.4.3, для 2.4.4 указывается версия 2.4.3
pppd.version=2.4.2
nas.inspector.class=ru.bitel.bgbilling.kernel.network.radius.inspectors.SNMPNasConnectionInspectorPPPD
nas.inspector.snmp.kill.oid=1.3.6.1.4.1.2021.255.1
nas.inspector.snmp.check.oid=1.3.6.1.4.1.2021.255

3. FreeBSD MPD 4.x, 5.x (vendor=12341).

dialup.workmode=1
snmp.version=2
nas.inspector.class=ru.bitel.bgbilling.kernel.network.radius.inspectors.SNMPNasConnectionInspectorMPD
nas.inspector.snmp.kill.oid=1.3.6.1.4.1.2021.255.1
nas.inspector.snmp.check.oid=1.3.6.1.4.1.2021.255

4. Cisco 53x (vendor=9), либо другие модели Cisco см. здесь.

snmp.version=2
nas.inspector.class=ru.bitel.bgbilling.kernel.network.radius.inspectors.SNMPNasConnectionInspectorCisco
nas.inspector.snmp.kill.oid=1.3.6.1.4.1.9.9.150.1.1.3.1.5
nas.inspector.snmp.check.oid=1.3.6.1.4.1.9.9.150.1.1.3.1.5
#возможна ситуация, когда в Acct-Session-Id передаётся не только код сессии, но и дополнительная "приставка" вначале
#данная опция вырезает из Acct-Session-Id строку от 4го символа для получения SNMP-кода сессии, вместо 4 может быть указано любое число
#session.mode=hex4

5. Cisco 36x (vendor=9).

nas.inspector.class=ru.bitel.bgbilling.kernel.network.radius.inspectors.SNMPNasConnectionInspectorCisco36x
nas.inspector.snmp.kill.oid=1.3.6.1.4.1.9.2.9.10.0 
nas.inspector.snmp.check.oid=1.3.6.1.4.1.9.2.9.2.1.18

6. Lucent Acsend (vendor=529).

nas.inspector.class=ru.bitel.bgbilling.kernel.network.radius.inspectors.SNMPNasConnectionInspectorCisco
nas.inspector.snmp.kill.oid=1.3.6.1.4.1.529.12.3.1.3
nas.inspector.snmp.check.oid=1.3.6.1.4.1.529.12.3.1.4
#раскомментировать, если код сессии (Acct-Session-Id) приходит в десятичном формате
#session.mode=dec

7. US Robotics NetServer (vendor=429).

nas.inspector.class=ru.bitel.bgbilling.kernel.network.radius.inspectors.SNMPNasConnectionInspectorUSRoboticsNetServer
nas.inspector.snmp.check.oid=1.3.6.1.4.1.429.4.10.1.1.18
nas.inspector.snmp.kill.oid=1.3.6.1.4.1.429.4.10.13

8. MS RRAS для W2K (vendor=311).

nas.inspector.class=ru.bitel.bgbilling.kernel.network.radius.inspectors.SNMPNasConnectionInspectorMsRRAS

9. Универсальный инспектор, вызывающий для проверки и разрыва соединения внешний скрипт с набором параметров командной строки.

nas.inspector.class=ru.bitel.bgbilling.kernel.network.radius.inspectors.ScriptNasConnectionInspector
#путь к внешнему скрипту проверки, если код выполнения будет 1 - абонент активен, если другой - неактивен
#требуемые параметры командной строки указываются после имени скрипта следующим образом ${NAS_IP} ${NAS_ID} ${USER_LOGIN} ${USER_SESSION} ${USER_PORT}
#например, /usr/local/check.pl ${NAS_IP} ${USER_PORT}
nas.inspector.check.command=
#путь к внешнему скрипту разрыва соединения
#требуемые параметры командной строки указываются после имени скрипта следующим образом ${NAS_IP} ${NAS_ID} ${USER_LOGIN} ${USER_SESSION} ${USER_PORT}
#например, /usr/local/kill.pl ${NAS_IP} ${USER_PORT}
nas.inspector.kill.command=

10. WiFi-портал модуля Dialup.

nas.inspector.class=ru.bitel.bgbilling.kernel.network.radius.inspectors.WiFiConnectionInspector
nas.inspector.wifi.host=<IP адрес, где поднят wifi-агент>
nas.inspector.wifi.port=<порт, на котором поднят wifi-агент >

11. Универсальный инспектор для всех NASов с поддержкой PoD. Использование возможно только в режиме обсчёта UPDATE. Дополнительно данный инспектор обладает возможностью отправки CoA-запросов согласно настройкам в тарифном плане для изменения параметров сессии без разрыва соединения.

dialup.workmode=1
#
nas.inspector.class=ru.bitel.bgbilling.kernel.network.radius.inspectors.PodNasConnectionInspector
#на какой порт слать PoD/CoA запросы
nas.inspector.radius.port=1812
#на какой хост слать (если не указан - берется IP-адрес NASа)
#nas.inspector.radius.host=
#секрет для подписи пакетов (если не указан - берется секрет NASа)
#nas.inspector.radius.secret=
#какие атрибуты добавлять в PoD/CoA-запрос из сессии, если пустой параметр - высылаются все атрибуты
nas.inspector.radius.attributes=User-Name;Framed-IP-Address;Acct-Session-Id
#опции, относящиеся только к CoA-пакетам
#таймаут ожидания ответа в секундах между попытками отправки пакета СoA
nas.inspector.coa.timeout=5
#количество попыток отправить пакет CoA
nas.inspector.coa.retries=2
#количество потоков отправки CoA-пакетов
nas.inspector.coa.threads=4
#отправка при смене CoA-пакета всех атрибутов, аналогично ответу на авторизацию
#nas.inspector.coa.send.all.attributes=1
#логирование в RADIUS-логе сессии, отправляемых CoA-пакетов
#coa.log=1
#фиксированные атрибуты CoA-пакета
#nas.inspector.coa.fixed.attributes=
#фиксированные атрибуты PoD-пакета
#nas.inspector.pod.fixed.attributes=
#отправка PoD-пакета вместо CoA
#nas.inspector.send.pod.instead.coa=1

Подробные инструкции по интеграции BGRadiusDialup с различными NASами доступны в WiKi.

Для использования дополнительной возможности некоторых NASов самостоятельно ограничивать трафик, либо время соединения RADIUS способен высылать атрибуты с максимальными значениями трафика, либо времени с учётом текущего баланса пользователя.

Чтобы RADIUS отправлял атрибут с ограничением, он должен быть прописан в текущем REALMе пользователя, либо в дополнительных атрибутах логина.

Далее необходимо указать, что данный атрибут является ограничительным по какой-либо услуге, это производится в конфигурации NASа подобным образом:

service.limit.attribute=<Название атрибута>:<Код услуги>

Пример 14.7. Пример

В модуле DialUP есть услуга "Входящий трафик" с кодом 23 и мы хотим, используя простейшие линейные тарифы, устанавливать ограничение на трафик соединения. Для этого в конфигурации модуля DialUP указывается.

realm.default=...;WISPr-Bandwidth-Max-Down=64000;ChilliSpot-Max-Output-Octets=limit

А в конфигурации NASа:

service.limit.attribute=ChilliSpot-Max-Output-Octets:23

Теперь данный атрибут с ограничением трафика будет высылаться всем подключившимся пользователям. Расчёт атрибута производится исходя из тарифного плана клиента.

Для того, чтобы отправлять дубликаты аккаунтинг запросов на другой хост, необходимо добавить в конфиг NASа такие параметры:

#Хост и порт, на который отправлять дубликат аккаунтинг RADIUS-пакета
radius.forward.host=
radius.forward.port=
#Секрет, которым подписывать пакет, если не указан, то используется секрет NASa
#radius.forward.secret=
#Префикс, который нужно добавлять к атрибуту User-Name
#radius.forward.user.name.prefix=
#Суффикс, который нужно добавлять к атрибуту User-Name
#radius.forward.user.name.suffix=

7.1. Скрипт предобработки запроса

В вкладке Скрипт предобработки редактора NASа может быть написан BGBS скрипт предобработки, предобрабатывающий все запросы, приходящие на данный NAS.

Начиная с 4.2 версии биллинга, код услуги типа время может быть установлен скриптом предобработки RADIUS-запроса в опцию service_time. Услуга, например, может быть выбрана на основании АОН звонящего. Услуга типа время, установленная скриптом, обладает бОльшим приоритетом по сравнению с установленной в конфигурации, примеры можно посмотреть в WiKi.

Замечание

Скрипты обработки RADIUS-запросов кэшируются RADIUS-сервером при первом исполнении. Для сброса кэша необходимо перезапустить RADIUS-сервер, либо выполнить команду в каталоге RADIUS-сервера.

Для Linux:

./radius.sh flush_script_cache

Для MS:

radius.bat flush_script_cache

Логи работы скриптов вы можете посмотреть в файле BGBillingServer/log/script.log

7.2. Пересылка RADIUS Accounting

Для дублирования полученных RADIUS Accounting-запросов на сторонний сервер в конфигурации NASа следует указать.

packet.forward.host=<host>
packet.forward.port=<port>
packet.forward.secret=<secret>
packet.forward.user.name.prefix=<prefix>
packet.forward.user.name.suffix=<suffix>

Где:

<host> - хост, на который будут ретранслироваться пакеты, единственный обязательный параметр для включения функционала;
<port> - порт, на который будут ретранслироваться пакеты, по умолчанию равен 1813;
<secret> - RADIUS-секрет, которым будет подписан пакет, по умолчанию берётся секрет NASа;
<prefix> - префикс к значению атрибута User-Name из аккаунтинг пакета, если не указан - префикс не добавляется;
<suffix> - суффикс к значению атрибута User-Name из аккаунтинг пакет, если не указан - суффикс не добавляется.

Суффикс и префикс могут быть полезны при необходимости ретранслирования пакетов с нескольких BGRadiusDialup с пересекающимися логинами на единый сервер.

Например:

packet.forward.host=bitel.ru
packet.forward.port=4444
packet.forward.secret=4343
packet.forward.user.name.prefix=test_
packet.forward.user.name.suffix=_forv

8. Настройка RADIUS-сервера для DialUp

Замечание

BGRadiusDialup обновляется как обычное серверное приложение биллинга. Необходимо обновить приложение перед первым запуском.

8.1. Установка BGRadiusDialup на Linux-платформу

1) Извлеките BGRadiusDialup из архива и скопируйте в каталог /usr/local;

2) Перейдите в каталог /usr/local/BGRadiusDialup;

3) Удалите все .ini, .bat и .exe файлы:

rm -f ./*.bat & rm -f ./*.exe & rm -f ./*.ini

4) Откройте для редактирования файл radius.sh и пропишите в нем путь к Java машине, например так:

...
cd ${0%${0##*/}}.

JAVA_HOME=/opt/java/jdk16

if [ -z "$JAVA_HOME" ]; then
  echo "The JAVA_HOME environment variable is not defined"
  echo "This environment variable is needed to run this program"
  exit 1
fi
...

5) Проверьте .sh файлы на наличие символов ^M, если символы присутствуют их можно удалить вручную, либо воспользоваться утилитой:

dos2unix *.sh

6) Установите права запуска для всех *.sh файлов:

chmod 744 *.sh

7) Возьмите из каталога BGRadiusDialup/script скрипт запуска bgradius_dialup и скопируйте его в каталог /etc/init.d, установите права на исполнение (см. выше). Если вы изменили каталог установки или переименовывали BGRadiusDialup, скорректируйте скрипт;

8) Выясните текущий уровень запуска системы командой:

[root@gate init.d]# runlevel
N 3

9) Создайте линк для автоматического запуска RADIUS-сервера:

ln -s /etc/init.d/bgradius_dialup /etc/rc5.d/S99bgradius_dialup

10) Произведите настройку radius.properties и запустите RADIUS-сервер (см. далее).

Замечание

При необходимости установки нескольких BGRadiusDialup-серверов на одной машине конечный каталог может быть переименован, например, в BGRadiusVPN. Также требуется переименование и корректировка скрипта запуска, разнесение RADIUS-портов в radius.properties.

8.2. Установка BGRadiusDialup на Windows платформу

Для установки BGRadiusDialup на Windows платформу на диск С:.

1) Убедитесь, что на машине, где вы собрались ставить RADIUS стоит Java машина. Если её нет, установите версию не меньше 1.6.0. Загрузить можете с нашего сайта.

2) Загрузите с сервера RADIUS-сервер для DialUp.

3) Распакуйте архив на диск C:

4) Установите переменную окружения BGRAD_HOME_DIALUP=C:\BGRadiusDialup. Как устанавливать переменные окружения можете посмотреть в инструкции по установке сервера и клиента биллинга.

5) Установите службу BGRadiusDialup, для чего запустите файл radius_install.bat.

6) Убедитесь, что служба появилась в списке служб Windows. В дальнейшем можете удалить эту службу, используя radius_uninstall.bat.

8.3. Настройка radius.properties

Откройте файл radius.properties и произведите настройку:

#процессор-обработчик запросов
processor.class=ru.bitel.bgbilling.modules.dialup.radius.DialUpRadiusProcessor
#код модуля dialup
processor.mid=XXX

#порты авторизации и аккаунта
auth.port=1812
acct.port=1813
admin.port=1955

#опции подключения к БД
db.driver=com.mysql.jdbc.Driver
db.url=jdbc:mysql://127.0.0.1/bgbilling?useUnicode=true&characterEncoding=UTF-8&allowUrlInLocalInfile=true&zeroDateTimeBehavior=convertToNull&jdbcCompliantTruncation=false
db.user=bill
db.pswd=bgbilling

#опции подключения к MQ
mq.url=failover:(nio://127.0.0.1:61616)
mq.user=bill
mq.pswd=bgbilling

Установите переменную processor.mid=<числовой код экземпляра модуля DialUp>. При необходимости скорректируйте параметры доступа к базе данных и к MQ-серверу. Параметры auth.port и acct.port - порты, на которых сервер будет слушать авторизацию и аккаунт. Установлены значения по умолчанию. Параметр admin.port определяет порт, на котором работающий процесс BGRadiusDialup открывает сокет управления, данный порт не должен быть доступен с других машин. Если на этой же машине установлены другие сервера, использующие такие же порты, их следует изменить.

Замечание

Изменения описанных в данном разделе параметров в radius.properties применяются только после перезапуска BGRadiusDialup. Все иные настройки могут быть изменены в ходе работы приложения и применяются при редактировании NASов и их конфигураций, редактировании конфигурации ядра (система алармов), конфигурации модуля.

8.4. Администрирование BGRadiusDialup

8.4.1. Управление BGRadiusDialup

Для запуска и останова сервера RADIUS для DialUp используйте:

1) для Windows: консоль запуска и управления службами, служба BGRadiusDialup;

2) для UNIX: скрипты radius_start.sh и radius_stop.sh.

После запуска посмотрите логи в папке BGRadiusDialup/log.

radius.log - распечатка пакетов запросов и ответов;
radius.out - выходной поток, критичные ошибки;
connection.log - лог хода соединения, обсчётов.

Если запуск прошёл успешно, в логе connection.log должен вывестись список загруженных NASов, указанных вами в модуле DialUp.

В radius.log должно быть сообщение вида:

INFO   18.05.2004 13:04:41 Starting radius auth_port:1812  acct_port:1813 admin_port:1899
INFO   18.05.2004 13:04:41 Init processor 
class: bitel.billing.server.processor.voiceip.DialUpProcessor
mid: 6

NFO   18.05.2004 13:04:42 Starting PortListener port=1812|type=AUTH_LISTENER
INFO   18.05.2004 13:04:42 Starting PortListener port=1813|type=ACCOUNT_LISTENER
INFO   18.05.2004 13:04:42 Starting PortListener port=1899|type=ADMIN_LISTENER

Это свидетельствует о том, что сервер запущен и ожидает пакеты.

Если сервер не запустился, ищите причину в файле radius.out. В него пишутся все критичные ошибки.

С работающего RADIUS-сервера возможно получение с сервера списка соединений и статуса. Это достигается запуском скрипта radius.bat(.sh) с параметрами. Список параметров можно получить простым запуском radius.bat(.sh). Ниже приведена выводимая при этом справка.

Usage: [start|stop|help|status|ps|kill|flush_script_cache]
Parametrs:
 help|?    - show this help
 start     - starting RADIUS server
 stop      - stopping RADIUS server
 status    - current connections status
 flush_script_cache  - flush BGS script cache
######## Only for DialUp RADIUS #########
 ps        - active connections list 
 kill [-port <#port>] [-nas ] [-login <#login>]
           - kill connections by filter
 kill doesn't work with empty params list

Example: radius.sh start
Example: radius.sh kill -nas supernas.bayan.com -login 11

radius.sh(.bat) ps - вывод списка текущих соединений в следующем формате

bill@bill-reg BGRadiusDialup]$ ./radius.sh ps
+---------------+---------------+------------------------------+--------------------+----------+---------------+--------------------+---------------+----------+
|    NAS_ID     |    NAS_IP     |           Session            |       Start        |  Login   |      IP       |      FromNum       |   Contract    |  Status  |
+---------------+---------------+------------------------------+--------------------+----------+---------------+--------------------+---------------+----------+
|     drs1      | 89.189.150.67 |        3419823-p0159         |19.02.2008 16:17:03 |   2443   |  77.79.162.9  |    10.47.8.140     |294NK007193-08 |  active  |
|     drs1      | 89.189.150.67 |        3419689-p0158         |19.02.2008 16:14:49 |2230@local| 172.27.35.248 |    10.47.55.194    |FREEDOM_0/294NK005198-07|  active  |
|     drs1      | 89.189.150.67 |        3413354-p0157         |19.02.2008 14:29:16 |   2499   |89.189.151.103 |    10.47.1.130     |FREEDOM_0/294NK005420-07|  active  |

radius.sh(.bat) status - краткий статус сервера

version 4.4 build 93 from 05.03.2009 17:14:01
12.03.2009 16:31:25     31035   30998   37      0
Request accounts per minute start: 264; stop: 248; update: 2931
Request auths per minute accept: 264; reject: 231
Netfow packets per minute: 144334
Ignore per minute auth: 0; update: 122
Antispam ban count: 20; used per minute: 143
Started: 06.03.2009 05:54:26    Uptime: 6 d 10:36:59
Memory total: 5 234 163 712; max: 5 234 163 712; free: 1 973 243 208
Trees in cache: 39
Connections pool to Master status Idle: 50; Active: 2; maxActive: 100; maxIdle: 50

Построчно статус:

  1. Версия, номер и дата билда BGRadiusDialup;

  2. Текущее время, общее число соединений на сервере, число в статусе active, sleep, wailt;

  3. Количество запросов аккаунтинга за последнюю минуту с разделением по типам;

  4. Количество запросов авторизации за последнюю минуту с разделением по успешным и не успешным авторизациям;

  5. Количество NetFlow-дейтаграмм, полученных за последнюю минуту;

  6. "Проглочено" за последнюю минуту авторизаций и аккаунтинг Update-пакетов;

  7. Количество записей в спам-базе и количество использований спам-базы за последнюю минуту;

  8. Время старта и uptime BGRadiusDialup;

  9. Статус по потребляемой памяти, количеству деревьев в кэше соединений и пулу соединений к БД, более подробно объяснения по данным параметрам здесь;

  10. Статус по количеству деревьев в кэше соединений, более подробно объяснения по данным параметрам здесь;

  11. Статус по пулу соединений к БД, более подробно объяснения по данным параметрам здесь.

radius.sh(.bat) kill <фильтры> - послать команду сброса для соединений.

Внимание

Если фильтр не установлен, сигнал будет послан для всех соединений на RADIUS-сервере.

radius.sh(.bat) flush_script_cache - сброс кэша скриптов предобработки RADIUS-запросов.

8.4.2. Расширение словаря RADIUS

Все указываемые в конфигурациях модуля атрибуты RADIUS должны быть описаны в файле dictionary.xml. Недостающие вендоры и их атрибуты могут быть добавлены администратором системы самостоятельно. Имя любого атрибута должно быть уникально в пределах dictionary.xml.

8.4.3. Антиспам

Спам-запросы на авторизацию порождаются, обычно, забытым оборудованием, самостоятельно предпринимающем попытки авторизации на RADIUS. Постоянные обращения в базу данных при таких запросах существенно повышают загрузку. Признаком спам-запроса являются несколько Reject-ответов на одинаковые запросы авторизации в течение определённого интервала времени. В этом случае подобные запросы попадают в спам-базу на определённое время и по ним автоматически выдаётся Reject-ответ без полных проверок, производимых при авторизации. Для включения антиспам-системы в конфигурации модуля добавьте:

antispam.key.attributes=<key_attributes>
antispam.reject.count=<reject_count>
antispam.reject.per.time=<per_time>
antispam.ban.time=<ban_time>

Где:

<key_attributes> - RADIUS-атрибуты, идентифицирующие запрос, через запятую;
<reject_count> - количество Reject, возвращённых на запрос с одинаковыми идентифицирующими атрибутами;
<per_time> - за какое количество секунд выдано указанное в <reject_count> количество Reject-ответов;
<ban_time> - время в секундах, на которое данный запрос попадает в спам-базу.

Например, запрос идентифицируется атрибутами User-Name и Calling-Station-Id. При десяти Reject-ответах в течении минуты запрос попадает в спам-базу на полчаса.

antispam.key.attributes=User-Name,Calling-Station-Id
antispam.reject.count=10
antispam.reject.per.time=60
antispam.ban.time=900

8.4.4. Поведение BGRadiusDialup при критических нагрузках

Замечание

Вы можете пропустть этот раздел при первичной настройке системы.

На порты авторизационных и аккаунтинговых запросов в BGRadiusDialup определён пул потоков-обработчиков размерами, задаваемыми переменными в radius.properties auth.thread.count и acct.thread.count соответственно. Каждый пришедший запрос обрабатывается в одном из свободных потоков пула.

По мере роста числа запросов авторизации, если число запросов в очереди превысит значение, определённое переменной в radius.properties auth.thread.queue, RADIUS-сервер начинает "проглатывать" запросы авторизации без обработки, предотвращая, тем самым, накопление устаревших запросов в буфере приёма сетевой подсистемы и обрабатывая только самые свежие запросы.

По мере роста числа запросов аккаунтинга, если число запросов в очереди превысит значение, определённое переменной в radius.properties acct.thread.queue, RADIUS-сервер начинает "проглатывать" Update-запросы, оставив оставшиеся потоки для обработки запросов старта и стопа, т.к. они критичнее.

Изменяя параметры количества потоков, следует также изменять количество максимальных активных соединений с базой данных, т.к. ожидание свободного соединения с базой данных блокирует потоки обработки запросов.

8.4.5. Оптимизация работы с базой данных

Замечание

Вы можете пропусить этот раздел при первичной настройке системы.

При обсчёте сессий в реальном режиме времени происходит значительная нагрузка на базу данных. Постоянно обновляются таблицы log_session, session_detail, session_account, contract_balance, contract_account.

В таблицу session_detail_<mid>_yyyyMM производится запись объёма потреблённых по ходу сессии услуг с разбивкой по часам. Возможно снизить число обновлений таблицы, отменив запись по некоторым тарифицируемым по нулевой стоимости и не нужных услуг (например, время при тарификации трафик). Также возможно сгруппировать записи, например, по суткам, если тарифные планы не предполагают различную стоимость услуг по времени суток. Правила "свёртки" таблицы session_detail определяются в конфигурации модуля следующим образом:

detail.compress.<sid>.<hour_range>=<rule>

Где:

<sid> - числовой код услуги, запись о которой вносится в session_detail;
<hour_range> - диапазон часов, к которым относится правило;
<rule> - ключевое слово SKIP (пропуск обновления), либо час, в который преобразуется реальный час вносимой записи.

Например, для отброса записи в session_detail информации об услуге Время с кодом 2 и свёртке по суткам записей по наработке по услугам трафиков 23 и 24 определяются следующие правила:

detail.compress.2.0-23=SKIP
detail.compress.23.0-23=0
detail.compress.24.0-23=0

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

При безлимитных тарифах жёсткое фиксирование посчитанного по нулевой цене трафика в session_detail не обязательно, информация может быть сохранена в конце часа, либо сессии. Так же не требуется постоянное обновление таблицы log_session (стоимость сессии и время её окончания). Для включения отложенного обновления таблиц session_detail и log_session возможно определение в узле Конфигурация тарифного плана следующих правил:

session_detail.delayed.update=1
log_session.delayed.update=1

При необходимости можно добавить только одну из строк.

Внимание

Установка опции в значение 0, равно как и в любое другое, не отключает ее! Для отключения необходимо удалить, либо закомментировать строку символом # в начале строки.

На снимке экрана ниже изображён узел в тарифном плане.

Отложенное обновление таблицы log_session может происходить только при нулевом приращении стоимости сессии. Отложенное обновление таблицы session_detail при ненулевых тарифных планах также возможно, однако следует учитывать следующие нюансы:

  • При обсчёте трафика по RADIUS-атрибутам при перезагрузке BGRadiusDialup произойдёт потеря трафика, при восстановлении сессии средства за этот трафик будут начислены повторно;

  • При тарификации трафика по NetFlow-данным в случае перезагрузки BGRadiusDialup произойдёт просто потеря накопленного счётчике в памяти трафика;

  • При использовании тарифов с узлом Диапазон наработки инициализация тарифа при старте сессии происходит по таблице session_detail, при нескольких параллельных сессиях одного договора возможна несколько некорректная тарификация. Тариф будет инициализироваться недостаточной наработкой. Проблема может быть решена переобсчётом в конце месяца всех сессий.

8.4.6. Reject-To-Accept

Замечание

Вы можете пропустть этот раздел при первичной настройке системы.

Иногда в случае неудачной авторизации нужно все равно разрешить установку сессии, но с определенными атрибутами. Например, если у клиента нет денег на счету, но соединение все равно нужно установить, чтобы пустить его к серверу статистики. Для настройки режима Reject-To-Accept в конфигурацию модуля добавьте:

reject_to_accept.<коды ошибок>=<передаваемые атрибуты>
reject_to_accept.nas=<коды nas-ов>
reject_to_accept.db.write=0

Коды ошибок авторизации доступны здесь. В случае возникновения ошибок авторизации с кодами, указанными в этой конфигурации, происходит выдача accept - пакета. Клиенту выдается адрес из пула адресов стандартным образом (в списке передаваемых атрибутов должен быть Framed-Pool=<имя пула>). Так же можно указать коды NASов, для которых производится данная подмена ответа Radius. Если это параметр не указан, то обработка производится для всех NASов.

Пример:

reject_to_accept.2,3=Session-Timeout=100;cisco-Fax-MDN-Address=1;Framed-Pool=fake_pool
reject_to_accept.4,11=Session-Timeout=200;Framed-Pool=fake_pool_2
reject_to_accept.nas=10,15

При указании параметра reject_to_accept.db.write=1 ошибки заносятся в таблицу БД dialup_reject_to_accept_<mid> для возможности перенаправления пользователя на страницу с описанием ошибки. Страница доступна по адресу: http://<ip>:<port>/bgbilling/pubexecuter?module=dialup&action=RejectToAccept&mid=<mid>, где:

<ip> - адрес сервера биллинга;
<port> - порт сервера биллинга;
<mid> - код экземпляра модуля.

При получении запроса на данную страницу пользователю генерируется HTML страница с использованием шаблона dialup_reject_to_accept_<mid>.xsl, где <mid> - код экземпляра модуля. В качестве образца поставка модуля включает шаблон dialup_reject_to_accept.xsl, который должен быть скорректирован соответсвующим образом и переименован к нужному виду. Идентификация пользователя производится по IP-адресу, с которого был произведен запрос. IP-адрес может быть передан в HTTP-заголовке, указанном в параметре header.name.remote.addr конфигурации сервера биллинга, например X-Real-IP.

Обычная схема перенаправления пользователя на страницу с ошибкой выглядит следующим образом:

  1. пользователю выдается IP-адрес из определенной сети для Reject-To-Accept соединений;

  2. маршрутизация настроена таким образом, что все обращения из данной сети перенаправляются на проксирующий HTTP-сервер, например nginx;

  3. проксирующий HTTP-сервер получает все запросы на определенном порту и проксирует их на указанный выше URL, подставляя адрес, с которого было обращение, в заголовок HTTP-запроса;

  4. сервер биллинга получает запрос на данный URL и по IP-адресу определяет пользователя, генерируя ему персональную страницу с ошибкой.

При разработке собственного XSLT-шаблона использовать следующую методику:

  1. настроить режим reject-to-accept с записью ошибок в БД, добиться создания таблицы dialup_reject_to_accept_<mid> и внесения в нее записей;

  2. изменить в таблцие dialup_reject_to_accept_<mid> какую-либо из записей с тем, чтобы поле ip было равно IP-адресу вашей машины;

  3. обратиться по URL: http://<ip>:<port>/bgbilling/pubexecuter?module=dialup&action=RejectToAccept&mid=<mid>&contentType=xml при этом страница собирается в браузере клиента, XSLT-шаблон запрашивается браузером по пути, указанному в параметре web.xslt конфигурации сервера биллинга;

  4. просмотреть исходный код страницы для просмотра XML дерева, доступного из XSLT шаблона.

Замечание

Таблица dialup_reject_to_accept_<mid> может храниться в "мусорной" базе. Для ускорения работы для данной таблицы используется тип таблиц Memory, хранимых в памяти. Для корректной работы режима перенаправления на страницу с ошибкой в списке RADIUS-атрибутов, передаваемых в accept пакете, должны обязательно быть Framed-Ip-Address и Session-Timeout, в противном случае запись в таблицу произведена не будет.

9. Настройка встроенного коллектора

Встроенный NetFlow-коллектор поддерживает NetFlow версий 1, 5 и 7 (9ая версия не поддерживается), sFlow версии 5.

Сконфигурируйте radius.properties, указав порты для приема потоков:

#размер буфера приема
#collector.capture.flow.buffer.capacity=4194304
#рекомендация размера буфера сокета
#collector.capture.flow.socket.buffer.capacity=524288
#количество потоков для порта по умолчанию
#collector.capture.flow.thread.count=10

#порт приема для netflow потока
#номер порта
collector.capture.flow.port.1=2001
#тип слушателя - netflow
collector.capture.flow.port.1.type=netflow
#количество потоков для порта
#collector.capture.flow.port.1.thread.count=8

#порт приема для sflow потока
#номер порта
collector.capture.flow.port.2=2002
#тип слушателя - sflow
collector.capture.flow.port.2.type=sflow

Коллектор может принимать данные на несколько портов, при этом на один порт может принимать данные только одного типа (netflow или sflow). Для обратной совмесимости в версией 4.6 порт типа netflow может также принимать данные sflow. Для каждого порта прописывается тип слушателя, также можно прописать количество потоков.

Опишите правила деления трафика по услугам в Конфигурации модуля.

netflow.service.link.1=23 IN 81.30.199.0 110-112
netflow.service.link.2=24 IN 81.30.199.12
netflow.service.link.3=25 OUT 0.0.0.0-255.255.255.255
netflow.service.link.4=27 IN 0.0.0.0-255.255.255.255

Читается так:Правило с приоритетом 1 к услуге с кодом 23 привязывается трафик с адреса 81.30.199.0 и с портов 110-112. Правило с приоритетом 2 к услуге с кодом 24 привязывается входящий для клиентов трафик с адреса 81.30.199.12....

Конфигурация состоит из строк следующего формата (разделители-пробелы):

netflow.service.link.<pos>=<sid> <direction> <address> <ports>

где:

<pos> - позиция правила, просмотр идёт в порядке позиций;
<sid> - код услуги, к которой привязано правило;
<direction> - ключевое слово IN или OUT, определяет тип трафика по отношению к клиенту, которое описывает правило;
<address> - один диапазон адресов, включая концы, либо одиночный адрес;
<ports> - диапазон портов, либо одиночный порт, параметр может быть пропущен.

В каждом правиле можно указать только один диапазон адресов и портов. Для добавления нескольких диапазонов последовательно располагаются несколько правил. В последних позиции должны стоять правила, в которые попадают все входящие и все исходящие пакеты (см. пример), это гарантирует вам что трафик не "потеряется" совсем.

Для того чтобы ассоциировать NAS с коллектором в биллинге добавьте в конфигурации NASа строку:

collector.agent.address=<IP адрес с которого приходит поток для NASа>

После добавления этих строк все адреса клиентов, авторизировавшихся на NASе, будут добавлены на коллекторе и по ним будет сниматься периодическая статистика по количеству потреблённых услуг.

При регистрации адреса на коллектор кроме него самого передаётся адрес агента NetFlow, с которого будет приниматься данные для этого адреса. Это сделано с целью недопущения повторного обсчёта трафика в случае, если трафик идёт от одного клиента к другому.

Для уточнения портов, на которые приходит потоки для NASа, добавьте в конфигурации NASа:

collector.agent.ports=<порты через запятую, на которые приходит статистика данного NASа>

Замечание

Для применения изменённых настроек коллектора достаточно перезапустить BGRadiusDialup, сохранить конфигурацию, модуля либо изменить что-то в списке NASов. После изменения настроек коллектора проверьте лог collector.log на предмет ошибок разбора конфигурации привязки услуг.

Если вы используете NetFlow и тарифицируете трафики с делением по типам, то для их отображения в отчёте добавьте строку в конфигурации модуля:

traffics=<sid1>/<sid2>/..<sidN>;<title1>/<title2>/..<titleN>

Например:

traffics=1/2;Внешн./Лок.

В этом случае в отчётах по сессиям клиентов через дробь будут выводится наработки по трафикам с кодами услуг 1 и 2 через дробь.Надпись "Внешн./Лок." будут добавлены в заголовок таблицы отчёта по сессиям клиента в Web. Если такая строка не указана в трафиках сессии выводятся суммарный входящий и исходящий трафики по данным RADIUS.

Для возможности предоставления детализации по сессиям необходимо установить IPN модуль, создать в нем источник, соответствующий NASу DialUP-модуля и направить на него дублирующий поток. В конфигурации NASа прописать опции:

#
ipn.module.id=<код экземпляра модуля IPN>
ipn.source.id=<код источника, соответствующего NASу>

В мониторе модуля DialUp отображается всегда трафик по данным RADIUS, использовать его для сверки цены сессий некорректно при обсчёте по данным NetFlow.

9.1. Переобработка NetFlow трафиков

Внимание

При переобработке трафиков трафики, определенные как MAX в конфигурации NASа, вычисляются как максимум записей по трафикам, из которых вычисляется максимум. В результате значения этих трафиков могут измениться после переобработки, т.к. в ходе тарификации максимум высчитывается по состоянию на каждый Update-пакет. Настоятельно рекомендуем вам сделать резервную копию таблицы session_detail_<mid>_yyyyMM перед переобработкой трафиков!

Переобработку трафиков осуществляет планировщик заданий BGScheduler, переобработка производится на основании логов формата коллектора IPN, т.е. необходимо организовать параллельный сбор логов в этом модуле, либо сконвертировать существующие логи в формат IPN-коллектора.

Путь к логам прописывается в конфигурации NASов следующим образом:

netflow.log.path=<полный путь к source-каталогу IPN-источника>

Например:

netflow.log.path=/storage/drs/drs18.ufanet.ru

Путь ищется на машине, где запущен планировщик заданий. Для запуска переобработки используется вкладка Переобработка NetFlow трафика в модуле.

Для того, чтобы переобработать трафик только по некоторым NASам в данный момент можно только комментировать строки с путём к первичным логам в конфигурации NASа. Письмо о завершении переобработки приходит на указанный E-Mail.

10. Настройка клиентов

Для того, чтобы добавить клиенту возможность использования модуля DialUp, откройте его договор, добавьте ему экземпляр модуля, выбрав узел Модули дерева договора и нажав кнопку Новый элемент стандартной панели инструментов.

Добавление разрешённых услуг модуля в договор необходимо:

  • При установке опции check.service=1 в конфигурации модуля. Клиент не сможет авторизоваться, если в договоре не будет хотя бы одной из прописанных на NASе услуг;

  • При использовании тарифных планов с узлом Диапазон в режиме пропорционально периоду разрешённой услуги. Объем пропорциональной квоты определяется долей месяца, в течении которой была разрешена услуга. Отсутствие разрешённой услуги означает полный объем;

  • При начислении максимальных трафиков, см. далее.

Откройте модуль и в список логинов добавьте новый логин. Для этого воспользуйтесь панелью инструментов, расположенной слева от списка логинов. При добавлении логина сначала нажмите Новый элемент, заполните настройки на вкладке Общие, другие вкладки по необходимости и сохраните изменения. Числовой логин выдаётся автоматически, изменить можно только алиас (замена числовому логину при входе). Числовые алиасы запрещены. Можно задать несколько алиасов, для этого перечислите их, используя пробел, как разделитель.

В основных свойствах установите период действия логина, алиас (по необходимости), ограничение по числу сессий (обязательно при выдаче статических адресов), пароль (галочка авто позволяет сгенерировать пароль автоматически длиной, заданной переменной в конфигурации модуля password.length.auto и набором символов из переменной password.chars).

Опции, устанавливаемые на прочих вкладках свойств логина и допустимые манипуляции с созданными логинами (переносы), описаны ниже.

10.1. Вкладка "IP-адрес"

На вкладке IP-Адрес задаются адреса, присваемые клиенту в момент авторизации. Адреса задаются с привязкой к реалму. Если на один реалм назначено несколько адресов, то будет не занятый адрес на каждую последующую сессию логина.

В отличие от назначения адресов указанием атрибута Framed-Ip-Address на данной вкладке осуществляется контроль совпадения адресов у разных логинов.

При назначении клиенту одного или нескольких фиксированных адресов обязательна установка лимита на количество одновременных соединений. Если на реалм установлено несколько адресов - они будут выдаваться для соединений данного логина как из пула.

10.2. Вкладка "Атрибуты RADIUS"

Вкладка Атрибуты RADIUS позволяет задавать атрибуты, такие как Framed-Ip-Address - IP-адрес, выдаваемый пользователю и Framed-Pool - пул адресов, установленный для пользователя. Атрибуты можно задавать как наборами, так и отдельными атрибутами. Все атрибуты (наборы) задаются с привязкой к REALMу.

В поле Группа REALMов укажите группу, в которую входит данный логин.

Также можно задать режим выдачи RADIUS-атрибутов логину. По умолчанию логину выдаются атрибуты, прописанные для REALMа, под которым он зашёл в конфигурации модуля DialUp + прописанные непосредственно в свойствах логина для данного REALMа. При выборе флага Только локальные глобальные атрибуты RADIUS для данного REALMа будут игнорироваться.

10.3. Вкладка "Ограничения"

Вкладка Ограничения содержит список возможных ограничений логина. Возможные ограничения: по времени доступа и работы, по телефонам доступа, по наработке денег и по наработке услуги.

Видам ограничений соответствуют следующие числовые коды:

  1. ограничение по телефону доступа (либо IP-адресу NASа, т.е. по содержимому атрибута Called-Station-Id);

  2. по времени доступа/работы (без разрыва уже установленного соединения или с разрывом);

  3. по наработке в единицах услуги;

  4. по наработке в деньгах;

  5. по телефону клиента (либо MAC-адресу, т.е. по содержимому атрибута Calling-Station-Id).

3 и 4 типы ограничений привязаны к услугам, то есть наработку можно ограничить только по каким-либо услугам.

Следует быть внимательным, программа совершенно корректно воспримет, если вы выберете в списке услуг трафик и время и ограничите их, например, 3600. То есть, сумма полученных байт и проработанных секунд будет ограничена 3600.

Для редактирования списка ограничений используется собственная панель инструментов. Каждое ограничение имеет временные маски, ограничивающие время работы ограничения.С их помощью можно ограничить различными значениями, например, трафик в обычные и в выходные дни. Значения в масках указываются через запятую. Часы - начиная с 0, все остальное - с 1. Для ограничений по времени входа временные маски задают, когда это ограничение пускает или нет. Если временные маски не указаны, ограничение работает всегда.

При авторизации ограничения сортируются по типам, просматриваются в порядке их указания, каждое последующее перекрывает предыдущее только, если оно одного типа. То есть, если вы решите пускать пользователя только на телефон 111111, то добавление ограничения Разрешить вход на 111111 ничего не даст, т.к. вход на него и так разрешён по умолчанию. Следует сделать запрет на все телефоны доступа, указав в качестве телефона *, а затем добавить строку с разрешением входа на 111111. Группировка по типам при авторизации делается для того, чтобы ограничения одного типа не перекрывали другие. То есть, если человек не прошёл по телефону доступа, его не должно пустить только потому, что доступ в это время разрешён.

Дополнительные сведения по ограничениям:

1. * означает любое значение в телефонах доступа;
2. дополнительно существуют ограничения по количеству одновременных сессий и вообще разрешение или запрет входа, они вынесены на вкладку Общие;
3. ограничения по наработке услуги или времени должны быть привязаны к списку ограничиваемых услуг;
4. любое ограничение действует только в указанный для него период действия.

Для создания ограничения нажмите кнопку Новый элемент, выберите его тип и настройте параметры, затем примените, нажав кнопку Ок. Для редактирования - выберите ограничение и нажмите кнопку Редактировать. Перемещая ограничения вверх или вниз с помощью кнопок Вверх на одну строку и Вниз на одну строку, можно изменять порядок следования ограничений, тем самым, меняя порядок их просмотра.

Замечание

Значения в счётчике ограничений начинают накапливаться только после установки ограничения на логине. Т.е. если вы поставите ограничение по наработке 600Мб на логин в середине месяца, считаться эти 600Мб начнут не с начала месяца, а с момента установки ограничения

Несколько примеров использования ограничений.

Пример 14.8. Разрешение на вход только с определённого номера (аналогично можно установить ограничение по MAC адресу).

Пример 14.9. Ограничение по времени работы

Пример 14.10. Ограничение по объёму наработки услуги "Входящий трафик"

10.4. Вкладка "Логи"

Вкладка Логи позволяет просмотреть последние сессии клиента и ошибки авторизации.

10.5. Вкладка "Пароль"

Вкладка Пароль позволяет изменить пароль доступа и посмотреть логи последних изменений.

10.6. Перенос логинов

При выборе строки в таблице логинов и нажатии правой кнопкой мыши отображается всплывающее меню.

Пункт Перенести на другой договор переносит логин из одного договора в другой (карточка должна быть открыта в текущий момент), при этом перемещается и вся наработка по данному логину. При переносе переносится наработка по логину только на период действия логина.

Пункт Перенести на другой договор с даты закрывает логин на существующем договоре и открывает аналогичный логин на целевом договоре с другим периодом. Все алиасы и свойства логина копируются. Возможен перенос только логина с неустановленной датой закрытия.

В обоих режимах перераспределение наработки между договорами происходит автоматически, но для этого должен быть запущен планировщик заданий.

11. Настройка тарифных планов

В один момент времени на договоре может действовать только один тарифный план, включающий в себя поддерево экземпляра модуля DialUp. Если у вас не было тарифного плана, создайте его, создайте для него поддерево, либо расширьте от другого тарифа. Как это сделать можете прочесть здесь. Там же описана логика работы тарифных деревьев и поведения стандартных узлов тарифных деревьев, общих для всех модулей. Логика поиска тарифа соответствует Алгоритму 1.

После того как вы откроете дерево, в нем должен отобразится узел со значком модема и названием экземпляра модуля DialUp.

В тарифном запросе модуля DialUp передаются следующие параметры:

код потребляемой услуги;
время момента потребления.

В ответе возвращаются:

стоимость услуги (обязательно);
признак акцепта (устанавливается узлом Стоимость услуги);
параметры соединения (опционально);
действия, которые нужно выполнить с соединением (опционально).

Дополнительные примеры тарифных планов модуля DialUp доступны на нашем WiKi.

11.1. Простейший тариф

Взымается 1 рубль за 60 минут нахождения в сети, 1 рубль за входящий мегабайт, исходящий трафик - бесплатный. Добавьте в узел поддерева модуля DialUP узлы типа Услуга. В эти узлы добавьте узлы типа Стоимость услуги, в которых определите сколько рублей за сколько единиц и чего вы хотите взымать.

Будьте внимательны при определении цен. Программа никак не отреагирует, если вы добавите в услугу, соответствующую входящему трафику, цену 1 рубль за 1 час. Однако это будет означать, что за каждые, потреблённые клиентом, 3600 (60*60 секунд ) байт будет снято 1 рубль, что вас вряд ли устроит. Для программы килобайты, мегабайты и минуты - всего лишь множители.

Узел Стоимость услуги при получении запроса проставляет в ответную часть параметры cost - стоимость, divisor - делитель объёма и, опционально, costType - тип услуги. Делитель определяет за какой объём услуги установлена цена (МБ, КБ, часы). Тип услуги используется в детализациях по тарифу, см. далее.

Внимание

Должны быть определены цены всех услуг, описанных в конфигурации NASа для данного соединения. В данном случае, если не указать стоимость услуги Dial-Up(исходящий), которая указана в конфигурации NASa, то при авторизации будет выходить 11 ошибка Цена не найдена.

11.2. Разделение стоимости по времени суток

Если вам необходимо варьировать цену по времени, можете воспользоваться узлами Временной фильтр и Фильтр по типу времени. Ниже приведён пример, как можно задать другую цену в выходные дни и 1 мая.

11.3. Учётные периоды

Функционал учётных периодов позволяет предоставлять услугу периодами, отвязанными от календарных месяцев. Например, безлимитный доступ на 30 дней от первого входа с однократным списанием средств. Учётный период активируется скриптом при входе абонента, если на текущий момент у него нет активированного периода. Для активации периода генерируется событие BGBS-скрипта Запрос учётного периода. Если скрипт договора не обрабатывает это событие, то предполагается работа без учётных периодов и аутентификация происходит успешно. Если скрипт есть и обрабатывает событие, то он либо возвращает новый учётный период, производя необходимые списания и т.п., либо возвращает ошибку активации периода. Примеры подобных скриптов вы можете найти на WiKi.

Замечание

Для использования учётных периодов необходима реализация BGBS-скрипта его активации. Договор может работать либо в обычном режиме, либо в режиме учётных периодов.

11.4. Зависимость стоимости от объема

Рассмотрим пример, когда первые 10 МБ входящего трафика будут идти по 1 руб., следующие 10 МБ - по 2 руб., а оставшиеся - по 3 руб.

Совершенно аналогично можно создать тарифный план с предоплаченным трафиком. В первом узле типа Диапазон указывается нулевая стоимость. Для начисления за предоплаченный трафик в модуле абонплат устанавливается абонентская плата.

Узел Диапазон может быть за день, за месяц, либо за учётный период и работать в режимах: безусловно, пропорционально периоду разрешённой услуги, пропорционально периоду действия тарифа. Разрешённые сочетания параметров и нюансы поведения узла приведены в таблице ниже. Квота базовая - это указанное в узле количество услуги. Квота - это используемое при тарификации для сравнения количество услуги.

Таблица 14.2. Логика работы узла

За периодРежимОцениваемаемый объём услугиКвота
за деньбезусловноОбъём услуги за сутки.Квота = Квота базовая.
за месяцбезусловноОбъём услуги за период действия тарифа в месяце.Квота = Квота базовая.
за месяцпропорционально периоду разрешённой услугиОбъём услуги за период действия тарифа в месяце.Квота = Квота базовая * (Количество дней с разрешённой услугой в месяце / Количество дней в месяце).
за месяцпропорционально периоду действия тарифаОбъём услуги за период действия тарифа в месяце.Квота = Квота базовая * (Количество дней действия тарифа в месяце / Количество дней в месяце).
за месяцпропорционально периоду действия тарифа (с учётом приостановленных статусов)Объём услуги за период действия тарифа в месяце.Квота = Квота базовая * (Количество дней действия тарифа в месяце с не приостановленными статусами / Количество дней в месяце).
за учётный периодбезусловноОбъём услуги за период действия тарифа в учётном периоде.Квота = Квота базовая.
за учётный периодпропорционально периоду разрешённой услугиОбъём услуги за период действия тарифа в учётном периоде.Квота = Квота базовая * (Количество дней с разрешённой услугой в учётном периоде / Количество дней в учётном периоде).
за учётный периодпропорционально периоду действия тарифаОбъём услуги за период действия тарифа в учётном периоде.Квота = Квота базовая * (Количество дней действия тарифа в учётном периоде / Количество дней в учётном периоде).
за учётный периодпропорционально периоду действия тарифа (с учётом приостановленных статусов)Объём услуги за период действия тарифа в учётном периоде.Квота = Квота базовая * (Количество дней действия тарифа в учётном периоде с не приостановленными статусами / Количество дней в учётном периоде).

Если клиент исчерпает разрешённые в тарифном плане объёмы, тарификация прекратится и услуга более ему не будет предоставляться. Таким образом, можно создавать ограничивающие тарифные планы. Ниже приведён пример плана, разрешающего потреблять клиенту 5МБ в течение суток.

Логика работы узла Диапазон следующая:

В запросе узел получает количество услуги amount, которое необходимо протарифицировать.
Оценивается текущее значение счётчика услуги в узле для данного договора и квота, в данном узле может быть протарифицирован объём MIN (amount, КВОТА - ТЕК. ЗНАЧЕНИЕ). Если в данном узле значение счётчика ещё не достигло квоты, то запрос посылается внутрь узла, откуда должна возвратиться стоимость единицы услуги узлом Стоимость услуги и быть установлен флаг акцепта. Возможный объём тарифицируется, значение amount в запросе уменьшается, увеличивается значение параметра ответа costAmount.
Текущее значение счётчика для договора в узле увеличивается отдельным запросом после запроса получения цены. Передаётся тарифный init запрос с протарифицированным объёмом услуги amount и узлы последовательно "разбирают" объём наработки, увеличивая счётчики.

По итогам обработки тарифного запроса RADIUS либо процесс переобсчёта реагируют либо на параметр costAmount в тарифном ответе, либо на cost и divisor (устанавливает узел Стоимость услуги). Поэтому при оценке услуги диапазонами недопустимо размещать цену вне диапазона. Например, вместо такого тарифа.

Недопустимо определять цену по умолчанию следующим образом.

11.5. Комбинированные зависимости

Возможно совместное использование различных типов узлов. Например, тарификация по диапазонам трафика дневного и ночного. Первые 5Мб дневного трафика и 10Мб ночного идут бесплатно, далее - по 1 руб.

11.6. Детализация по тарифу

Детализация по тарифу позволяет в счетах модуля бухгалтерии разделить наработку по какой-либо из услуг, посчитанных по различным ценам или условиям. Например, можно вынести в отдельные строки счета бесплатный входящий трафик и платный трафик. Суть метода состоит в определении категорий услуги в конфигурации модуля и указании их в выпадающем списке узла Стоимость услуги. В результате каждая протарифицированная единица услуги относится к той или иной категории.

О детализации по тарифу написано подробно в документации по настройки позиций модуля бухгалтерии.

11.7. Использование узла "Мультиуслуга"

Вместо нескольких узлов Услуга возможно создание узлов типа Мультиуслуга. Данный узел аналогичен по функциям узлу Услуга, но пропускает в себя запросы цены для нескольких указанных в нем услуг. Использование данного узла целесообразно для:

  • указания в одном узле цен для нескольких услуг с одинаковой стоимостью

  • создания тарифов с квотами трафика, в которых начальная квота общая для нескольких услуг

Рассмотрим оба этих случая в едином примере:

В данном примере стоимость услуг исходящих трафиков равна 0. На услуги входящего локального и внешнего трафиков выделена общая бесплатная квота 3МБ, при превышении которой входящий внешний трафик тарифицируется по 1 руб/Мб, а локальный по 0.5 руб/Мб.

11.8. Указание в тарифе свойств соединения

В тарифных планах возможна установка наборов RADIUS-атрибутов, передаваемых в AUTH ACCEPT-пакете. Например, это может использоваться для заужения канала клиента в зависимости от потреблённого им трафика в течении месяца. Пример подобного тарифа приведён ниже. Наборы передаваемых RADIUS-атрибутов должны быть предаварительно настроены в конфигурации модуля.

При получении тарифного запроса узел передаёт в ответную часть набор атрибутов, который должен быть установлен. С использованием флага перекрыть остальные (см. далее) узел может удалять из ответной части установленные ранее наборы атрибутов.

Недостаток приведенного примера в том, что атрибуты передаются только при авторизации. При прохождении порога 100Мб по ходу соединения ничего не произойдет, до следующей авторизации клиент будет работать на большой скорости.

Для выполнения каких-либо действий при необходимости изменения свойств соединения используются зоны. Нижеприведенный пример разделяет весь потребленный объем на две зоны, при этом переход из одной зоны в другую вызывает разрыв соединения и, как следствие, повторную авторизацию. Разрыв необходимо настроить в обоих зонах, т.к. в начале месяца происходит переход в первую зону.

Помимо разрыва соединения при смене зон возможна отправка CoA запроса, в том случае, если в качестве инспектора соединений для NASа указан PoD инспектор, а NAS поддерживает PoD и CoA-запросы. В этом случае нужно выбрать действие Отправить CoA.

При установке в поле Событие BGBS любой строки при переходе на данную зону генерируется событие Тарифная зона изменилась, которое можно обработать скриптом поведения. При этом строка передаётся в событии.

При прохождении тарифного запроса узел Зона проставляет свой идентификатор в ответную часть. RADIUS отслеживает смену зоны по ходу соединения и выполняет те действия, которые указаны в новой зоне. Также данный узел можно использовать для разрыва соединений при переходе между разными временами суток с различной скоростью канала. Сброс должен быть установлен в обеих зонах.

Важно понимать, что смена зоны происходит только при очередном обсчёте, который, в свою очередь, при Update режиме тарификации происходит по Accounting Update пакету. В случае, если зоны изменяются по времени, они должны быть установлены в узле услуги типа "Время". В случае, если они меняются от объема потребленного трафика - в узле услуги типа "Трафик". Это связанно с алгоритмом тарификации, а именно с тем, что трафик всегда считается потреблённым единой "порцией" в момент предыдущего Update-пакета. Время же при переходе часа обсчитывается двумя "порциями": в момент предыдущего Update-пакета считается потреблённым время до границы часа, и на начало часа учитывается потребление остатка времени. Поэтому, если вы установите зоны, которые должны изменяться по времени в услугу по трафику, то реально действие произойдёт при втором Update-пакете после наступления нужного часа.

Обратите внимание на флаг Перекрыть остальные в узле Набор RADIUS атрибутов. Необходимость данного флага можно рассмотреть на следующем примере тарифа. Пусть при смене зон отправляется CoA-пакет.

Без установки этого флага набор атрибутов просто добавляется в тарифный запрос. В результате по приведённому выше тарифу, но без установки этого флага при очередном обсчёте трафика по Update-пакету в ответе тарифного запроса вернутся два набора атрибутов (часть трафика будет обсчитана по 0 руб. а остаток по 1 руб.), которые и будут отправлены в CoA-пакете. При установке же данного флага, последний набор атрибутов удалит информацию о предыдущем в результате будет отправлен только набор Канал 128. При изменении зоны по времени наличие данного флага не принципиально по описанным чуть ранее причинам, связанным с различными алгоритмами обсчёта времени и трафика.

Вот ещё один пример тарифа, когда после смены зоны отправляются уже два набора атрибутов Канал 128 и Канал WiFi 256/128.

При отправке CoA используются стандартно набор(ы) атрибутов, полученные из тарифа при очередном обсчёте. Однако в реальности зачастую необходима также повторая отправка атрибутов логина и релама. В этом случае в конфигурации NASа при настройке PoD-инспектора необходима установка опции nas.inspector.coa.send.all.attributes=1. При установке данного флага в CoA-пакете будут отправлены атрибуты, аналогичные отправляемым в Auth Accept-пакете: из свойств логина, реалма. Также будут добавлены все наборы атрибутов, полученные из тарифного плана при последнем обсчёте.

Изменение зон может быть отслежено только в пределах тарификации одной услуги. Однако, зачастую могут быть ситуации, когда требуется изменять параметры доступа в зависимости от нескольких услуг. Например, в приведённом ниже примере скорость входящего и исходящего канала понижаются независимо. Обратите внимание на префикс с двоеточием перед названием зоны. Это группа зон. RADIUS отслеживает смену зон в каждой из групп и при этом выполняет действия, указанные в новой зоне. Если бы вместо "группа:зона" в данном тарифе использовались просто зоны, то при превышении наработки 200 Мб входящего и исходящем меньше 100 Мб возникало бы противоречие в зонах.

Всвязи с наличием возможности изменения в тарифном плане свойств соединения возникает необходимость обработки ситуации смены тарифного плана по ходу работы сессии. Штатно логика обработки события изменения тарифных планов договора во время активной сессии описана ниже.

При смене тарифа разрывается соединение только, если в результате смены:

  1. изменился текущий действующий тариф, его нужно в общем случае переинициализировать, если есть узлы Дипазон наработки;

  2. правился сам тарифный план в справочнике текущего действующего тарифа, при этом идёт загрузка тарифного дерева заново и, опять таки, нужно переинициализировать узлы Диапазон наработки;

  3. не стало тарифа на текущую дату.

Также производится разрыв соединения, если в ходе обсчёта начал использоваться тариф, отличный от предыдущего (начались новые сутки). Однако этот сброс можно отключить опцией no.session.break.on.tariff.change=1 в конфигурации экземпляра модуля, котроллируя разрыв/CoA, когда нужно зонами в тарифах, т.к. смена зон ослеживается и при переходе на другой тариф.

11.9. Уровни

Зачастую необходима возможность управления глобально свойствами текущих соединений. Например, уменьшение пропускной способности каналов активных пользователей, но только в моменты пиковой загрузки внешнего канала. Для этого в BGRadiusDialup реализована возможность сопоставления договорам неких абстрактных чисел - уровней. Если договору не сопоставлен уровень, то он считается нулевым. Сопоставление осуществляется командой set_levels на сокет управления RADIUS-сервера с указанием перечня договоров и уровней.

Формат команды: set_levels\n<levels>, где <levels> - набор записей <код договора>\t<уровень>\n

Например, передача извне файла с уровнями levels, содержащего уровни для договоров с кодами 4 и 5:

4\t1 
5\t2

Может быть осуществлена следующим образом (BGRadiusDialup установлен на локальной машине и его admin.port=1955):

echo ./levels | nc 127.0.0.1 1955

После выполнения команды set_levels для договоров, уровень которых не был передан, он становится нулевым. Переданные уровни сохраняются в файле levels в каталоге BGRadiusDialup, для возможности восстановления после перезагрузки BGRadiusDialup. Логика формирования уровней полностью отдана стороннему приложению. Пример подобного управляещего скрипта вы можете посмотреть в WiKi.

В биллинге уровень передаётся в тарифный запрос при каждом обсчёте и воспринимается узлом Фильтр по уровню. В соответствии с уровнем могут изменяться зоны и текущие параметры соединения. Ниже приведён пример подобного тарифного плана.

11.10. Тарифные опции

В зависимости от активированных опций можно менять логику тарифа. Ветка Тарифные опции отрабатывает, если в момент обсчета одна из указанных в ветке опций активна. В случае срабатывания одной из веток, последующие этого же уровня не отработают, даже, если указаны те же опции. Отсутствие указанных опций означает, что ветка отработает в том случае, если не было срабатывания ветки Тарифная опция выше.

Для того, чтобы сделать повышение скорости на период, можно создать такой тариф:

При отсутвии активированных опций запрос попадет во вторую ветку и отработает зона "normal". При активации опции Турбо супер, запрос попадет в первую ветку и зона сменится на "turbo". Логику работы с зонами можно изучить выше.

Внимание

Следует учитывать, что в модуле DialUp наработка хранится по часам, поэтому, если в зависимости от тарифной опции меняется цена, то активация тарифной опции не должна быть в режиме "часов (с текущего момента)" (как исключение, можно установить разрыв соединения), также не должна быть в режиме "с текущего часа/дня/недели/месяца", чтобы цена прошедшего времени не изменялась. Если же в зависимости от тарифной опции выполняется только посылка CoA, то режим "часов (с текущего момента)" может быть использован.

11.11. Тарифы с переоценкой всего потребленного трафика

Занесение бонусов при смене зон актуально для создания тарифов, при которых трафик переоценивается за весь объем.

Получив 200 мегабайт по 2 рубля, клиент тратит 400 рублей. После этого тарификация переходит в другую зону, с ценой по 1.86 за мегабайт. Бонус 28 рублей компенсирует траты клиента по 14 копеек на 200 мегабайт, так что теперь можно считать, что весь трафик он полностью получал по 1.86 руб.

И в тарифе для клиента можно указывать, что при наработке свыше 200 мегабайт трафик считается по 1.86. Аналогично происходит переход на тариф по 1.5 руб за мегабайт.

Внимание

При переобсчете сессий с подобными тарифами платежи не проводятся повторно и не корректируются на правильные. Занесение платежей происходит только непосредственно в момент тарификации.

11.12. Ограничение по NASам

В тарифном плане можно устанавливать ограничение по NASам, на которых может работать пользователь. Ограничение производится узлом Фильтр по NASам.

11.13. Узел "Конфигурация тарифа"

Редактор узла представляет собой простое текстовое поле для введения стандартных конфигураций вида "ключ=значение".

Позволяет передавать RADIUS-серверу различные параметры, влияющие на работу с базой данных.

11.13.1. Блокировка отправки атрибутов REALMа

Производится флагом конфигурации not.send.realm.attributes=1. Это аналогично установке в свойстве логина отправки только локальных атрибутов.

11.13.2. Фильтр по RADIUS-атрибутам пакета авторизации

Также возможна установка ключей-фильтров по RADIUS-атрибутам пакета авторизации, что позволяет ограничивать авторизацию с REGEXP фильтром по RADIUS-атрибутам. Фильтры указываются следующим образом:

radius.auth.attr.filter.<filter_number>=<attr_name>=<regexp>

Где:

<filter_number> - порядковый номер фильтра, просмотр фильтров идёт по номерам;
<attr_name> - название RADIUS-атрибута, совпадающее с указанным в файле dictionary.xml;
<regexp> - REGEXP фильтр по атрибуту.

Так, для добавления фильтра по атрибуту Calling-Station-Id из шести цифр необходимо добавить:

radius.auth.attr.filter.1=Callind-Station-Id=\d{6}

Все фильтры соединяются условием И, т.е. должно выполняться выполнение всех указанных фильтров.

12. Переобсчёт соединений

Для переобсчёта сессий задним числом при ошибке в тарифных планах, либо неверно установленных планах для клиентов воспользуйтесь вкладкой Начисление. Задачу переначисления выполняет планировщик заданий, он должен быть запущен.

В простейшем случае для переобсчёта сессий достаточно выбрать месяц, ввести E-Mail для оповещения о завершении обсчёта и нажать Запуск. Левая область вкладки предназначена для переобсчёта сессий, правая - для переначисления за максимальные трафики.

Дополнительно возможна установка фильтра по договору, группам договоров и периоду в днях, когда начинались сессии. По завершению переначисления на указанный E-Mail будет выслано письмо с отчётом и темой письма DialUp session recalculate.

13. Монитор соединений

Вкладка Монитор предназначена для мониторинга работы DialUP модуля. Монитор работает в 3х режимах:

Ошибки - отображает ошибки авторизации пользователей;
Логи - логи соединений;
Текущие - текущие соединения по данным из БД.

Для переключения режимов вывода используются соответствующие кнопки.

Режимы Логи и Ошибки поддерживают фильтр по времени, ряд кнопок в верхней области позволяет смотреть ошибки и логи за 0-1 часа назад, 1-2 часа, либо произвольные сутки.

В таблице логов и текущих соединений отображаются время начала и окончания сессий, номер звонящего и вызываемый номер (атрибуты Calling-Station-Id, Called-Station-Id RADIUS-авторизации). Информация о принятых и отправленных байтах отображается на основании данных из RADIUS Update-пакетов.

Сортировка соединений производится по дате начала для режимов Логи и Текущие и в обратном порядке для режима Ошибки. Поддерживается постраничный просмотр, при переключении режима отображается первая страница. Для постоянного мониторинга какой-либо из страниц нажимайте кнопку Обновить стандартной панели инструментов.

При двойном клике по строке таблицы показывается RADIUS-лог соединения.

При нажатии правой кнопкой мыши по выбранной строке таблицы появляется контекстное меню, позволяющее как открыть договор, которому соответствует строка лога, либо просмотреть логи RADIUS-соединения.

В режиме Логи и Текущие возможно послать сигнал сброса сессии через контекстное меню. При этом возможно использование команд Сбросить (послать сигнал на сброс сессии и ждать STOP-пакета) и Закрыть (принудительное закрытие соединения).

Команда Сбросить означает попытку принудительного разрыва соединения пользователя и, далее, закрытие его по приходу Stop-пакета с NASа. Команда Закрыть предназначена для удаления "Висящих соединений", которые точно не присутствуют на NASе и не тарифицируются RADIUS-сервером. Рекомендуется всегда сначала пытаться сбросить соединение и ждать корректного Stop-пакета, а удаление применять только для "зависших" соединений.

При вызове команд управления сервер биллинга обращается к RADIUS-серверу через порт управления, для чего в конфигурации модуля DialUP должна быть установлена опция radius.manage=<IP>:<PORT> где <IP> - адрес RADIUS-сервера, <PORT> - его порт управления. (см. конфигурацию модуля по-умолчанию).

В левой верхней области монитора расположено окно поиска, позволяющее найти клиента по номеру договора, логину, либо алиасу. При выборе строки в таблице с результатами поиска в мониторе будут отображаться логи и текущие соединения только выбранного логина и ошибки выбранного логина, либо неопознанного логина (ошибка Логин и карта не найдены). По найденному договору отображается краткая информация над таблицей (название, текущий режим и баланс).

Для всех режимов доступен фильтр по NASам в левом нижнем угле, при не выбранных NASах отображается сводная информация по всем шлюзам доступа.

В режиме просмотра ошибок монитор отображает договор (если он был найден), дату и время, логин (атрибут User-Name), IP-адрес NASа и описание ошибки. Для исключения ошибок Логин и карта не найдены предусмотрена галочка в фильтре.

Перечень типов ошибок в мониторе и их расшифровка:

Таблица 14.3. Таблица кодов ошибок

Код ошибкиНазваниеОписание
1Неверный пин-код картыКарта найдена, но введённый пароль не соответствует её пин-коду.
2Неверный пароль логинаЛогин найден, но введённый пароль не соответствует его паролю.
3Тарифные планы не найденыУ договора не установлен ни один тарифный план для данного модуля на день авторизации.
4Ошибка балансаОстаток баланса договора меньше лимита договора.
6NAS не найденRADIUS-пакету не сопоставлен NAS в модуле.
7Не найден код услугиВ конфигурации NASа не определены коды услуг.
8Карта просроченаИстёк период годности карты.
9Карта заблокированаКарта не передана дилеру.
10Карта активирована на балансКарта уже активирована для пополнения баланса.
11Цена не найденаНа одну или несколько услуг, заявленных в конфигурации NASа, не найдена цена в тарифном плане.
12Ошибка сохранения соединенияВ RADIUS-пакете отсутствует атрибут NAS-Port, что помешало сохранить объект соединения.
14Логин и карта не найденыНе найдены ни логин, ни карта по данным пакета.
17Невозможно активировать карту на этом NASекарта не может быть активирована на данном NASе, её услуга активации не прописана в параметре card.activate.service конфигурации NASа.
18REALM запрещёнИспользование данного REALM запрещено для группы логинов логина.
19Услуга запрещенаВ конфигурации модуля установлена опция check.service=1, в услугах договора нет одной или нескольких услуг, определённых в конфигурации NASа для данной авторизации.
21Превышен лимит сессийУ логина установлено ограничение на число одновременных сессий, оно уже исчерпано.
22Запрещён вход на данный телефонУ логина установлено ограничение на телефон доступа (Called-Station-Id).
23Запрещён вход в это времяУ логина установлено ограничение по времени входа, либо работы.
24Превышен лимит услугиУ логина установлено ограничение по объёму услуги.
25Превышен лимит наработкиУ логина установлено ограничение по денежной наработке.
26Доступ заблокированДоступ логина установлен в Запрещён.
27Запрещён вход с данного телефонаУ логина установлено ограничение на телефон звонящего (Calling-Station-Id).
31Ошибка установки расчётного периодаОшибка получения нового учётного периода из скрипта.
33Договор не активенСтатус договора не позволяет авторизовать логин
34NAS запрещёнЗапрещена авторизация на данном NASе узлом тарифного дерева Разрешённые NASы.
35Истек срок жизни карточного договораУ договора, для создания которого активирована карта, закончился период действия.

Возможно изменение текста отображаемой ошибки, для этого в конфигурации модуля указывается:

error.message.code.<code>=<название>

Где <code> - код ошибки, <название> - отображаемое в таблице название.

14. Интеграция с модулем "Карточки"

Для того, чтобы ваш модуль DialUp смог работать с карточками необходимо в конфигурации модуля в параметре card.module.id указать числовой код модуля Карточки.

Каждая карточка имеет три параметра: серийный номер (уникальный, не должен повторятся ), логин и пароль. При первом звонке клиента-карточника для него создаётся договор. Шаблон имени договора может быть определён в шаблоне договора. Если шаблон имени не указан, то договор именуется К{логин}-YY, где YY - год создания. На этот договор заносится логин и пароль с карты.

Если карта уже активирована другим модулем, например Voip, то в уже существующий договор будет добавлен логин и пароль DialUP модуля. Данный подход позволяет выпускать универсальные карты, по которым можно одновременно получать несколько видов сервиса.

Далее подключение идёт по обычной схеме. Следует уделить особое внимание неперекрытию диапазонов логинов обычных и карточных. Дело в том, что при обычном создании логины создаются последовательно, карточные же просто переносятся из карты.

Поэтому над диапазоном обычных логинов должен быть запас, т.е. карточные логины должны начинается с 10000 или выше, чтобы не произошло пересечения.

Чтобы узнать незанятые логины в диапазоне используйте вкладку Свободные логины в модуле DialUp.

В верхнем окошке выбирается диапазон, в котором вы хотите выбрать свободные логины, галочка Исключить карточки позволяет исключить загруженные карты из диапазона.

Выбрав свободные логины, сгенерируйте для них пароли и серийные номера (они не должны повторятся ), после чего можете загрузить в модуле "Карточки".

Возможно разграничение типов карт по NASам, можно разрешить активировать на каждом NASе только карты с определёнными кодами услуг активации, перечислив их через точку с запятой в переменной card.activate.service конфигурации NASа (например: 1;4;5). Значение 0 означает, что на данном NASе можно активировать карты любого типа. Если переменная не указана для NASа, то активация карт на NASе запрещена.

15. Отчёты

Для просмотра отчётов, связанных с пользователем, откройте договор и выберите вкладку Отчёты. В нижнем ряде вкладок выберите интересующий экземпляр модуля DialUp.

Трафики, выводимые в отчётах, берутся либо по данным RADIUS, либо из переменной traffics конфигурации модуля (см. настройку встроенного NetFlow коллектора). Имеется возможность распечатки и сохранения сессий (в HTML или в CSV-формате) и наработки, а также отправки на E-mail. Чтобы иметь эту возможность, в конфигурации модуля должны быть верно настроены URL-адреса шаблонов преобразования XSL, отвечающих за оформление информации для печати или отправки на Email. Шаблон xslt.1 - оформление сессий, xslt.2 - наработок. При необходимости можно модернизировать эти файлы, меняя оформление. Для отправки сессий на E-mail также должны быть настроены опции почты в файле конфигурации сервера биллинга.

15.1. Отчёт по сессиям, детализация

Для просмотра сессий выберите интересующий логин (ы), единицы измерения, месяц и интервал дней. Для выбора нескольких логинов используйте кнопки Ctrl и Shift. Доступные логины отображаются в зависимости от указанного периода - отображаются только те логины, период которых пересекается с указанным интересующим периодом. Затем нажмите кнопку с галочкой. При выборе месяца можно проматывать месяцы назад и вперёд с помощью кнопок со стрелками.

Правой кнопкой мыши вызывается контекстное меню выбранной сессии. Возможно просмотреть RADIUS-лог сессии, либо получить детализацию по трафику.

RADIUS-лог сессии также можно просмотреть двойным кликом по строке сессии.

15.1.1. Детализация трафика за сессию

Для получения детализации должны быть произведены настройки. Детализацию предоставляет коллектор модуля IPN на основании бинарных логов трафика. При выборе пункта контекстного меню Получить детализацию необходимо указать E-Mail адрес на который будет отправлена детализация.

Стандартная детализация за сессию представляет из себя одно или несколько писем с приложенным архивом detail.zip. Архив содержит CSV-файл с частью детализации. Размер максимального возможного detail.zip в одном письме задается переменной ipn.collector.detail.max.attach.size в файле netflow_ipn.properties. По умолчанию значение переменной составляет 4000000 байт. Каждое письмо сопровождается темой Session traffic detail [N], где N - увеличивающийся порядковый номер. Последнее письмо данной детализации снабжено темой Session traffic detail [LAST] и содержит простейшую аналитику: на какие и с каких адресов был максимальный трафик.

Можно заменить стандартную детализацию, для этого необходимо указать в netflow_ipn.properties

ipn.collector.detail.class=bitel.billing.server.netflow.ipn.detail.AnalyzedFlowDetailMaker

Данный класс создания детализации кроме стандартного csv добавляет в архив detail.zip html-файл с графиком и анализом.

Детализация в этом случае будет приходить одним письмом, разбиения в данный момент не предусмотрено.

15.1.2. Детализация трафика за месяц

Также можно получить детализацию за месяц по логинам. Получение детализации по логинам возможна только при условии настройки детализации по сессиям.

Детализация сохраняется в файл. Каталог, куда будет выкладываться детализация на сервере, прописывается в настройках коллектора в файле netflow_ipn.properties. Названия каталогов на разных коллекторах могут отличаться, но все коллекторы должны ссылаться на один каталог.

ipn.collector.detail.folder=/home/billing/detail

15.2. Отчёт по наработке логинов

Для просмотра наработки по логинам достаточно выбрать месяц и период.

16. Web-интерфейс

Через Web-интерфейс модуля DialUp имеется возможность просмотра сессий клиента по логинам, наработки по логинам и учётных периодов логинов. Имеется возможность доступа к Web-статистике по логину и паролю DialUp. Пример подобной настройки смотрите здесь.

Чтобы отредактировать названия пунктов меню в Web-интерфейсе модуля используйте параметры web.menuItem1 - web.menuItem4 в конфигурации модуля.

По умолчанию все пункты меню названы применительно к DialUp, что может не соответствовать истине, если модуль используется для предоставления VPN доступа.

В отчёте по сессиям также есть возможность получения детализации на e-mail. Для предоставления пользователю такой возможности должны быть установлены настройки NASов.

17. Начисление наработки за максимальные трафики

Начисление наработки за максимальные трафики осуществляется дополнительно к основной тарификации модуля периодически в ручном режиме, либо, используя планировщик. В конфигурации модуля должны быть определены зависимости услуг, представляющих собой максимальные трафики, например:

max.traffic.74=39,40

В данном случае услуга с кодом 74 представляет собой максимум между услугами с кодами 39 и 40.

Начисление осуществляется по следующему алгоритму:

  1. выбираются все договоры с разрешённой услугой типа "Максимальный трафик" за обсчитываемый месяц;

  2. выбираются действующие у клиента тарифные планы в период действия услуги, получая наборы: договор - услуга - тариф - период;

  3. для каждого пункта набора осуществляется тарификация, причём дата в тарифном запросе передаётся равной последнему дню набора.

Пример 14.11. Пример логики работы

Предположим что у нас есть договор Х, у которого с 3 сентября по 20 сентября разрешена услуга Макс. трафик 1. Предположим также, что в течении сентября у договора был Тариф1 с 1 по 10 сентября и Тариф2 с 11 по 30 сентября.

В данном случае будут обсчитаны две позиции:

  1. услуга Макс. трафик 1 вычисленная на период с 1 по 10 по тарифу Тариф1

  2. услуга Макс. трафик 1 вычисленная на период с 11 по 30 по тарифу Тариф2

Для начисления максимальных трафиков можно использовать ручной режим, используя вкладку Начисление модуля.

Для автоматического начисления необходимо настроить задачу Максимальные трафики DialUP в планировщике задач. В конфигурации задачи должно быть установлено:

mid=<код модуля>

Как и обсчёт логов IPN, задача берет месяц, отнимая час от текущего времени. Это позволит вам обсчитать все трафики по окончанию месяца, если запуск задачи будет установлен на 0 часов 55 минут последующего месяца. При этом необходимо настроить сброс сессий пользователей на границе месяца.

18. Динамическое управление DNS-сервером

Применение динамического DNS решает проблему серверов пользователей с динамическим адресом (например, игровых). По старту сессии BGRadiusDialup может регистрировать имя хоста с адресом, назначенным для сессии клиента, разрегистрация производится по стопу сессии.

Есть три режима работы динамического ДНС:

1) выключен;
2) по логину входа (имя хоста получается из логина, под которым зашёл пользователь, заменой @ на -);
3) по цифровому логину (в качестве имени хоста используется цифровой логин, при входе под реалмом к цифровому логину добавляется тире и реалм).

Пример 14.12. Пример

Под динамически управляемую зону провайдер выделил vpn.prov.com. Пользователь с цифровым логином 777 входит в сеть под логином vasya@local, ему присваивается имя хоста vasya-local и его компьютер будет доступен из сети под именем vasya-local.vpn.prov.com. В случае использования режима по цифровому логину имя будет присвоено 777-local.vpn.prov.com, даже если он зашел под алиасом vasya.

Имя хоста всегда приводится к нижнему регистру. В случае нескольких сессий под одним логином каждая последующая сессия "перехватывает" хост на себя, разрегистрация хоста происходит по стопу последней "перехватившей" сессии.

18.1. Пример настройки DNS сервера

Рассмотрим по шагам настройку динамической зоны совместно с DNS-сервером bind. Для примера взята зона dyn.ufanet.ru, NS сервер - ns2.ufanet.ru, 81.30.199.70 - IP-адрес RADIUS-сервера.

1) Запустить утилиту rndc-confgen для генерации случайного ключа.

[root@shamil ~]# rndc-confgen
# Start of rndc.conf
key "rndckey" {
        algorithm hmac-md5;
        secret "T92pAc/L6HM4tQUPi/vu+Q==";
};

options {
        default-key "rndckey";
        default-server 127.0.0.1;
        default-port 953;
};
# End of rndc.conf

# Use with the following in named.conf, adjusting the allow list as needed:
# key "rndckey" {
#       algorithm hmac-md5;
#       secret "T92pAc/L6HM4tQUPi/vu+Q==";
# };
#
# controls {
#       inet 127.0.0.1 port 953
#               allow { 127.0.0.1; } keys { "rndckey"; };
# };
# End of named.conf

2) Добавить в named.conf записи о разрешении управлением DNS с адреса RADIUS-сервера и описание самой зоны. Ключ скопирован из вывода rndc-confgen.

key "dyndns" {
        algorithm hmac-md5;
        secret "T92pAc/L6HM4tQUPi/vu+Q==";
};

controls {
       inet 127.0.0.1 port 953
                 allow { 127.0.0.1; } keys { "dyndns"; };
       inet 81.30.199.67 port 953
                 allow { 81.30.199.70; } keys { "dyndns"; };
};

zone "dyn.ufanet.ru" {
        type master;
        file "dynamic/dyn.ufanet.ru";
        allow-update { key "dyndns"; };
};

3) В файле dynamic/dyn.ufanet.ru (путь относительно каталога в котором расположен named.conf) описать саму зону.

$ORIGIN .
$TTL 600        ; 10 minutes
dyn.ufanet.ru           IN SOA  ns2.ufanet.ru. root.ufanet.ru. (
                                20345026   ; serial
                                28800      ; refresh (8 hours)
                                7200       ; retry (2 hours)
                                604800     ; expire (1 week)
                                600        ; minimum (10 minutes)
                                )
                        NS      ns2.ufanet.ru.
$ORIGIN dyn.ufanet.ru.

18.2. Пример настройки модуля

Для включения динамического DNS, согласно предшествующему примеру настройки DNS-сервера, необходимо внести в конфигурацию модуля:

# Динамический DNS
dyn.dns.zone=dyn.ufanet.ru.
dyn.dns.resolver=ns2.ufanet.ru
dyn.dns.shared.key.name=dyndns
dyn.dns.shared.key.value=T92pAc/L6HM4tQUPi/vu+Q==
dyn.dns.ttl=600

#параметры для логина
login.parameter.1.name=dialup.dns
login.parameter.1.title=Тип ДНС
login.parameter.1.type=5
login.parameter.1.default=0
login.parameter.1.listValue=Выключен;Цифровой логин;Логин входа

Опции login.parameter.* определяют в модуле параметр спискового типа с именем dialup.dns. В БД параметр сохраняется как число от 0 до 2, которым соответствуют текстовые обозначения от Выключен до Логин входа в примере. Текстовые обозначения могут быть изменены. Опция login.parameter.1.default определяет, какое значение имеет параметр по умолчанию. Соответственно, можно включить по умолчанию динамический DNS всем логинам, установив опцию в 1 или 2.

Имя параметра dialup.dns является ключевым для BGRadiusDialup, который получает из значения данного параметра режим работы динамического DNS для логина. После настройки модуля необходим перезапуск BGRadiusDialup.

18.3. Пример настройки логина

Во вкладке Параметры логина должен появится параметр, созданный в конфигурации модуля. Его переключение изменяет режим динамического DNS для логина.

Клиент имеет также возможность самостоятельно управлять режимом динамического DNS через Web-интерфейс, пункт меню Управление динамическим ДНС (либо иное название, прописанное в конфигурации модуля).

19. Настройка автозакрытия соединений

Признаком "висящего" соединения для RADIUSа является его неактивность при наличии активных соединений на этом же NASе. Автозакрытие следует использовать в случае, если закрытие по приходу аутентификации на порт невозможно (например, если в NAS-Port идёт код сессии).

Для автозакрытия соединений, "висящих" более часа при наличии активных соединений на этом же NASе, добавьте в конфигурацию NASа строку:

drop.sleep.timeout=3600

Замечание

Используйте автозакрытие очень осторожно, т.к. неверно удалённое соединение из RADIUS не обсчитывается сервером. Не рекомендуется ставить таймаут автозакрытия менее 3600 секунд.

20. Поддержка CallBack

Механизм CallBack нужен в ситуации, когда используется повременная оплата телефонной связи. При соединении CallBack после авторизации клиента на NASе происходит обратный звонок клиенту.

В конфигурации NASа опция callback.support должна быть установлена в 1.

В этом случае за звонок платит провайдер, а оплата звонков для юр.лиц, в большинстве своём, фиксированная. Чтобы сообщить NASу о необходимости перезвонить, нужно установить для клиента набор атрибутов RADIUS.

Атрибуты могут меняется в зависимости от оборудования, ниже приведён пример для Ascend Max6060.

Ascend-Assign-IP-Pool = 1
Ascend-CBCP-Enable = 0 (CBCP-Enabled) (кстати, для Unix-подобных =1, а для Microsoft=0)
Ascend-CBCP-Mode = 7 (CBCP-Any-Or-No)
Ascend-CBCP-Trunk-Group = 9
Ascend-Client-Primary-DNS = 212.110.226.2
Ascend-Data-Svc = 42 (Switched-modem)
Ascend-Send-Auth = 0 (Send-Auth-None)
Service-Type = 2 (Framed-User)

Для определения набора атрибутов для другого оборудования обратитесь к документации производителя.

21. Настройка RADIUS-сервера с различными шлюзами CISCO

BGRADIUS-сервер способен взаимодействовать с любыми шлюзами CISCO, поддерживающими авторизацию и аккаунтинг по протоколу RADIUS и SNMP-управление с поддержкой AAA-SESSION-MIB.

При настройке pppoe-сервера CISCO возможна проблема: в атрибуте NAS-Port постоянно идёт 0. Что недопустимо, т.к. BGRadius использует этот атрибут для идентификации соединения.

Для того, чтобы обойти это, выполните команду:

radius-server attribute nas-port format e UUUUUUUUUUUUUUUUUUUUUUUUUUUUUUUU

(всего 32 буквы U).

Теперь CISCO будет слать в атрибуте NAS-Port код сессии, что обеспечит его уникальность.

Однако, при этом возникает проблема "зависших" соединений. Т.к. NAS-Port постоянно уникален, то в случае не получения RADIUSом STOP-пакета, он не будет знать о том, что соединение закончилось.

Обычно "висящие" соединения закрываются RADIUSом, как только на порт приходит авторизация, но в этом случае авторизация на такой же порт придёт не скоро. Чтобы зависшие сессии удалялись автоматически, настройте автозакрытие.

При настройке экспорта NetFlow желательно указать опции:

ip flow-cache timeout active 1
ip flow-cache timeout inactive 10

Это заставит шлюз слать потоки чаще, тем самым обеспечивая более "живой" обсчёт в биллинге.

22. Настройка WiFi-агента для работы с модулем Dialup

22.1. Описание WiFi-агента

WiFi-агент предназначен для манипулирования клиентами в WiFi-сетях. Он взаимодействует с сервером BGBilling и RADIUS-сервером для передачи информации о появлении клиента , его уходе и актуальном времени сессии. Также он управляет маршрутизатором. Общая схема взаимодействия может быть представлена на следующей диаграмме :

В данный момент WiFi-агент и WiFi-портал реализованы одним приложением и поднимаются на машине маршрутизатора. Это решение работает только для ОС семейства Linux. Пользователь выходит в WiFi-сеть, по dhcp получает ip-адрес с DHCP-сервера, установленного в этой сети, и через точку доступа попадает на маршрутизатор, на котором стоит ОС Linux со службой iptables. Iptables настраивается таким образом, что по умолчанию для клиента закрыты все порты кроме порта, на котором весит WiFi-портал. Все запросы на 80-ый порт перебрасываются на страницу портала, на которой пользователь вводит логин и пароль для доступа к WiFi-сетям. Страница авторизации имеет такой вид :

Пользователь водит логин/пароль.

Далее Портал обращается к RADIUS-серверу и шлёт на него авторизационный radius-пакет. Если авторизация проходит успешно (в ответ получен radius-пакет подтверждения авторизации), то портал шлёт об этом запрос WiFi-агенту. WiFi-агент, в свою очередь, шлёт стартовый radius-пакет на RADIUS-сервер и меняет правила iptables, разрешая пользователю выйти в интернет. После успешной авторизации пользователя перекидывают на сервисную страницу :

На эту страницу пользователь может попасть всегда (даже после авторизации), зайдя на http://192.168.184.39:9090 (путь зависит от настроек). Здесь он видит свой баланс, ссылку на первоначальный ресурс , который он набирал до того, как его перенаправили на страницу авторизации. Также есть альтернативная ссылка на эту страницу через https.

Сессия клиента может быть завершена следующими способами :

1. Клиент зашёл на страницу портала и нажал кнопку "выйти";

2. Клиент исчерпал свой баланс и RADIUS-сервер послал сообщение WiFi-агенту о завершении работы клиента с данным ip;

3. WiFi-агент, периодически проверяющий (в текущий момент через каждые 60 сек) состояние счётчиков iptables, определит, что клиент был неактивен в течение некоторого времени;

В случае завершения работы (не важно каким из выше перечисленных способов) WiFi-агент пошлёт Stop-пакет Radius-серверу и удалит разрешающие правила iptables для нужного ip-адреса.

C точки зрения модуля DialUp WiFi-агент выступает как NAS. В текущий момент он поддерживает следующие возможности :

1. Режим работы NAS в режимах UPDATE и CHECKER (dialup.workmode);

2. Тарификация с помощью любых тарифов (по времени, по трафику), которые можно завести в системе BGBilling и которые поддерживаются модулем DialUP. Для обсчёта трафика на маршрутизаторе нужно поднять NetFlow-агент (описание настройки Radius-сервера тут ). Также клиент имеет возможность выбора REALMов сразу на странице авторизации;

4. Доступ к статистике клиента и все возможности, которые предоставляет модуль DialUp для Web-интерфейса и клиента BGBilling (мониторинг сессий и т.п);

4. Возможно ограничение скорости (Шейпинг) каналов в зависимости от атрибутов, переданных RADIUS-сервером;

5. Вызов внешних скриптов при входе и выходе пользователя в сеть, что позволяет сжимать каналы в зависимости от тарифа или сбрасывать установленные соединения, или выполнять любые другие действия;

6. Защита WiFi-сети от ARP-спуффинга;

7. Функция восстановления пароля через почтовый ящик клиента;

8. Возможность взаимодействия с модулем Карточки, т.е. возможность активации карты с последующей авторизацией по этой карточке в сети WiFi;

9. Возможность клиента работать с https-версией портала.

22.2. Установка, настройка и запуск

В текущий момент WiFi-агент и WiFi-портал реализованы одним приложением, которое и называется WiFi-агент. Для его установки его нужно скачать с сайта и распаковать в какую-нибудь папку .Например, в папку /user/local. Далее для простоты будем считать, что мы установили в эту папку.

При установке рекомендуется идти от простого к сложному . Т.е. вначале заставить работать более простую конфигурацию, а потом уже пытаться добавлять дополнительные возможности.

Далее идут шаги, необходимые, для установки.

1) Для работы WiFi-агента нужна Java-машина.

2) Все настройки агента хранятся в файле dialup_wifi_agent.properties. Вот пример этого файла :

#wifi agent class
wifi.agent.class=ru.bitel.bgbilling.modules.dialup.wifi.DialupWiFiAgent

#mq options
mq.url=failover:(nio://127.0.0.1:61616?socketBufferSize=1000000)
mq.user=bill
mq.pswd=bgbilling

#radius options
radius.auth.host=127.0.0.1
radius.auth.port=1812

radius.account.host=127.0.0.1
radius.account.port=1813

radius.nasId=den_nas
radius.secret=hello

#Слать update-пакеты на Accounting-сервер (1  по умолчанию)
radius.update.send=1

#billing server options
billing.server.login=admin
billing.server.passwd=admin
billing.server.http.url=http://localhost:8080/bgbilling
#billing.server.https.url=https://localhost:8443/bgbilling
billing.server.moduleId=XXX

billing.server.show.statistics=0
billing.server.password.remind=0

#portal options
portal.http.port=9090
#portal.https.port=9091
#portal.https.keystore.password=bgbilling
#portal.card.link=http://127.0.0.1:8080/bgbilling/pubexecuter?action=CreateContract&module=card&mid=5&activateType=1

#tariff options
#portal.use.realm=1
#portal.tarif.1.realm=wifi_128_128
#portal.tarif.1.title=128 kb/s
#portal.tarif.2.realm=wifi_256_128
#portal.tarif.2.title=256 kb/s

portal.http.url=http://localhost:9090
#portal.https.url=https://localhost:9091


#wifi agent options
wifi.agent.port=5555
wifi.agent.port.admin=5556

wifi.agent.radius.live.time=60000
wifi.agent.client.live.time=24000000

wifi.agent.arp.command=/sbin/arp
#wifi.agent.server.https=1

#radius attributes
#wifi.agent.radius.atrubute.1.vendor.code=1111
#wifi.agent.radius.atrubute.1.attr.code=1
#wifi.agent.radius.atrubute.1.type=integer
#wifi.agent.radius.atrubute.2.vendor.code=1111
#wifi.agent.radius.atrubute.2.attr.code=2
#wifi.agent.radius.atrubute.2.type=integer


#dhcp options
#dhcp=1
#dhcp.server.host=192.168.184.254
#dhcp.server.port=67
#dhcp.agent.host=192.168.184.39
#dhcp.minThreadCount=10
#dhcp.maxThreadCount=10

#возможность использования символьных ссылок на файлы портала  
#portal.allow.linking=1
#обработка ssi (обрабатываются shtml файлы )
#portal.use.ssi=1

Установите переменную billing.server.moduleId=<числовой код экземпляра модуля DialUp>. При необходимости скорректируйте параметры доступа к БД и к MQ-серверу.

А теперь остановимся более подробно на каждой настройке.

radius.auth.host, radius.auth.port - хост и порт, на котором поднят Radius-сервер авторизации;

radius.auth.port, radius.account.port - хост и порт, на котором поднят Radius-сервер аккаунтинга (возможно у вас поднят один Radius-сервер на одном хосте для авторизации и аккаунтинга, но порты будут отличаться);

radius.nasId - Идентификатор NASа;

radius.secret - секретный ключ для NASа (как настроить NAS для WiFi-агента будет описано ниже);

radius.update.send - Слать update-пакеты на Accounting-сервер. По умолчанию включено;

billing.server.login, billing.server.passwd - логин и пароль доступа к серверу (те же самые, что используются в клиенте биллинга). Нужны для получения баланса пользователя. Данный пользователь должен быть заведён в системе и обладать правами на действия из группы : "Dial-Up->WiFi". О том как администрировать пользователей читайте здесь;

billing.server.http.url, billing.server.https.url - URL сервера биллинга (тот же самый, по которому обращается клиент биллинга). Соответственно для http и https. Если https-соединение не нужно, то не указывайте billing.server.https.url;

billing.server.moduleId - код модуля DialUp на BGBilling-сервере, c которым будет работать этот агент;

billing.server.show.statistics - показывать ли ссылку на статистику сервера (1- показывать; 0 - не показывать, стоит по умолчанию ). При этом, если в текущий момент клиент работает c порталом по http, то для него эта будет ссылкой на http-версию статистики, а если он работает по https с порталом, то это будет ссылка на https версию статистики;

billing.server.password.remind - показывать ли ссылку на страницу напоминания пароля (1- показывать; 0 - не показывать, стоит по умолчанию ).Если этот флаг установлен в 1, то в конфигурации модуля DialUp должен быть указан параметр mail.contract.param.code - код параметра договора, в котором задаётся e-mail адрес клиента;

portal.http.port, portal.https.port - порты портала для обычного и безопасного соединения. Если https-соединение не нужно, то не указывайте portal.https.port;

portal.https.keystore.password - пароль для https-соединения. Для работы https-соединения нужен файл .keystore (основанный на этом пароле), который необходимо положить в папку агента. Как получить этот файл описано здесь. Если https-соединение не нужно, то не указывайте этот параметр;

portal.http.url, portal.https.url - URL портала для http и https-соединений. Это URL, по которому будут обращаться клиенты WiFi-сети, чтобы попасть на сервисную страницу. Если https-соединение не используется, то параметр portal.https.url не указывается;

wifi.agent.port - это порт, на котором будет подниматься wifi_agent и RADIUS-сервер будет обращаться к этому порту;

wifi.agent.port.admin - порт для управления WiFi-агентом;

wifi.agent.radius.live.time - время жизни (в миллисекундах) клиента с точки зрения Radius-сервера. Т.е. это время неактивности клиента, через которое Radius-сервер считает, что сессия не активна и останавливает подсчёт по ней. По умолчанию стоит одна минута. Активность клиента проверяется по изменению счётчиков iptables в цепочке WIFI (о том, как настроить iptables читайте ниже);

wifi.agent.client.live.time - время жизни (в миллисекундах) клиента с точки зрения WiFi-агента. Т.е. это время неактивности клиента, через которое WiFi-агент считает, что клиента больше нет, сбрасывает сессию клиента (отсылает stop-пакет Radius-серверу, очищает iptables, вызывает внешние скрипты). По умолчанию стоит 40 минут. Активность клиента проверяется по изменению счётчиков iptables в цепочке WIFI (о том как настроить iptables читайте ниже);

wifi.agent.arp.command - путь к команде arp в ОС Linux. Она нужна для получения mac-адреса клиента и манипулирования arp-таблицами (в случае настойки защиты от ARP-спуффинга). По умолчанию обычно /sbin/arp;

wifi.agent.server.https - использовать или нет при взаимодействии между WiFi-агентом и сервером протокол https (1 - https; 0-http, стоит по умолчанию);

3) Для работы внешних скриптов нужно настроить файл conf.sh (часть этих настоек дублируется в dialup_wifi_agent.properties). Пусть у нас имеется Linux-маршрутизатор c двумя сетевыми интерфейсами: eth0 - локальный (сеть 172.16.1.0/24, через него выходят клиенты WiFi), eth1 - внешний интерфейс для выхода в интернет (имеет внешний ip - 81.30.199.220).

#путь к Java-машине, установленной в системе
JAVA_HOME=/opt/java/jre
#порты портала для обычного и безопасного соединения 
PORTAL_HTTP_PORT=9090
PORTAL_HTTPS_PORT=9091
#это порт? на котором будет подниматься WiFi-агент и RADIUS-сервер будет обращаться к этому порту.
WIFI_AGENT_PORT=5555
#имя цепочки iptables, в которой будут храниться разрешающие правила для клиентов.
WIFI_CHAIN_NAME=WIFI
#интерфейс, на котором происходит подсчёт клиентов WiFi-сети
WIFI_INTERFACE=eth0
#внешний интерфейс
EXTERNAL_INTERFACE=eth1
#внешний IP
EXTERNAL_IP=81.30.199.220
#сеть клиентов WIFI
WIFI_NET=172.16.1.0/24

4) Необходимо сделать запускаемыми все скрипты в папке агента . Для этого надо перейти в эту папку и выполнить команду :

chmod 755 *.sh *.pl

5) Настроить скрипты входа/выхода абонента.

login.sh - сюда добавляются команды открытия доступа для авторизовавшегося клиента . В этот скрипт в качестве параметра передаётся ip пользователя и атрибуты RADIUS, полученные в accept-пакете (настройка атрибутов описана ниже).

Скрипт имеет такой вид в стандартной поставке:

#!/bin/sh
cd ${0%${0##*/}}.
. ./conf.sh

IP=$1
DOWNSTREAM_SPEED=$2
UPSTREAM_SPEED=$3

date  >> ./log/manad.out
echo `/sbin/iptables -I $WIFI_CHAIN_NAME 1 -t nat -j ACCEPT -s $IP` >> ./log/manad.out 2>&1
echo `/sbin/iptables -I $WIFI_CHAIN_NAME 1 -t nat -j ACCEPT -d $IP` >> ./log/manad.out 2>&1


if [ $USE_MANAD -eq 1 ]; then
./tell_manad.pl "add $IP $DOWNSTREAM_SPEED $UPSTREAM_SPEED" $MANAD_PORT
fi

#use it for shaping
#./shape.sh $IP $PARAM1 $PARAM2

logout.sh - сюда добавляются команды закрытия доступа для клиента . В этот скрипт в качестве параметра передаётся ip пользователя. Скрипт имеет такой вид в стандартной поставке:

!/bin/sh
cd ${0%${0##*/}}.
. ./conf.sh


IP=$1

date  >> ./log/manad.out

echo `/sbin/iptables -D $WIFI_CHAIN_NAME -t nat -j ACCEPT -s $IP` >> ./log/manad.out 2>&1
echo `/sbin/iptables -D $WIFI_CHAIN_NAME -t nat -j ACCEPT -d $IP` >> ./log/manad.out 2>&1


if [ $USE_MANAD -eq 1 ]; then
./tell_manad.pl "remove $IP" $MANAD_PORT
fi


6) Настроить скрипт проверки активности клиента - ip_counts.pl. Скрипт поставялется в стандартной поставке и расчитан на парсинг цепочки с разрешающми правилами . На выходе скрипт выдает данные вот в таком формате

192.168.185.10 13423 6878 
192.168.185.20 133423 6878

Тут для каждого ip, найденного в цепочке, выводится информация о входящих (первый солбец) и исходящих байтах (второй столбец) на этот адрес . Столбцы разделены символом табуляции . Стандартный скрипт раcчитан на работу со стандартным файлом login.sh, считывает счетчики iptables из цепочки WIFI. Скрипт можно менять, главное, чтобы выходной формат оставался такой же, как описан выше.

7) Необходимо настроить iptables. По умолчанию WiFi-агент при старте системы инициализирует правила в системе с помощью скрипта iptables.sh. Рекомендуется все ваши настойки iptables также помещать в этот скрипт. Этот скрипт также может использовать администратор для очистки правил и сбрасывания всех текущих клиентов. Вот пример этого скрипта:

#!/bin/sh  
cd ${0%${0##*/}}.
. ./conf.sh


/sbin/iptables -F -t nat
/sbin/iptables -F -t filter

/sbin/iptables -P PREROUTING DROP -t nat


#external interface ##################################################################################### 
#ssh 
/sbin/iptables -A PREROUTING -s ! $WIFI_NET -t nat -p tcp --dport 22 -d  $EXTERNAL_IP -j ACCEPT
#drop others from external interface
/sbin/iptables -A PREROUTING -s ! $WIFI_NET -t nat -j DROP
#end of external interface ################################################################# 



#internal interface ################################################################################################### 

#before wifi chain we must add redirects for authorized users  
/sbin/iptables -A PREROUTING  -t nat -p tcp --dport 80 -d $EXTERNAL_IP -j REDIRECT --to-ports $PORTAL_HTTP_PORT 
/sbin/iptables -A PREROUTING  -t nat -p tcp --dport 443 -d $EXTERNAL_IP -j REDIRECT --to-ports $PORTAL_HTTPS_PORT 


#chain for  WiFi  (accept rules for authorized users) 

/sbin/iptables --delete-chain $WIFI_CHAIN_NAME -t nat
/sbin/iptables -N $WIFI_CHAIN_NAME -t nat
/sbin/iptables -A PREROUTING  -j $WIFI_CHAIN_NAME -t nat

#below is rules for internal not authorized users : 

#dns   
/sbin/iptables -A PREROUTING  -t nat -p udp --dport 53 -j ACCEPT

#http  
/sbin/iptables -A PREROUTING  -t nat -p tcp --dport 80 -j REDIRECT --to-ports $PORTAL_HTTP_PORT 
/sbin/iptables -A PREROUTING  -t nat -p tcp --dport $PORTAL_HTTP_PORT -j ACCEPT

#https  
/sbin/iptables -A PREROUTING -t nat -p tcp --dport 443 -j REDIRECT --to-ports $PORTAL_HTTPS_PORT 
/sbin/iptables -A PREROUTING -t nat -p tcp --dport $PORTAL_HTTPS_PORT -j ACCEPT

#statistics 
/sbin/iptables -A PREROUTING  -t nat -p tcp --dport 8080 -d $EXTERNAL_IP -j ACCEPT


# NAT 
iptables -A POSTROUTING -o $EXTERNAL_INTERFACE  -s $WIFI_NET -j SNAT -t nat --to-source $EXTERNAL_IP

#RST packets for dropping estblished connections  
/sbin/iptables -A FORWARD -p tcp  -j REJECT --reject-with tcp-reset

Этот скрипт нужно поправить под ваш случай. В процессе работы правила будут иметь вид :

# iptables -L -t nat -n
Chain PREROUTING (policy DROP)
target     prot opt source               destination         
ACCEPT     tcp  -- !172.16.1.0/24        81.30.199.220       tcp dpt:22 
DROP       all  -- !172.16.1.0/24        0.0.0.0/0           
REDIRECT   tcp  --  0.0.0.0/0            81.30.199.220       tcp dpt:80 redir ports 9090 
REDIRECT   tcp  --  0.0.0.0/0            81.30.199.220       tcp dpt:443 redir ports 9091 
WIFI       all  --  0.0.0.0/0            0.0.0.0/0           
ACCEPT     udp  --  0.0.0.0/0            0.0.0.0/0           udp dpt:53 
ACCEPT     tcp  --  0.0.0.0/0            0.0.0.0/0           tcp dpt:9090 
ACCEPT     tcp  --  0.0.0.0/0            0.0.0.0/0           tcp dpt:9091 
ACCEPT     tcp  --  0.0.0.0/0            81.30.199.220       tcp dpt:8080 

Chain POSTROUTING (policy ACCEPT)
target     prot opt source               destination         
SNAT       all  --  172.16.1.0/24        0.0.0.0/0           to:81.30.199.220 

Chain OUTPUT (policy ACCEPT)
target     prot opt source               destination         

Chain WIFI (1 references)
target     prot opt source               destination         
ACCEPT     all  --  172.16.1.105         0.0.0.0/0      
ACCEPT     all  --  172.16.1.57          0.0.0.0/0      
ACCEPT     all  --  172.16.1.94          0.0.0.0/0


# iptables -L -t filter -n
Chain INPUT (policy ACCEPT)
target     prot opt source               destination         

Chain FORWARD (policy ACCEPT)
target     prot opt source               destination         
REJECT     tcp  --  0.0.0.0/0            0.0.0.0/0           reject-with tcp-reset 

Chain OUTPUT (policy ACCEPT)
target     prot opt source               destination         

Chain RH-Firewall-1-INPUT (0 references)
target     prot opt source               destination

Очень не рекомендуется заносить правила в цепочку WIFI, т.к. она редактируется автоматически и могут возникнуть проблемы. Свои дополнительные правила вы можете заносить в любые другие цепочки и таблицы (учитывая логику работы iptables и WiFi-агента).

Например, если Radius-сервер находится на другой машине, то ему надо разрешить 5555-ый (в данном случае) порт для обращения к WiFi-агенту. Аналогично можно разрешить порты для ssh и т.п., если это необходимо. На шлюзовой машине, где устанавливается агент, скорое всего, будет, как минимум, один внешний интерфейс и один внутренний интерфейс, через который будут работать клиенты WiFi. В этом случае, например, если по ssh будут обращаться только через внешний интерфейс, можно повесить разрешающие правила на внешний интерфейс. Вариантов много, но главное чтобы выход во внешнюю сеть был закрыт для клиентов локальной сети по умолчанию. Одним из вариантов организации сети может быть набор виртуальных (vlan) интерфейсов, которые будут заведены на данной шлюзовой машине (на интерфейсе eth0) и агент будет добавлять правила для всех клиентов этих виртуальных сетей. В этом случае агент может управлять сразу многими локальными сетями, которые могут быть физически разнесены далеко друг от друга.

Замечание

Отметим, что для правильной работы сети кроме правила NAT, добавленного выше, в случае ОС Linux необходимо ещё включить ipforwarding. Для дистрибутива Fedora необходимо поставить net.ipv4.ip_forward = 1 в /etc/sysctl.conf и выполнить команду echo 1 >> /proc/sys/net/ipv4/ip_forward (чтобы изменения немедленно применились). Рекомендуется вначале проверить работу точки доступа и выход в интернет через неё, прежде чем применять запрещающие правила iptables, описанные выше.

8) Установить скрипт service/bgwifiagent_dialup как службу. Для этого нужно скопировать файл bgwifiagent_dialup в /etc/rc.d/init.d и потом вызвать следующие команды

chmod 755 /etc/rc.d/init.d/bgwifiagent_dialup
chkconfig --add bgwifiagent_dialup
chkconfig --level {lev} bgwifiagent_dialup on

Где {lev}- это уровень запуска в вашей системе. Узнать его можно так:

[root@king ~]# runlevel
N 5

Т.к. агент изменяет правила iptables, то в системе он должен запускаться с правами root-а.

9) В файле setenv.sh нужно прописать JAVA_HOME;

10) Перед запуском агента нужно запустить скрипт

./update.sh

в папке агента. Это обновит все библиотеки на нем (скачает с сервера).

11) Для запуска агента можно выполнить команду:

service bgwifiagent_dialup start

Агент не запуститься, если не будет связи с сервером BGBilling или там не будет установлены лицензии на модуль Dialup или сам портал.

12) Подсоединиться клиентом к серверу биллинга, настроить NAS для работы с нашим агентом. В конфигурацию NAS нужно добавить:

#интервал между посылками на вышибание клиента
nas.inspector.sleep_time=60
#числовые коды услуг времени, трафика входящего и исходящего
nas.port_time.default.*=109
nas.port_traffic.default.*=111:COLLECTOR

nas.inspector.class=bitel.billing.server.processor.WiFiConnectionInspector
nas.inspector.wifi.host=127.0.0.1
nas.inspector.wifi.port=5555

Здесь вы должны указать хост и порт, на котором работает агент. RADIUS-сервер будет периодически обращаться к нему, проверять активность клиента и слать сигнал о завершении работы в случае завершения баланса клиента. При этом вы должны сделать идентификатор NASа равным параметру radius.nasId , а секретный ключ NAS-а равный radius.secret.

13) Установить RADIUS-сервер для модуля DialUp . Настройки радиуса должны совпадать с параметрами radius.auth.host, radius.auth.port, radius.account.host, radius.account.port в файле dialup_wifi_agent.properties.

22.3. Связь WiFi-агента с модулем "Карточки".

Если у вас установлен модуль "Карточки", то портал может отображать ссылку на активацию карты. Для этого в конфигурационном файле dialup_wifi_agent.properties вы должны прописать строку

portal.card.link=http://127.0.0.1:8080/bgbilling/pubexecuter?action=CreateContract&module=card&mid=5

Формат этой ссылки описан в документации по модулю Карточки.

22.4. Защита WiFi-сети от ARP-спуффинга

ARP-spoofing (ARP-poisoning) — техника сетевой атаки, применяемая преимущественно в Ethernet, но возможная и в других, использующих протокол ARP, сетях, основанная на использовании недостатков протокола ARP и позволяющая перехватывать трафик между узлами, которые расположены в пределах одного широковещательного домена. Суть её состоит в том, что любой желающий может посылать ARP-запросы, подменять таким образом ARP-таблицы на других компьютерах и сопоставлять свой mac-адрес c чужим ip-адресом.

Одним из методов защиты является использование статических ARP-таблиц, т.е. запрет на изменение ARP-таблицы. Именно это решение мы предлагаем для использования в нашем WiFi-агенте. Для этого внутри WiFi-агента реализуется ещё одно приложение - DHCP relay-агент. По описанию протокола DHCP (RFC 2131) сервер DHCP может отвечать не только на запросы клиентов на получение ip-адреса, но и на запрос relay-агентов, которые пробрасывают запросы клиентов на сервер (проставляя свой адрес, чтобы сервер мог им ответить) , а ответ отправляют клиенту. Таким образом обычно реализуется возможность получения ip-адресов, если DHCP сервер находится в другой сети и часто роль relay -агентов выполняют аппаратные шлюзы. Мы используем программный relay-агент для того, чтобы при получении ip-адреса от DHCP-сервера редактировать arp-таблицу на шлюзе (где установлен WiFi-агент) и для удаления записи из arp-таблицы по истечению срока аренды ip-адреса (который задаётся DHCP-сервером и проставляется клиенту, а клиент, в свою очередь, обязан до истечения срока аренды послать запрос на продление ip-адреса). Динамическое обновление arp-таблицы отключается и никто другой не может править arp-таблицу, кроме DHCP relay-агента.

Для запуска DHCP-агента нужно в файл dialup_wifi_agent.properties добавить следующие настройки:

#dhcp options
dhcp=1

dhcp.servers.1.host=192.168.184.254
dhcp.servers.1.port=67

dhcp.servers.2.host=192.168.184.253
dhcp.servers.2.port=67

dhcp.agent.host=192.168.154.39
dhcp.minThreadCount=10
dhcp.maxThreadCount=10

dhcp.servers.1.host=192.168.184.254
dhcp.servers.1.port=67

Здесь

dhcp=1 - это флаг, говорящий о том, что нужно запускать DHCP агент.

Далее идут настройки dhcp-серверов. Поддерживается несколько серверов (<id> - 1,2,3 и т.п. ):

dhcp.server.<id>.host - ip-адрес сервера DHCP. Он нужен relay-агенту.

dhcp.server.<id>.port - порт, на котором запускается сервер DHCP. Вообще, стандартным портом для сервера DHCP является 67-ой. Но в данном случае, возможно, вам понадобиться изменить этот порт . Например, если DHCP-агент и DHCP-сервер находятся в одной локальной сети . В этом случае они оба будут получать широковещательные dhcp-запросы клиентов на получение ip-адреса и сервер будет отправлять ответы клиентам напрямую . Нам же нужно, чтобы запрос приходил только к DHCP-агенту, а агент его уже пробрасывал на сервер. Этого можно добиться с помощью организации сети или ещё какими-либо другими способами, но один из вариантов - это поднять сервер на другом порту, чтобы он не получал запросы клиентов на 67-ом. Стандартный сервер dhcpd позволяет это сделать . В этом случае вам понадобится изменить этот параметр.

dhcp.agent.host - ip-адрес DHCP-агента, на который потом будет отвечать DHCP-сервер. Это адрес проставляется в dhcp-запрос, который проходит через relay-агент.

dhcp.minThreadCount, dhcp.maxThreadCount - это минимальное и максимальное количество потоков в пуле при обработке запросов от клиентов и серверов DHCP. Эти параметры можно оставить по умолчанию.

dhcp.arp.command - путь к команде arp в ОС Linux. Она нужна для манипулирования arp-таблицами. По умолчанию обычно /sbin/arp.

Для отключения динамического обновления arp-таблицы нужно выполнить команду

ifconfig eth0 -arp 

При этом нужно посмотреть какие адреса уже попали в эту таблицу и, при необходимости, её отредактировать (например, добавить адреса каких-либо серверов в локальной сети, которые имеют статический ip).

22.5. Настройка ограничения скорости (шейпинг) для трафика WiFi-сети.

Шейпинг осуществляется с помощью iproute2. Его реализация происходит через внешние скрипты и настраиваемые атрибуты Radius-сервера, получаемые в accept-пакете. Вы можете реализовать свой вариант или изменить наш под ваши нужды. Общий принцип такой :

1. Скрипт init.sh( вызывается при старте системы) - в нем можно проводить инициализацию правил шейпинга;

2.login.sh - сюда добавляются правила шейпинга для нового клиента, появившегося в сети. В это скрипт в качестве параметра передаётся ip пользователя и атрибуты RADIUS, полученные в accept-пакете (настройка атрибутов описана ниже);

3.logout.sh - здесь удаляются правила шейпинга при выходе клиента из сети. В этот скрипт в качестве параметра передаётся ip пользователя.

Мы вам предлагаем свой вариант реализации этих скриптов. Для корректной работы этого варианта в системе должен быть установлен perl. Для его конфигурации надо добавить в файл conf.sh следующие строчки:

USE_MANAD=1
MANAD_INTERFACE=eth0
MANAD_PORT=4567

Здесь USE_MANAD=1 обозначает, что будет использоваться шейпинг, MANAD_INTERFACE - это интерфейс, на котором будет контролироваться трафик клиента и MANAD_PORT - порт, на котором будет слушать перловый скрипт wifi_manad.pl, управляющий шейпингом . Этот скрипт слушает на определённому порту команды на удаление и добавление нового клиента . При добавлении клиента, например, с ip 192.168.184.33, скоростью входящего трафика (downstream ) - 256 кбит/сек, скоростью исходящего трафика (upstream) -128 кбит/сек, он добавляет для него следующие правила :

/sbin/tc class add dev eth0 parent 1:0 classid 1:3 htb rate 256kbit burst 4k prio 1 
/sbin/tc qdisc add dev eth0 parent 1:3 handle 3: sfq perturb 10 quantum 1500 
 
/sbin/tc class add dev eth0 parent 1:0 classid 1:4 htb rate 128kbit burst 4k prio 1 
/sbin/tc qdisc add dev eth0 parent 1:4 handle 4: sfq perturb 10 quantum 1500 
 
/sbin/tc filter add dev eth0 parent 1:0 protocol ip prio 3 u32 match ip dst 192.168.184.33  flowid 1:3 
 
/sbin/tc filter add dev eth0 parent 1:0 protocol ip prio 4 u32 match ip src 192.168.184.33 flowid 1:4

А при удалении клиента 192.168.184.33 скрипт выполняет следующие команды:

/sbin/tc filter del dev eth0 parent 1:0 protocol ip prio 3
/sbin/tc filter del dev eth0 parent 1:0 protocol ip prio 4

/sbin/tc class del dev eth0 parent 1:0 classid 1:3 htb rate 256kbit burst 4k prio 1
/sbin/tc class del dev eth0 parent 1:0 classid 1:4 htb rate 128kbit burst 4k prio 1

Для правильной работы данного скрипта нужно настроить RADIUS-атрибуты, которые мы хотим получить из accept-пакета от RADIUS-сервера . В данном случае нас интересует два атрибута: ограничение входящей скорости (downstream) и значение исходящей скорости (upstream). Для этих атрибутов в файл в dialup_wifi_agent нужно добавить следующие настройки:

wifi.agent.radius.atrubute.1.vendor.code=1111
wifi.agent.radius.atrubute.1.attr.code=1
wifi.agent.radius.atrubute.1.type=integer
wifi.agent.radius.atrubute.2.vendor.code=1111
wifi.agent.radius.atrubute.2.attr.code=2
wifi.agent.radius.atrubute.2.type=integer

Формат добавления атрибутов следующий:

agent.radius.atrubute.X. - общий вид.

X - это код атрибута. Нумерация должна идти по порядку - 1, 2 и т.д . vendor.code - код производителя , attr.code - код атрибута, type - тип атрибута. Атрибуты настраиваются в файле dictionary.xml Radius-сервера и WiFi-портала (там тоже есть такой файл), и для данного примера можно добавить, например, такие атрибуты:

<vendor code="1111" name="linuxWiFi">
  <attribute add="no" name="WiFi-Downstream-Speed-Limit" type="integer" code="1"/>
  <attribute add="no" name="WiFi-Upstream-Speed-Limit" type="integer" code="2"/>
</vendor>

В конфигурация модуля DialUp нужно добавить группы атрибутов :

attrset.4.title=Канал WiFi 256/128
attrset.4.attributes=WiFi-Downstream-Speed-Limit=256;WiFi-Upstream-Speed-Limit=128

Сами группы атрибутов можно задать:

1. для каждого логина DialUp;

2. для услуги в тарифе.;

3. для REALMа (можно использовать, например, realm.default для всех пользователей).

Значения атрибутов, описанных в файле dialup_wifi_agent.properties в точно в таком же порядке (после ip-адреса), подаются в качестве параметров в скрипт login.sh, вызываемый после установки пользователем соединения.

22.6. Настройка REALMов

Клиент при авторизации может использовать REALMы. Список доступных REALMов может отображаться клиенту в виде выпадающего списка :

Пусть, мы хотим использовать 2 REALMа: входящий трафик 128 кбит/с и 256 кбит/с. Исходящий же трафик в обоих случаях пусть будет 128 кбит/сек. Для добавления этой возможности нужно добавить следующие настройки в файл dialup_wifi_agent.properties:

#tarif options
portal.use.realm=1
portal.tarif.1.realm=wifi_128_128
portal.tarif.1.title=128 kb/s
portal.tarif.2.realm=wifi_256_128
portal.tarif.2.title=256 kb/s

В конфигурацию модуля для этого случая нужно добавить :

realm.wifi_128_128=WiFi-Downstream-Speed-Limit=128;WiFi-Upstream-Speed-Limit=128
realm.wifi_256_128=WiFi-Downstream-Speed-Limit=256;WiFi-Upstream-Speed-Limit=128
realmgr.default=default;wifi_128_128;wifi_256_128

В конфигурацию NASа нужно добавить

nas.port_time.wifi_128_128.*=112
nas.port_traffic.wifi_128_128.*=

nas.port_time.wifi_256_128.*=113
nas.port_traffic.wifi_256_128.*=

Где 112 и 113 - коды услуг обсчёта данных REALMов (в данном примере обсчёт только по времени). Эти услуги должны быть добавлены в тариф (читайте настройку тарифов).

22.7. Web-интерфейс

Web-интерфейс WiFi-портала сделан с помощью jsp и располагается в каталоге portal. Также используются технологии jstl и struts.

Глава 15. Модуль DrWeb

1. Назначение модуля

Модуль автоматизирует работу с Dr.Web AV-Desk. Позволяет пользователям подписываться на услугу, менять тариф, блокировать на время и прекращать подписку. Производит списание наработки с баланса пользователя в соответствии старифами. В настоящий момент поддерживаться версия Dr.Web AV-Desk 5 c API2.0.

2. Базовые понятия и алгоритм работы модуля

При запросе агента через web интерфейс пользователя, проверяется наличие достаточного количества денег, после чего посылается запрос на сервер Dr.Web AV-Desk, полученная ссылка показывается пользователю для загрузки агента.

Задача планировщика "Обработка задач Dr.Web (режим 1)",выполняет несколько задач.

  • За определенное количество дней до конца месяца проверяет наличие необходимых средств на балансе и продлевает подписки на следующий месяц. В случае нехватки средств, выполняется запрос на сервер, ограничивающий срок подписки последним днем текущего месяца;

  • При поступлении денег на счет пользователя, у которого прекращена подписка из-за нехватки денег, продлевает подписку;

  • В первые дни месяца посылает запрос на изменение тарифа для пользователей, которые инициировали смену тарифа.

Задача планировщика "Начисление Dr.Web", выполняет начисление наработки, по акивным агентам.

3. Установка и настройка модуля

Модуль устанавливается с помощью утилиты bg_installer, после чего создаётся его экземпляр и прописываются необходимые услуги.

На вкладке Конфигурация создайте и установите конфигурацию модуля.

#ссылка на api2 для сервера AVDESK
drweb.api.url=http://localhost:9080/api/2.0/
#логин для доступа к серверу
drweb.api.user=
#пароль для доступа к серверу
drweb.api.pswd=
#кодировка
drweb.api.encoding=UTF-8
#id расхода за Drweb
drweb.charge.id=54
# коментарий к расходу
drweb.charge.comment=За Dr.Web AV-Desk test;
#текст ошибки при нехватке баланса
drweb.error.balance.message=Недостаточно денег на счету test
#наличие льготного периода
graceperiod=yes
#количество полных месяцев льготного периода
graceperiod.count=1
#название пункта меню в web-интерфейсе
web.menuItem1=Dr.Web AV-Desk - подписка
#максимальное кол-во на однин договор
#drweb.agent.max.count=5
#текст ошибки при превышение максимального количества агентов
#drweb.error.max.count.message=Вы превысили количество агентов

На вкладке модуля Тарифы создайте тарифы, соответствующие тарифам в Dr.Web AV-Desk.

Для тарифа можно выбрать следующие параметры:

  • Название - определяет как тариф будет показываться пользователю;

  • Услуга - определяет услугу, по которой будет начисляться наработка;

  • Услуга активации - определяет услугу, по которой будет начисляться наработка в месяц активации агента (месяц первого платежа);

  • Группа - соответствеут группе на сервере Av-Desk;

  • Действует - задает период действия тарифа;

  • Показывать - задает период, когда пользователь видит тариф и может на него переключаться (подключаться);

  • Следующий тариф - определяет тариф, на который нужно переключить агента по истечении срока действия данного тарифа (применяеться для акционных тарифов);

  • Показывать для групп - определяет группы договоров, пользователи которых видят тариф и могут на него переключаться (подключаться);

  • Только для новых - тариф виден только для первичного подключения, но не для перехода на него в последующем.

В планировщике заданий необходимо добавить задачу Обработка задач Dr.Web (режим 1). Данная задача отвечает за продление подписки и изменение тарифов на сервере Dr.Web AV-Desk. Период запуска устанавливаем в начале каждых суток. В конфигурации задачи должно быть указано

#mid модуля drweb
mid=
#В какие дни месяца можно менять тариф. AV-Desk позволяет переключать тариф в первый день месяца
change.tariff.days=1   
#За сколько дней до конца месяца начинать продлять агентов (когда начинать списывать средства и продлять или прекращать подписку )
prolong.days=2

В планировщике заданий необходимо добавить задачу Начисление Dr.Web. Данная задача производит начисление за подписку. В конфигурации задачи должно быть указано

#mid модуля drweb
mid=

Добавить модуль в договоры, в которых планируется применение данной услуги.

4. Управление подписками

В договоре при выборе модуля drweb имеется возможность управленя агентами пользователя.

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

5. Web-интерфейс

При добавлении модуля в договор, в Web-интерфейсе пользователя появляется пункт меню Dr.Web AV-Desk - подписка. Здесь имеется возможность получить новый агент и управлять подписками имеющихся агентов.

Для получения нового агента пользователь должент выбрать галочку Я принимаю условия лицензионного соглашения и нажать кнопку Получить Dr.Web. Для управления агентом, необходимо выбрать агент по ссылке, откроется страница управления агентом.

6. Настройка тарифных планов

В один момент времени на договоре может действовать только один тарифный план, включающий в себя поддерево экземпляра модуля DrWeb. Если у вас не было тарифного плана, создайте его, создайте для него поддерево, либо расширьте от другого тарифа. Как это сделать можете прочитать здесь. Там же описана логика работы тарифных деревьев и поведения стандартных узлов тарифных деревьев, общих для всех модулей. После того как вы откроете дерево в нем должен отобразится узел со значком паука и названием экземпляра модуля DrWeb.

В тарифном запросе модуля DrWeb передаются следующие параметры:

1) код потребляемой услуги;
2) время момента потребления;
3) код тарифного плана.

Глава 16. Модуль E-Mail

1. Назначение модуля

Модуль предназначен для упрощения процесса создания и управления почтовыми ящиками из интерфейса биллинга и из Web-интерфейса пользователя. Работа модуля построена на взаимодействии с LDAP или SQL базой данных, используемой для хранения почтовых аккаунтов и информации о них.

2. Установка и настройка модуля

После того как вы проинсталлировали модуль с помощью утилиты bg_installer и создали его экземпляр в редакторе модулей и услуг создайте услугу одну или несколько в данном модуле. Количество услуг может варьироваться в зависимости от того сколько типов почтовых пользователей вы хотите завести. Наличие разрешённой услуги в договоре определят права по управлению почтовыми аккаунтами данного договора через Web интерфейс.

2.1. Домены

На вкладке Домены определите перечень доменов, аккаунты в которых можно создавать в модуле.

Обязательным параметром является лишь имя домена. Идентификаторы доменов указаны в столбце ID таблицы. В конфигурации домена могут быть указаны опции LDAP или SQL-хранилища, если для данного домена требуются иные от общей конфигурации модуля настройки хранилища (см. далее).

2.2. Настройка конфигурации

Откройте модуль E-Mail и внесите конфигурацию. Здесь определяются права услуг - разрешения для пользователей с определёнными услугами по манипуляции ящиками. Общая часть конфигурации:

#активные статусы договора
contract.status.active.codes=0

#названия пунктов меню Web-интерфейса
web.menuItem1=Управление E-Mail
web.menuItem2=Пересылки E-Mail
web.menuItem3=Смена пароля на E-Mail
#блокировать статусы ящиков при изменении статуса договора на неактивный
#разблокировать при изменении статуса на активный или при приходе платежа
#change.by.status=1
#минимальная и максимальная длина пароля почты
password.length.min=5
password.length.max=10
#длина автоматически генерируемого пароля
password.length.auto=6
#допустимые в пароле символы
password.chars=1234567890
#значения квот
quota.list=1:1КБ;1024:1MB;10240:10MB
#допустимые имена аккаунтов, REGEXP
email.account.regexp=^[-\w]{1,40}$
#допустимые имена пересылок, REGEXP
email.forward.regexp=^[\\w]{4,20}@[\\.\\w]{5,20}$
#----------------------------------------
#выборочное отключение проверки закрытого периода
#Изменение записи
#closed.date.disabled.ActionUpdateAccount=1
#----------------------------------------

Строки с разрешениями для различных услуг:

#разрешения для различных услуг модуля E-Mail
service.{код услуги 1}=view;create:{сколько, 0 - неогр}:{где}:{квота};delete;forward:{форвардов на аккаунт};password
service.{код услуги 2}=view;create:{сколько, 0 - неогр}:{где}:{квота};delete;forward:{форвардов на аккаунт};password

Строка-разрешение выглядит следующим образом:

service.{код услуги}=view;create:{сколько}:{где запятую}:{квота};delete;forward:{форвардов на аккаунт}

Рассмотрим составляющие привилегии:

{код услуги} - код услуги модуля E-Mail, можете посмотреть его в редакторе модулей и услуг; view - разрешение просмотра списка ящиков через Web-интерфейс; create - разрешение создания ящиков;
{сколько} - максимальное число ящиков, которые можно создать договору;
{где} - перечень кодов разрешённых доменов через запятую (в данном примере один домен с кодом 1);
{квота} - квота создаваемых через Web ящиков; delete - привилегия удалять ящики; forward - разрешение вешать пересылки на ящик;
{форвардов на аккаунт} - сколько пересылок можно вешать на один аккаунт;
password - разрешение менять пароли на ящики;
view - разрешение просматривать свои ящики;

Данные ограничения работают только на Web-интерфейс пользователя.

Пример 16.1. Пример ограничения для клиента

quota.list=1:1КБ;1024:1MB;10240:10MB;0:неограниченно
#разрешено просматривать ящик, создать 1 ящик в 1 домене с квотой 1КБ, удалять, менять пароль на ящики
service.138=view;create:1:1:1;delete;password
#разрешено просматривать ящик, создать 2 ящика в 1 или 2 домена с неограниченной квотой, создавать 2 переадресации с каждого ящика
service.138=view;create:2:1,2:0;delete;forward:2

Если вы предоставите договору несколько услуг модуля E-Mail, их разрешения будут складываться.

Параметр quota.list задаёт список разрешённых квот и фактические значения, которые будут передаваться на LDAP сервер. В приведённом примере, например, указаны значения для Exim, т.к. он принимает значения квот в килобайтах.

2.3. Хранилище почтовых аккаунтов

Параметры хранилища почтовых аккаунтов можно указать как в конфигурации модуля, так и отдельно для каждого домена. При этом параметры сначала будут браться из конфигурации домена, а при отсутствии какого-либо - из конфигурации модуля. В случае персональной настройки доменов в конфигурации домена можно указать параметр inherit=<id>, означающий, что параметры хранилища данного домена такие же как и у домена идентификатором равным <id>.

Таким образом, аккаунты различных отдельных доменов могут хранится в разных LDAP/SQL-серверах, а также в разных типах хранилищ.

2.3.1. LDAP база

В конфигурации модуля/домена необходимо указать параметры подключения к LDAP-базе (пример):

#работа через LDAP
sa=ru.bitel.bgbilling.modules.email.server.bean.LdapEmailServiceActivator
#драйвер, специфичный для используемого почтового агента
sa.ldap.class=bitel.billing.server.email.bean.EximLDAPDriver
#адрес LDAP-сервера
sa.ldap.host=ldap.bill.ru
#порт LDAP-сервера
sa.ldap.port=389
#корневой узел домена
sa.ldap.root=dc=bill,dc=ru
#логин и пароль для LDAP-сервера
sa.ldap.user=cn=admin,dc=bill,dc=ru
sa.ldap.password=admin
#имя базы подставляется в LDAP-запись для идентификации с какого сервера биллинга была добавлена запись
sa.ldap.base=bgbilling

Примеры настройки почтовой системы и LDAP-хранилища описаны в WiKi в разделе Решения для модулей и плагинов => Модуль E-Mail.

Начиная с версии 4.0 возможно добавление собственных LDAP-атрибутов. Для этого в конфигурации прописываются записи. name - имя атрибута, которое будет передано в LDAP. Атрибуты должны быть добавлены в схеме! title - отображение атрибута в биллинге.

ldap.attribute.1.title=Атрибут1
ldap.attribute.1.name=attr1
ldap.attribute.2.title=Атрибут2
ldap.attribute.2.name=attr2

В дальнейшем будут поддержаны LDAP-схемы для других почтовых клиентов.

2.3.2. SQL база

В конфигурации модуля/домена необходимо указать параметры подключения к SQL-базе, параметры домена (пример):

#работа через SQL-базу данных 
sa=ru.bitel.bgbilling.modules.email.server.bean.JDBCEmailServiceActivator
#JDBC-драйвер для SQL-базы
#sa.jdbc.driver=com.mysql.jdbc.Driver
#URL доступа к базе
sa.jdbc.url=jdbc:mysql://127.0.0.1:3306/email
#логин и пароль к SQL-базе
sa.jdbc.user=
sa.jdbc.password=
#тип домена ('LOCAL','RELAY','VIRTUAL')
sa.jdbc.domain.type=
#пользователь и группа
sa.jdbc.domain.uid=
sa.jdbc.domain.gid=

Структура базы хранилища аккаунтов представлена ниже:

 CREATE TABLE domains (
   domain varchar(128) NOT NULL,
   type enum('LOCAL','RELAY','VIRTUAL') default 'LOCAL',
   uid int(10) unsigned default '1003',
   gid int(10) unsigned default '6',
   PRIMARY KEY  (domain)
 );

 CREATE TABLE users (
   login varchar(64) NOT NULL,
   name varchar(128) NOT NULL,
   password varchar(64) NOT NULL,
   domain varchar(128) NOT NULL,
   quota tinyint(4) default '0',
   status enum('0','1') default '1',
   PRIMARY KEY  (login,domain)
 );
 
 CREATE TABLE userforward (
   local_part varchar(64) NOT NULL,
   domain varchar(128) NOT NULL,
   recipients text,
   PRIMARY KEY  (local_part,domain)
 );

 CREATE TABLE aliases (
   local_part varchar(64) NOT NULL,
   domain varchar(128) NOT NULL,
   recipients text,
   PRIMARY KEY  (local_part,domain)
 );

2.4. Настройка планировщика

В планировщике заданий необходимо настроить запуск задачи Синхронизация E-Mail аккаунтов в 0 часов 3 минуты каждых суток. В параметрах запуска укажите mid=<mid>, где <mid> - код экземпляра модуля E-Mail. В хранилище почтовых аккаунтов хранится только актуальное на текущий момент состояние аккаунтов, данная задача необходима для обновления актуального состояния аккаунтов при переходе дат. При добавлении аккаунта в договор будущим числом, он будет реально добавлен в хранилище только при наступлении дня начала периода действия данной задачи. Аналогично, задача удалит аккаунт в хранилище при истечении периода его действия в биллинге.

3. Использование модуля

Подключение экземпляра модуля к договору осуществляется путем выбора узла Модули дерева договора и нажатия кнопки Новый элемент стандартной панели иструментов. Разрешённые услуги устанавливают ограничения на управление ящиками через Web-интерфейс.

Для добавления/удаления/редактирования ящиков выберите модуль в дереве договора и используйте кнопки панели инструментов открывшегося редактора. При управлении ящиками через клиент биллинга не действуют ограничения, как при создании через Web.

Для переноса ящика на другой активный договор следует открыть целевой договор, выбрать ящик в таблице, нажатием правой кнопкой мыши вызвать всплывающее меню, выбрать пункт Перенести на другой договор. Целевой договор должен быть открыт на вкладке.

Вкладка Атрибуты - позволяет редактировать пользовательские LDAP-атрибуты аккаунта.

Модуль способен автоматически блокировать аккаунты договоров с остатком на балансе менее лимита. Блокировку осуществляет задача планировщика Блокировка E-Mail аккаунтов . В параметрах запуска задачи должно быть установлено:

mid=<код модуля E-Mail>

При этом аккаунт переходит в статус заблокирован и происходит обновление записи в хранилище.

При приходе платежа в случае, если баланс превысит лимит, статус договора активен и переменная конфигурации модуля change.by.status установлена в 1, сервер разблокирует аккаунты договора со статусом заблокирован.

Если установлена опция change.by.status=1, статусы ящиков также меняются вслед за статусами договоров. При всех неактивных статусах договора ящики переводятся в статус заблокирован, при подключении договора все заблокированные ящики становятся активными.

Глава 17. Модуль Inet

1. Назначение модуля

Модуль предназначен для организации доступа, тарификации времени и трафика клиентов, потребляющих услуги передачи данных по RADIUS, Netflow v1,v5,v7,v9, sFlow.

Поддерживаются различные механизмы доступа: RADIUS-авторизация, управление ПО и оборудованием, Cisco ISG, Redback CLIPS, DHCP.82-авторизация.

2. Базовые сведения о модуле

Базовые понятия модуля:

Тип трафика - категория для разделения потребляемого трафика;
Устройство - в дереве устройств определяется иерархия устройств разного типа, имеющих значение для модуля;
Тип устройства - определяет поведение устройства, механизм управления сервисов на устройствах данного типа;
Сервис - предоставляемый клиенту какой-то способ доступа к передаче данных, например логин или порт коммутатора;
Тип сервиса - определяет параметры, которые должны быть определены у сервиса;
Сессия сервиса - сущность в модуле для учёта потребляемых сервисом услуг;
Опция - набор опций определяет параметры сессии сервиса в конкретный момент времени, опция абстрактна, конкретное её воплощение реализует тип устройства.

Приложения модуля:

BGInetAccess - управляет доступом сервисов к сети и параметрами этого доступа;
BGInetAccounting - тарификация сессий сервисов.

Связь между приложениями осуществляется посредством базы данных и MQ-сообщений.

Внимание

После очередного обновления модуля необходимо в Автоматизация->Управление динамическим кодом скомпилировать все классы, т.к. перекомпиляция после обновления автоматически не происходит, а классы, входящие в сборку, могли обновиться.

3. Настройка модуля

Внимание

Для корректной работы модуля необходима установка модуля Card.

Установите модуль на сервер, создайте экземпляр. Определите в Редакторе модулей и услуг услуги, обсчитываемые этим модулем. Например: "Входящий трафик", "Исходящий трафик", "Время". Услуги используются для разделения наработки по типам в балансе договора.

В конфигурации модуля укажите:

# Активные и приостановленные статусы договора
contract.status.active.codes=0
contract.status.suspend.codes=3,4

# Проверка цены в тарифе: 0 - проверка отсутствует, 1 - ошибка только? Если у сессии есть трафик определённого типа,
# но для него нет цены, 2 - ошибка? Если хотя бы для одного типа трафика в привязке типа сервиса нет цены (по умолчанию - 1)
#accounting.tariffication.checkPrice=1

# Режим активации учетного периода, если не используется скрипт на событие активации,
# 0 (по умолчанию) - активация со дня подключения (старта сессии), 1 - активация с начала месяца.
# Следует учитывать, что учетный период является второй величиной при вычислении пропорциональности
# в тарифной ветке "Диапазон трафика"
#accounting.period.activation.mode=0

# Нужно ли отключать сервис с типом инициации "по трафику", если тариф не найден
#serv.disableOnTariffError=0

#Пункты Web - меню
web.menuItem1=Отчет по сессиям Inet
web.menuItem2=Смена пароля на логины Inet
web.menuItem3=none
#web.menuItem3=Отчет по трафикам Inet

# Параметры автоматической генерации логина для сервиса.
# Минимальное значение логина при генерации логина
#serv.login.min=1
# Максимальное значение логина при генерации логина (т.е. если в базе присутствуют логины 1,2,3 и 10000000,
# то при генерации создастся логин 4, а не 10000001)
#serv.login.max=9999999

#Параметры логина
#Список разрешенных символов для логина
serv.login.chars=1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz
#Описание разрешенных символов, если пользователь ввел другие
serv.login.chars.description=Логин может содержать только цифры и латинские буквы

# Параметры автоматической генерации пароля для сервиса. Можно указать в конфигурации модуля, конфигурации устройства, конфигурации типа сервиса
# (в последнем случае значения будут главнее):
# Минимальная длина пароля
serv.password.length.min=5
# Максимальная длина пароля
serv.password.length.max=16
# Разрешенные символы (используются также при генерации пароля)
serv.password.chars=1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz
# Описание разрешенных символов, если пользователь ввел другие
serv.password.chars.description=В пароле допустимы только цифры и латинские буквы.
# Длина для автоматически генерируемого пароля
serv.password.length.auto=6
# Используемые символы для автоматически генерируемого пароля (по умолчанию значение берется из параметра serv.password.chars)
#serv.password.chars.auto=

# Параметры активации карточек модуля card при использовании InetRadiusProcessor,
# данные параметры можно указать как в конфигурации модуля, так и в конфигурации устройства.
# Код модуля card
#card.moduleId=
# id услуг активации
#card.activate.serviceIds=
# Минимальное значение карточного логина используется, чтобы указать, какие числовые логины нужно искать в карточках;
# если 0, то ограничение не действует.
#card.login.min=0
# Максимальное значение карточного логина используется, чтобы указать, какие числовые логины нужно искать в карточках;
# если 0, то ограничение не действует.
#card.login.max=0

#Опции клиента биллинга
#Сворачивание/Разворачивание дерева устройств в редакторе сервиса договора.
#Возможные значения: 0 - сворачивать, 1 - разворачивать. Если опция не указана, то по умолчанию используется значение 1.
#client.gui.expand.device.tree=1

На вкладке Опции экземпляра модуля укажите хотя бы одну опцию.

4. Трафики

Настройка типов трафика и привязок выполняется на вкладке модуля Трафики.

Тип трафика - это категория, необходимая для разделения потребляемого трафика по типам. Например: "Входящий внешний", "Входящий внутренний", "Входящий локальный", "Радио", "Голосовой трафик". Время также является специальным типом трафика с кодом 0, который всегда потребляется в ходе работы. Перечень типов трафика редактируется на подвкладке Типы трафика.

Привязка типов трафика определяет правила разделения трафика по типам. Привязок может быть множество.

В свойствах привязки определяется название и набор правил, просмотр которых осуществляется последовательно. С помощью панели инструментов можно создавать привязки, изменять их порядок.

В каждом правиле указывается:

Тип - RADIUS, либо Коллектор (для netflow/sflow), в зависимости от протокола данных;
Период - период действия правила;
Тип трафика, к которому относится правило.

Для типа RADIUS необходимо указать ServiceName, Код вендора, Код атрибута и Префикс трафика. Код вендора и Код атрибута определяют атрибут, из которого извлекается трафик. Атрибут может быть типа целого типа либо строкового. Для получения трафиков из стандартных атрибутов Acct-Output-Octets, Acct-Output-Gigawords (входящий трафик для клиента) необходимо указать в коде вендора и атрибута значения -2 и 1 соответственно. Acct-Input-Octets, Acct-Input-Gigawords (исходящий трафик для клиента) - значения -2 и 2.

Префикс трафика может быть использован для извлечения трафика из строкового атрибута, в котором он добавлен с каким-либо префиксом. В этом случае трафик разных типов может идти в одном атрибуте, но с разными префиксами.

ServiceName используется для идентификации сервиса при посервисном аккаунтинге.

Для типа NetFlow необходимо указать направление трафика относительно адреса клиента, диапазон адресов (если нужен весь диапазон - поля можно оставить пустыми), а также, если необходимо, DiffServ/TOS биты.

5. Ресурсы

Ресурсами модуля являются уникальные идентификаторы, количество которых ограничено. В данный момент это IP-адреса, VLAN-ы, порты устройства. Всякий IP-адрес, vlan или порт, выданный модулем временно, либо постоянно, должен присутствовать в базе ресурсов и помечен там как занятый или свободный.

5.1. IP ресурсы

Ресурсы адресов делятся на категории. Категории образуют дерево, у каждой категории есть код, отображаемый в столбце ID.

Для редактирования дерева категорий используется общая панель инструментов, для редактирования ресурсов - панель над таблицей с ресурсами. Каждый диапазон адресов уникален внутри категории.

Категории IP-ресурсов можно использовать как для статической привязке в сервисе на договоре, так и для динамической выдачи через RADIUS или DHCP, в том числе одновременно. Например, указать на устройстве категорию для реалма radius и для статической выдачи:

radius.realm.default.ipCategories=1
ip.resource.categoryId=1

Однако необходимо учитывать, что при статическом назначении в сервисе договора IP-адреса, занятые в данный момент динамически, будут показаны как свободные.

По правому клику мышки в таблице на конкретном ресурсе во всплывающем меню доступен пункт "Использование ". При выборе этого пункта открывается таблица тех, кто использует данный ресурс:

Для оперативного перехода к договору, который использует данный ресурс, достаточно щелкнуть правой кнопкой мыши и в появившемся контекстном меню выбрать пункт меню Договор.

5.2. VLAN-ресурсы

Ресурсы VLAN делятся на категории. Категории образуют дерево, у каждой категории есть код, отображаемый в столбце ID.

Для редактирования дерева категорий используется общая панель инструментов, для редактирования ресурсов - панель над таблицей с ресурсами. Каждый диапазон VLAN уникален внутри категории.

По правому клику мышки в таблице на конкретном ресурсе во всплывающем меню доступен пункт "Использование ". При выборе этого пункта открывается таблица тех, кто использует данный ресурс:

5.3. Ресурсы интерфейсов.

Интерфейсы уникальны в пределах одного устройства. Сам список интерфейсов задаётся в типе устройства. Далее в дереве устройств можно по правому клику мышкой на устройстве выбрать "Интерфейсы", и откроется панель занятости интерфейсов:

Двойным кликом мышки можно открыть на редактирование конкретный интерфейс и изменить его статус . Статусы имеют следующие значение:

Доступен - интерфейс доступен для добавления на договор;

Зарезервирован - интерфейс не доступен для добавления на договор.

Также для каждого интерфейса может быть указана категория адресов, которые могут быть выбраны на этом интерфейсе . Внутри одной категории IP-адреса не пересекаются.

По правому клику мышки в таблице на конкретном интерфейсе во всплывающем меню доступен пункт "Использование ". При выборе этого пункта открывается таблица тех, кто использует данный интерфейс:

6. Типы устройств

Дерево устройств представляет из себя отображение структуры сети с точки зрения модуля. При этом устройства не обязательно соотносятся с реальными устройствами сети - это логические единицы. В том числе это могут быть группирующие узлы или, например, физические интерфейсы маршрутизатора. Управление устройствами, их типами и ресурсами адресов производится на вкладке Устройства и ресурсы модуля.

Каждое устройство обладает своим типом. Типы устройств определяются на вкладке Типы.

Рассмотрим параметры, которые могут быть указаны в типе устройства:

Название - обозначение типа, используется в т.ч. для формирования имени устройства;
Флаг является источником данных - обозначает, что данный тип устройств генерирует данные о трафике, устройства с данным типом отображаются при переобработке логов;
Обработчик активации сервисов - динамический класс, реализующий определённый интерфейс по управлению устройством для блокировки/разблокировки сервиса, изменения его параметров;
Обработчик процессора протокола - динамический класс, реализующий определённый интерфейс по пред- и постобработке пакетов протокола, связанных с конкретным устройством (например, RAIDIUS или DHCP-пакетов).
Обработчик управления устройством - динамический класс, реализующий определённый интерфейс по дополнительному управлению устройством (например, получение uptime устройства на текущий момент, для отслеживания перезагрузки устройства).

На вкладке Интерфейсы типа устройства указываются его интерфейсы, к которым могут быть привязаны сервисы. Например, это могут быть порты коммутаторов.

Внимание

После корректировки параметров типов устройств для их перечитывания на серверах Access и Accounting необходимо нажать кнопку Перечитать конфигурацию на серверах, расположенную под деревом устройств. Данная кнопка позволяет оповещать сервера об изменениях только, когда конфигурация станет законченной. До тех пор сервера используют сохранённую в памяти конфигурацию.

6.1. Обработчик активации сервисов

Обработчик активации сервисов синхронизирует состояние сервиса и сессии на устройстве. Именно он производит открытие/закрытие доступа, изменение скорости или других параметров.

Обработчик привязывается к типу устройства и вызывается поочередно от корня дерева устройств до затронутого устройства (при необходимости синхронизировать сервис, привязанный к устройству данного типа или же сессию, начатую на устройстве данного типа).

Внимание

В поставку модуля Inet входят стандартные реализации для Cisco, Redback, MPD и т.п., производящие интеграцию с соответствующими устройствами. Исходные коды находятся в Управлении динамическим кодом, в пакете ru.bitel.bgbilling.modules.inet.dyn. Данные классы перетираются при обновлении, поэтому для изменения логики класса необходимо расширить его или создать копию, но не изменять его напрямую.

/**
 * Интерфейс обработчика активации сервисов.<br/>
 * <pre>Жизненный цикл:
 * init
 * 
 *   connect
 *     serviceModify
 *     serviceModify
 *     serviceCancel
 *   disconnect
 *   
 *   connect
 *     serviceCreate
 *     serviceModify
 *     connectionModify
 *     serviceModify
 *     connectionClose
 *   disconnect

 * destroy</pre>
 */
public interface ServiceActivator
{
	/**
	 * Инициализация обработчика. Вызывается после создания объекта.
	 * @param setup
	 * @param moduleId
	 * @param device
	 * @param deviceType
	 * @param config
	 * @return
	 * @throws Exception
	 */
	public Object init( Setup setup, int moduleId, InetDevice device, InetDeviceType deviceType, ParameterMap config )
	    throws Exception;

	/**
	 * Утилизация обработчика. Вызывается перед уничтожением объекта.
	 * @return
	 * @throws Exception
	 */
	public Object destroy()
	    throws Exception;

	/**
	 * Подключение к устройству для работы с ним.
	 * @return
	 * @throws Exception
	 */
	public Object connect()
	    throws Exception;

	/**
	 * Отключение от устройства.
	 * @return
	 * @throws Exception
	 */
	public Object disconnect()
	    throws Exception;

	/**
	 * Создание сервиса (по событию добавления или началу периода действия)
	 * @param e
	 * @return
	 * @throws Exception
	 */
	public Object serviceCreate( ServiceActivatorEvent e )
	    throws Exception;

	/**
	 * Изменение сервиса (подключение/отключение/изменение скорости).
	 * Вызывается при изменении набора опций или изменении состояния сервиса
	 * @see ServiceActivatorEvent
	 * @see {@link ServiceActivatorEvent#getNewState()}
	 * @param e
	 * @return
	 * @throws Exception
	 */
	public Object serviceModify( ServiceActivatorEvent e )
	    throws Exception;

	/**
	 * Удаление сервиса (по событию удаления или окончания периода действия).
	 * @param e
	 * @return
	 * @throws Exception
	 */
	public Object serviceCancel( ServiceActivatorEvent e )
	    throws Exception;

	/**
	 * Изменение соединения.
	 * Вызывается при изменении набора опции на соединении или при изменении состояния.<br/>
	 * Обычно, при {@link ServiceActivatorEvent#getNewState()} == {@link InetServ#STATE_DISABLE} из этого метода происходит вызов метода {@link #connectionClose(ServiceActivatorEvent)}
	 * @param e
	 * @return
	 * @throws Exception
	 */
	public Object connectionModify( ServiceActivatorEvent e )
	    throws Exception;

	/**
	 * Закрытие (принудительное) соединения.<br/>
	 * Обычно вызывается при {@link AccessCodes#TOO_MANY_SESSIONS_ERROR} или из метода {@link #connectionModify(ServiceActivatorEvent)}
	 * @param e
	 * @return
	 * @throws Exception
	 */
	public Object connectionClose( ServiceActivatorEvent e )
	    throws Exception;

	/**
	 * Обработка старта соединения.
	 * @param event
	 * @return
	 * @throws Exception
	 */
	public Object onAccountingStart( ServiceActivatorEvent event )
	    throws Exception;

	/**
	 * Обработка стопа соединения.
	 * @param event
	 * @return
	 * @throws Exception
	 */
	public Object onAccountingStop( ServiceActivatorEvent event )
	    throws Exception;
}

Описание интерфейса ru.bitel.bgbilling.modules.inet.access.sa.ServiceActivator доступно в документации по API.

6.2. Обработчик процессора протокола

Обработчик процессора протокола позволяет произвести пред/постобработку RADIUS или DHCP-запросов - например, изменить RADIUS-запрос перед его обработкой системой или установить дополнительные опции, которые поменяют логику обработки запроса.

Обработчик привязывается к типу устройства, т.е. обработчик будет работать с запросами с устройств данного типа. При этом поочередно вызываются все обработчики в цепочке дерева, начиная от корня дерева до устройства, с которого пришел запрос.

Внимание

В поставку модуля Inet входят стандартные обработчики для Cisco, Redback, MPD и т.п., позволяющие расширить интеграцию и функционал простым изменением конфигурации. Исходные коды находятся в Управлении динамическим кодом, в пакете ru.bitel.bgbilling.modules.inet.dyn. Данные классы перетираются при обновлении, поэтому для изменения логики класса необходимо расширить его или создать копию, но не изменять его напрямую.

Обработчик процессора протокола состоит из двух интерфейсов, которые он расширяет:

/**
 * Обработчик RADIUS-запросов
 */
public interface RadiusProtocolHandler
{
	/**
	 * Предобработка RADIUS-запроса Access-Request
	 * @param request
	 * @param response
	 * @param connectionSet
	 * @throws Exception
	 */
	public void preprocessAccessRequest( RadiusPacket request, RadiusPacket response, ConnectionSet connectionSet )
	    throws Exception;

	/**
	 * Постобработка RADIUS-запроса Access-Request
	 * @param request
	 * @param response
	 * @param connectionSet
	 * @throws Exception
	 */
	public void postprocessAccessRequest( RadiusPacket request, RadiusPacket response, ConnectionSet connectionSet )
	    throws Exception;

	/**
	 * Предобработка RADIUS-запроса Accounting-Request
	 * @param request
	 * @param response
	 * @param connectionSet
	 * @throws Exception
	 */
	public void preprocessAccountingRequest( RadiusPacket request, RadiusPacket response, ConnectionSet connectionSet )
	    throws Exception;

	/**
	 * Постобработка RADIUS-запроса Accounting-Request
	 * @param request
	 * @param response
	 * @param connectionSet
	 * @throws Exception
	 */
	public void postprocessAccountingRequest( RadiusPacket request, RadiusPacket response, ConnectionSet connectionSet )
	    throws Exception;
}
/**
 * Обработчик DHCP-запросов
 */
public interface DhcpProtocolHandler
{
	/**
	 * Предобработка DHCP-запроса
	 * @param request
	 * @param response
	 * @throws Exception
	 */
	public void preprocessDhcpRequest( DhcpPacket request, DhcpPacket response )
		throws Exception;
	
	/**
	 * Постобработка DHCP-запроса
	 * @param request
	 * @param response
	 * @throws Exception
	 */
	public void postprocessDhcpRequest( DhcpPacket request, DhcpPacket response )
		throws Exception;
}
/**
 * Обработчик процессора протокола.
 * @see RadiusProtocolHandler
 * @author amir
 *
 */
public interface ProtocolHandler
    extends RadiusProtocolHandler, DhcpProtocolHandler
{
	public void init( Setup setup, int moduleId, InetDevice inetDevice, InetDeviceType inetDeviceType, ParameterMap config )
	    throws Exception;
}

Например, такой обработчик будет подменять значение атрибута User-Name на значение идентификатора устройства + значение атрибута Nas-Port-Id, а значение пароля на "Password":

import ru.bitel.bgbilling.kernel.network.radius.RadiusDictionary;
import ru.bitel.bgbilling.kernel.network.radius.RadiusPacket;
import ru.bitel.bgbilling.modules.inet.access.sa.ProtocolHandler;
import ru.bitel.bgbilling.modules.inet.access.sa.ProtocolHandlerAdapter;
import ru.bitel.bgbilling.modules.inet.api.common.bean.InetDevice;
import ru.bitel.bgbilling.modules.inet.api.common.bean.InetDeviceType;
import ru.bitel.bgbilling.server.util.Setup;
import ru.bitel.common.ParameterMap;
import ru.bitel.common.sql.ConnectionSet;

public class SomeProtocolHandler
	extends ProtocolHandlerAdapter
	implements ProtocolHandler
{
	private String deviceIdentifier;

	@Override
	public void init( Setup setup, int moduleId, InetDevice inetDevice, InetDeviceType inetDeviceType, ParameterMap deviceConfig )
		throws Exception
	{
		this.deviceIdentifier = inetDevice.getIdentifier();
	}

	@Override
	public void preprocessAccessRequest( RadiusPacket request, RadiusPacket response, ConnectionSet connectionSet )
		throws Exception
	{
		String nasPortId = request.getStringAttribute( -1, RadiusDictionary.NAS_Port_Id, null );
		
		request.setStringAttribute( -1, RadiusDictionary.User_Name, this.deviceIdentifier + ":" + nasPortId );
		request.setStringAttribute( -1, RadiusDictionary.User_Password, "Password" );
	}
}

6.3. Обработчик управления устройством

Для дополнительного управления у типа устройства можно указать обработчик управления устройством.

На текущий момент главной функцией обработчика является получение текущего uptime устройства. Uptime необходим для определения перезагрузки устройства, чтобы при наступлении такого события Access мог синхронизировать заново все сервисы на этом устройстве.

В конфигурации типа устройства (или в самом устройстве) можно задать параметры выполнения команд:

# Пауза между выполнением команды после ошибки
#manage.error.pause=5
# Пауза между получением uptime
#manage.uptime.pause=120
# Пауза после ошибки, возникшей при получении uptime
#manage.uptime.error.pause=120

С модулем Inet поставляется динамический класс ru.bitel.bgbilling.modules.inet.dyn.device.snmp.SnmpDeviceManager, у него реализован метод uptime, который по SNMP у устройства получает его текущий uptime в секундах.

# Хост для отправки SNMP-запросов (по умолчанию хост, заданный в параметрах устройства Хост/порт)
#snmp.host=
# Порт для отправки SNMP-запросов (по умолчанию 161)
#snmp.port=
# Версия SNMP (по умолчанию 1)
#snmp.version=
# Сommunity (по умолчанию из параметра устройства Сommunity/Secret)
#snmp.community=public
# SNMP OID, из которого извлекается значение uptime (1.3.6.1.2.1.1.3.0)
#snmp.uptimeOid=1.3.6.1.2.1.1.3.0

После привязки обработчика управления устройством с реализованным методом uptime, все устройства с периодичностью manage.uptime.pause будут опрашиваться на время работы после перезагрузки. Для того, чтобы при определении очередной перезагрузки устройства Access выполнил синхронизацию сервисов, в конфигурации типа устройства (или в устройстве) необходимо прописать:

# Синхронизировать ли сервисы при обнаружении перезагрузки, 0 - не синхронизировать (по умолчанию), 1 - синхронизировать
# (для обнаружения перезагрузки в типе устройства должен быть установлен обработчик управления устройством)
#sa.device.sync.onReboot=1
# Вызывать ли при синхронизации для каждого сервиса, 0 - только serviceCreate или 1 (по умолчанию) - 
# сначала serviceCancel, а затем serviceCreate
#sa.device.sync.cancelBeforeCreate=1

7. Устройства

База устройств модуля представлена в виде дерева, для редактирования используется стандартная панель инструментов. По правому клику мыши на устройство доступны функции вырезки и вставки, для изменения предка узла устройства.

Редактор устройства.

В устройстве определяются поля: Идентификатор, Хост/порт, Логин, Пароль, Community/secret. Назначение данных полей зависит от того, какой процессор использует данное устройство. В конфигурации устройства указывается текстовая конфигурация, которая также зависит от процессора, использующего устройство.

Конфигурация каждого устройства наследует все параметры конфигурации своего типа устройства, а затем устройства-предка (конфигурация которого также унаследована). Т.е. параметр, указанный в предке будет доступен во всех потомках и его можно переопределить в конфигурации типа устройства потомка и ещё раз - в конфигурации самого потомка. Это свойство можно использовать для определения одинаковых параметров для множества устройств с одним предком.

Внимание

После корректировки параметров устройств для их перечитывания на серверах Access и Accounting необходимо нажать кнопку Перечитать конфигурацию на серверах, расположенную под деревом устройств. Данная кнопка позволяет оповещать сервера об изменениях только, когда конфигурация станет законченной. До тех пор сервера используют сохранённую в памяти конфигурацию.

В контекстном меню на каждом устройстве доступны следующие пункты:

Договоры - открывает список договоров, на которых добавлен сервис, привязанный к данному устройству.

Cинхронизовать сервисы - синхронизует все сервисы на устройстве , для каждого сервиса вызываются команды удаления и создания сервиса на устройстве.

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

Удалить событие из очереди - Удаляет событие activemq для этого устройства. Бывает полезно, когда из-за ошибки в обработчике активации сервисов событие все время падает при обработке, и не может быть обработано и попытки его обработки продолжаются .

Интерфейсы устройства - интерфейсы устройства. Описаны тут.

Также есть команды - Вырезать, Вставить, Удалить, позволяющие редактировать дерево устройств.

7.1. Корневые устройства

Все устройства разделены на Группы авторизации, каждая со своим корневым устройством. Каждая из групп авторизации управляется отдельным изолированным Access-сервером, либо несколькими Access-серверами, которые работают в режиме кластера. Контроль IP-ресурсов, количества одновременных сессий сервисов производится только в пределах группы. Т.е. группы авторизации позволяют разделить предоставление услуг на не взаимосвязанные сегменты, что повышает масштабируемость.

В пределах группы авторизации может быть одна или несколько Групп обработки. Каждая из групп обрабатывается своим Accounting-сервером, либо несколькими Accounting-серверами, работающими в режиме кластера. Корневой узел группы обработки должен быть выделен отдельным типом. Для простоты, корневые узлы группы авторизации и обработки могут быть объединены в один.

Внимание

Для корректной работы InetAccounting необходима сконфигурировать обработчики в корневом устройстве.

В конфигурации корневого узла группы обработки (BGInetAccounting) обязательно нужно указать параметры тарификации и обработки соединений. Для этого нужно задать "worker", указав количество потоков для него, обработчики, которые будут работать в этом worker'е и их параметры. Каждый worker назначается с идентификатором, например, accounting.worker.1. и accounting.worker.2. Каждый обработчик также задаётся с идентификатором. Таким образом, может быть несколько worker'ов и несколько обработчиков в них.

Параметры обработчика тарификации (tariffication):

minDeltaAmount - минимальная сумма нетарифицированного трафика, при которой тарифицировать соединение. Включает в себя все трафики в байтах плюс время в секундах, которое ещё не было протарифицировано;
delay - пауза между заданиями тарификации;
batchSize - максимальное количество протарифицированных соединений за одно задание.

Параметры обработчика соединений без трафика (tracking - используется для отслеживания изменения опций модуля для соединений, у которых нет трафика):

delay (delay.millis) - пауза между заданиями в секундах (в миллисекундах);
batchSize - максимальное количество протарифицированных соединений за одно задание.

Параметры обработчика сервисов без соединений (serv.tracking - используется для отслеживания изменения опций модуля для сервисов, у которых нет сессии и, соответственно, нет трафика):

delay (delay.millis) - пауза между заданиями в секундах (в миллисекундах);
batchSize - максимальное количество протарифицированных соединений за одно задание;
servTypeIds - типы сервисов, которые нужно обрабатывать (если не указано - то все типы);
accountingPeriodActivate - нужно ли активировать учётные периоды при проверке, 1 - активировать, 0 - не активировать.

Параметры обработчика событий (event.tracking - предназначен для более быстрой реакции на события, например, изменение статуса договора, активация тарифной опции):

delay (delay.millis) - пауза между заданиями в секундах (в миллисекундах);
batchSize - максимальное количество обработанных сервисов за одно задание.

Параметры сброса в базу (flushing):

minDeltaAccount - минимальная сумма несброшенной наработки соединения, при которой нужно сбрасывать в базу;
delay (delay.millis) - пауза между заданиями в секундах (в миллисекундах);
batchSize - максимальное количество сброшенных соединений за одно задание.

Параметры обработчика завершения сессий (finishing - завершает соединения, а также закрывает соединения по таймауту):

delay (delay.millis) - пауза между заданиями в секундах (в миллисекундах);
batchSize - максимальное количество протарифицированных соединений за одно задание.

Пример конфигурации:

# Количество потоков на worker
accounting.worker.1.thread.count=2
# Тарификатор:
# минимальная сумма трафика, при которой тарифицировать соединение
accounting.worker.1.tariffication.1.minDeltaAmount=0
# пауза между заданиями тарификации
accounting.worker.1.tariffication.1.delay=10
# максимальное количество тарифицируемых соединений за задание
accounting.worker.1.tariffication.1.batchSize=1000
# Трекер (обработка сессий без наработки):
# пауза между заданиями трекинга
accounting.worker.1.tracking.1.delay=10
# максимальное количество проверенных соединений за задание
accounting.worker.1.tracking.1.batchSize=1000
# Трекер (обработка сервисов модуля без активных сессий, по умолчанию не требуется):
# пауза между заданиями трекинга
accounting.worker.1.serv.tracking.1.delay=20
# максимальное количество проверенных соединений за задание
accounting.worker.1.serv.tracking.1.batchSize=100
 
# Количество потоков на worker
accounting.worker.2.thread.count=1
# Сброс в базу трафиков и наработки:
# минимальная наработка, при которой сбрасывать соединение в базу
accounting.worker.2.flushing.1.minDeltaAccount=0
# минимальная сумма трафика, при которой сбрасывать соединение в базу
accounting.worker.2.flushing.1.minDeltaAmount=0
# пауза между заданиями сброса в базу
accounting.worker.2.flushing.1.delay=20
# максимальное количество сброшенных соединений в базу за задание
accounting.worker.2.flushing.1.batchSize=500
 
# Количество потоков на worker
accounting.worker.3.thread.count=1
# Завершитель соединений:
# пауза между заданиями
accounting.worker.3.finishing.1.delay=20
# максимальное количество сброшенных соединений в базу за задание
accounting.worker.3.finishing.1.batchSize=500

Пример конфигурации с несколькими обработчиками тарификации (для более частой тарификации соединений с большим трафиком):

# Количество потоков на worker
accounting.worker.1.thread.count=3
# Тарификатор:
accounting.worker.1.tariffication.1.minDeltaAmount=104857600
accounting.worker.1.tariffication.1.delay=10
accounting.worker.1.tariffication.1.batchSize=1000
accounting.worker.1.tariffication.2.minDeltaAmount=10485760
accounting.worker.1.tariffication.2.delay=20
accounting.worker.1.tariffication.2.batchSize=1000
accounting.worker.1.tariffication.3.minDeltaAmount=0
accounting.worker.1.tariffication.3.delay=30
accounting.worker.1.tariffication.3.batchSize=1000
# Трекер (обработка сессий без наработки):
# пауза между заданиями трекинга
accounting.worker.1.tracking.1.delay=20
# максимальное количество проверенных соединений за задание
accounting.worker.1.tracking.1.batchSize=1000
 
# Количество потоков на worker
accounting.worker.2.thread.count=1
# Сброс в базу трафиков и наработки:
# минимальная наработка, при которой сбрасывать соединения в базу
accounting.worker.2.flushing.1.minDeltaAccount=0
# минимальная сумма трафика, при которой сбрасывать соединение в базу
accounting.worker.2.flushing.1.minDeltaAmount=0
# пауза между заданиями сброса в базу
accounting.worker.2.flushing.1.delay=30
# максимальное количество сброшенных соединений в базу за задание
accounting.worker.2.flushing.1.batchSize=500
 
# Количество потоков на worker
accounting.worker.3.thread.count=1
# Завершитель соединений:
# пауза между заданиями
accounting.worker.3.finishing.1.delay=20
# максимальное количество сброшенных соединений в базу за задание
accounting.worker.3.finishing.1.batchSize=500

Для обработки сервисов без сессий нужно добавить ещё один обработчик (а также можно увеличить количество потоков для accounting.worker.1 или вынести обработчик в отдельный worker):

# Трекер (обработка сервисов без сессий):
# пауза между заданиями трекинга
accounting.worker.1.serv.tracking.1.delay=60
# максимальное количество проверенных сервисов за задание
accounting.worker.1.serv.tracking.1.batchSize=500
# типы сервисов, которые нужно обрабатывать, через запятую
# (если пусто - будут обрабатываться сервисы всех типов!)
accounting.worker.1.serv.tracking.1.servTypeIds=
# нужно ли активировать учетный период при обработке
# (по умолчанию учетный период активируется при авторизации по RADIUS/DHCP или появлении новой сессии)
accounting.worker.1.serv.tracking.1.accountingPeriodActivate=1

Для более быстрой обработки событий нужно добавить ещё один обработчик (а также можно увеличить количество потоков для accounting.worker.1 или вынести обработчик в отдельный worker):

# Трекер (обработка событий):
# пауза между заданиями трекинга (в миллисекундах)
accounting.worker.1.event.tracking.1.delay.millis=200
# максимальное количество проверенных сервисов за задание
accounting.worker.1.event.tracking.1.batchSize=500

7.2. Интерфейсы

Правой кнопкой на любом устройства можно вызвать интерфейсы из его контекстного меню.

Тут все зависит от настроек типа сервиса. Если в типе сервиса стоит галочка "Индивидуальные интерфейсы", тогда их нужно создавать в типе устройства и они автоматически будут созданы на всех устройствах(если вы создали индивидуальные интерфейсы на устройствах, которых нет в типе устройства, то они будут удалены при сохранении типа устройства) . Если же галочка стоит, то нужно на каждом устройстве создавать интерфейсы вручную.

В интерфейса можно задавать индекс.

Индекс интерфейса используется для управления по snmp и сборе статистики по netflow. По умолчанию, если не указан, то индекс приравнивается номеру интерфейса. В тех же случаях, где индекс отличается от номера интерфейса, его можно задать явно. Так же для индекса может быть указана даты и время с какого по какое он действует.

8. Опции

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

Опции можно выстраивать в группы, как для удобства, так и для того, чтобы опции внутри группы не пересекались.

По умолчанию при прохождении тарифного дерева указанные опции просто добавляются в набор, однако, если опции выделить в отдельную группу и оставить поле "Пересечение в группе возможно", то установка очередной опции из группы удалит все другие опции из той же группы. Такую группу, например, можно создать для указания скоростей - тогда при использовании тарифных веток диапазонов (а при тарификации возможна ситуация, когда запрос зайдёт сначала в одну ветку диапазона, заполнив её, а затем в следующую, т.к. есть остаток), опция скорости в итоге всегда будет одна - последняя установленная при прохождении тарифа.

При изменении набора опций в сессии, например, при очередной тарификации или при добавлении/удалении опции в сервисе на договоре автоматически вызывается обработчик активации сервисов - вызывается serviceModify и, если в типе сервиса указан тип инициации сессии "по сигналу" (например, для RADIUS-сессий), для каждой сессии сервиса - connectionModify.

9. Типы сервисов

Тип сервиса определяет параметры, которые должны быть указаны в сервисе клиента. Типы сервисов редактируются на одноимённой вкладке модуля с использованием стандартной панели инструментов.

Параметры типа сервиса:

Тип инициации сессии - по сигналу (RADIUS, DHCP-пакет), либо по трафику;
Кол-во сессий - максимальное одновременно возможное количество сессий по одному сервису договора данного типа;
Тип адреса - какой тип адреса соотносится сервису, возможные значения рассмотрены далее;
Привязка типов трафика - используемая для сервиса привязка типов трафика.

Тип адреса может принимать следующие значения:

Не выделять адрес - сервис не предполагает использования адреса;
Статический диапазон - статический диапазон адресов указывается непосредственно в сервисе;
Статическая сеть - статическая сеть адресов указывается непосредственно в сервисе;
Статический адрес - статический адрес, указывается непосредственно в сервисе;
Динамический адрес - адрес выдаётся динамически на каждую сессию сервиса из пула;
Динамический или статический адрес - адрес выдаётся динамически на каждую сессию сервиса из пула, но может всё время принимать одно указанное значение;
Динамический адрес или статический диапазон - адрес выдаётся динамически на каждую сессию сервиса из пула, но может выдаваться из указанного непосредственно в сервисе диапазона адресов.

Флаги в нижней области определяют какие параметры должны быть указаны в сервисе договора.

В конфигурации типа сервиса могут быть определены переменные:

1. title.pattern=(<шаблон имени сервиса>), в шаблоне имени возможны переменные:

${login} - логин;
${deviceIdentifier} - идентификатор устройства, к которому привязан сервис;
${deviceTitle} - полное название устройства, к которому привязан сервис;
${interfaceId} - код интерфейса, указанного для сервиса;
${vlan} - VLAN, указанный для сервиса;
${addressRange} - адрес, указанный для сервиса;
${addressRange} - диапазон адресов, указанные для сервиса;
${addressNet} - сеть, указанная для сервиса;
${macAddress} - MAC-адрес(а), указанный для сервиса;
${identifier} - идентификаторы, указанные для сервиса.

2. const.device.id=<постоянный код устройства для всех сервисов данного типа>.

Пример конфигурации типа сервиса:

# Шаблон имени сервиса
title.pattern=(${login})

# Постоянный код устройства для всех сервисов данного типа,
# будет автоматически устанавливаться при сохранении сервиса
#const.device.id=

#Параметры логина
#Список разрешенных символов для логина
serv.login.chars=1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz
#Описание разрешенных символов, если пользователь ввел другие
serv.login.chars.description=Логин может содержать только цифры и латинские буквы

# Параметры пароля для сервиса. Можно указать в конфигурации модуля, конфигурации устройства, конфигурации типа сервиса
# (в последнем случае значения будут главнее):
# Минимальная длина пароля
#serv.password.length.min=5
# Максимальная длина пароля
#serv.password.length.max=16
# Разрешенные символы (используются также при генерации пароля)
#serv.password.chars=1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz
# Описание разрешенных символов, если пользователь
#serv.password.chars.description=В пароле допустимы только цифры и латинские буквы.
# Длина для автоматически генерируемого пароля
serv.password.length.auto=6
# Используемые символы для автоматически генерируемого пароля (по умолчанию значение берется из параметра serv.password.chars)
#serv.password.chars.auto=<serv.password.chars>

# Разрешенные реалмы при RADIUS-аутентификации. Можно указать в конфигурации модуля, конфигурации устройства, конфигурации типа сервиса.
# По умолчанию разрешена только default, т.е. без указания реалма
#radius.realm=default

# Нужно ли автоматически проставлять в сервис MAC-адрес, если его еще нет.
# Можно указать в конфигурации модуля, конфигурации устройства, конфигурации типа сервиса.
#serv.macAddress.auto=0

10. Сервисы

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

Столбцы таблицы:

Тип - тип сервиса;
Устройство - устройство, к которому привязан сервис;
Название - сгенерированное на основании шаблона из типа сервиса название сервиса договора;
Период - период действия;
Статус - текущий статус сервиса;
Состояние - реальное состояние сервиса на устройстве.

Статус сервиса может принимать следующие значения: открыт, закрыт и заблокирован. Статус сервиса переключается вручную.

Состояние сервиса может быть "подключён", либо "отключен", отображает реальное состояние, которое было установлено на устройстве. Между состояниями "подключен" и "отключен" модуль осуществляет автоматическое переключение в зависимости от состояния баланса (больше, либо меньше лимита), статуса договора, статуса сервиса. Сервис подключен, когда в договоре установлен активный для него статус, сервис в статусе открыт и баланс больше лимита.

В зависимости от настроек типа сервиса в редакторе сервиса могут присутствовать различные поля. Обязателен тип, период, статус, количество сессий, устройство. Устройство может быть указано постоянным для всех сервисов одного типа с помощью переменной в конфигурации типа сервиса. Это может быть необходимым в случае идентификации по логину. Привязка к устройствам необходима для возможности разделения базы сервисов модуля. IP-адрес (диапазон) при сохранени проверяется на вхождение в ресурс .Для того, чтобы выбрать свободный адрес из ресурсов, нужно нажать на кнопку "<<<" возле адреса.

Тут можно указать диапазон и количество адресов в диапазоне, либо сеть и маску сети. Адрес выбирается из категории ресурса. Алгоритм определения категории такой:

Если интерфейс является обязательным полем и в настройке интерфейса, с которого идет трафик указана категория IP-адресов, то выбирается эта категория. В противном случае в конфигурации устройства ищется опция

ip.resource.categoryId=1

Где 1-это код категории IP-адресов. Тут можно указать несколько категорий через запятую.

Нажатие кнопки "<<<" возле поля выбора VLAN (если это поле указано как обязательное в типе сервиса ) выбирает первый свободный VLAN из ресурсов. Свободными считаются те, которые выбраны уже на другом сервисе.

Ресурсы VLAN выбираются из категории, которая определяется опцией в конфигурации устройства:

vlan.resource.category=1

Где 1-это код категории VLAN.

Нажатие кнопки "<<<" возле поля выбора интерфейса (если это поле указано как обязательное в типе сервиса ) выбирает первый свободный интерфейс из ресурсов. Доступны те интерфейсы, которые имеют статус Доступен на устройстве и не выбраны уже на другом сервисе.

На вкладке Опции сервиса указываются статически определённые для данного сервиса опции.

При активации сервиса первыми применяются опции, указанные в сервисе, после чего - опции из тарифного плана. Конкретная реализация опций: RADIUS-атрибуты, либо какие-то правила файрвола, задаются классом обработчиком активации сервиса для конкретного типа устройства, либо процессором Access-сервера.

Вкладка Учётные периоды настроек модуля определяет учётные периоды. Периоды активируются скриптами по различным событиям. К периодам могут быть привязаны диапазоны наработки тарифных планов.

Для сервисов, в которых вводится логин возможна генерация логина/пароля автоматически. Ввод логина выглядит так:

Сгенерировать логин или пароль автоматически можно, если проставить галочку авто. Параметры для автоматической генерации можно посмотреть тут.

10.1. Шаблоны договоров

В шаблоне договора можно указать автоматическое добавление сервиса при создании договора. Для этого, кроме простого добавления модуля, нужно установить галочку Выполнить на вкладке Создать сервис и указать параметры, которые будут применяться к каждому автоматически добавляемому сервису: тип сервиса, статус по умолчанию, кол-во сессий по умолчанию.

Тип сервиса необходимо выбирать только из тех, у которых указан параметр const.device.id, чтобы при создании сервиса он был привязан к определенному устройству. Исключение составляет только шаблон договора для создания по карточкам модуля Card. В последнем случае, если const.device.id не указан, сервис будет привязан к тому устройству, с которого происходила активация карты.

Дополнительно можно указать опции, которые будут привязаны к добавляемому сервису.

10.2. Дочерние сервисы

При инициации сессии по трафику, когда обсчет идет по netflow/sFlow, а сессии создаются по наличию трафика и закрываются, когда трафика нет определенное время, возможна ситуация, когда необходимо обсчитывать несколько подсетей, но управление устройством осуществляется в одном месте. Т.е. точка подключения одна, а обсчитываемых диапазонов - несколько. В этом случае понадобятся дочерние сервисы - они предназначены только для обсчета, а не для управления.

Для того, чтобы появилась возможность добавлять дочерние сервисы на родительский необходимо сначала создать тип сервиса, в котором не установлены галочки устройство, интерфейс/vlan (все это указывается на родительском сервисе), а на закладке Родительские типы необходимо указать тип (или типы) сервиса, который будет являться родительским для данного.

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

Если же выделен сервис, у типа которого есть дочерние типы (т.е. те, у которых указан родительский тип, тот же что и тип выделенного сервиса), то в редакторе будут доступны для выбора только эти дочерние типы и сервис после сохранения добавится как дочерний к тому, что был выделен перед добавлением.

Т.к. дочерний сервис не является точкой подключения, у него нет собственного статуса и состояния - они наследуются от родительского сервиса.

10.3. Поиск сервиса.

В модуле inet возможен поиск по логину, IP-адресу, названию, типу, идентификатору, VLAN, МАС-адресу сервиса. Доступен на вкладке "Поиск".

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

11. Тарифные планы

Тарифные планы обязательно содержат информацию о отнесении типов трафика к той или иной услуге и стоимости единиц типа трафика. Дополнительно в них могут быть указаны параметры сервиса (опции). Порядок просмотра тарифных планов соответствует Алгоритму 2.

В тарифном запросе передаются следующие параметры:

идентификатор учётного периода;
время потребления;
тарифные опции;
перечень потреблённых после последней тарификации типов трафика и их объёмы.

Внимание

После редактирования тарифного дерева необходимо вызвать контекстное меню у главной ветки модуля в дереве (при редактировании дерева она подсвечивается рыжим цветом) и выбрать Оповестить об изменениях, для того чтобы все приложения обновили кэш данного тарифного дерева.

Если с момента последней тарификации изменился час, то вызываются последовательно несколько тарифных запросов, т.к. стоимость может изменится со сменой часа. В результате выполнения в тарифном запросе обязательно появляется следующая информация:

стоимость каждого из потреблённого объёмов трафика каждого вида;
услуга, к которой отнесена каждая из стоимостей.

Для каждой цены рекомендуется назначать отдельную услугу для облегчения бухгалтерской отчетности. Например услуга Включенный трафик - 0 руб./МБ и услуга Трафик - 0.10 руб./МБ.

Дополнительно в запрос можно добавить набор опций модуля Inet. Пример простейшего тарифного плана приведён на скриншоте.

Здесь трём типам трафика сопоставляются нулевые стоимости и одноимённые услуги. Кроме того, производится установка опции сервиса "Inet".

11.1. Объединение типов трафика

В ветке Трафик можно указать сразу несколько типов трафика:

11.2. Диапазоны трафика

Внутри ветки Трафик можно указывать диапазоны, внутри диапазона можно назначить отдельную цену, услугу и/или опции. Диапазон со значением 0 работает как бесконечно большой.

11.3. Пакеты трафика

С помощью тарифных опций и диапазонов, зависящих от них, можно создать пакеты трафика. Для этого необходимо создать тарифную опцию с режимом активации, например, на 1 час ровно, добавить диапазон с режимом за период тарифной опции и выбрать тарифную опцию из списка.

Если есть необходимость, в диапазоне (в последнем диапазоне тарифной опции, если их несколько) можно указать "деактивировать при превышении" - тогда при превышении диапазона опция будет деактивирована принудительно текущим временем, даже если время деактивации уже проставлено. Например, опция активирована на 1 час, но диапазон потрачен за полчаса - время деактивации опции будет перенесено на текущий момент, чтобы клиент мог активировать опцию заново.

11.4. Опции модуля и "турбо-кнопка"

При помощи опций модуля Inet можно, например, регулировать скорость соединения. А при помощи тарифных опций настроить "турбо-кнопку", которая будет действовать на период активированной опции:

Здесь, при активности тарифной опции "Турбо супер" будут отрабатывать первая ветка Тарифные опции, при неактивности - вторая (т.к. она пуста и выше ни одна ветка Тарифные опции не отработает).

Если же "турбо-кнопка" должна быть ограничена не только по времени действия тарифной опции, а также по объему трафика, необходимо использовать диапазон с привязкой к тарифной опции:

11.5. Превалирующий трафик

Для подсчета превалирующего трафика из двух типов трафика нужно использовать ветку Превалирующий трафик.

При отсутствии внутри ветки превалирующего трафика зависимостей цены от какого-либо временного промежутка, стоимость за период ветки будет равна стоимости максимального трафика, помноженного на цену.

В других случаях стоимость может "плавать", т.к. в один момент времени превалирующим может быть первый трафик, в другой момент - второй, а за время, пока второй трафик "догоняет" первый наработки соостветственно не будет, т.е. трафик будет превалирующим.

11.6. Дополнительные ветки тарифного дерева

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

Ветка Фильтр по реалму производит фильтрацию по указанным реалмам, т.е.если текущий REALM (по умолчанию - default) не входит в список, то тарифный запрос не попадет внутрь. Если на том же уровне есть ветка с пустым набором REALMов, а ни в одну из веток Фильтр по реалму, которые находятся выше на том же уровне запрос не попал, то эта пустая ветка отработает, т.е. запрос попадет внутрь этой ветки. Для сессий с типом инициации по трафику REALM всегда default.

Ветка Фильтр по группе договоров фильтрует по указанным группам договоров, т.е. запрос попадет внуть этой ветки, только, если группы обсчитываемого договора совпадают с фильтром. Если на том же уровне есть ветка с пустым набором групп, а ни в одну из веток Фильтр по группе договоров выше на этом же уровне запрос не попал, эта пустая ветка отработает.

Если запрос попал в ветку Запрещенные устройства, а авторизация происходит на одном из указанных устройств или на одном из потомков указанных устройств, то в авторизации будет отказано с кодом 40 "Доступ к устройству (NAS'у) закрыт".

Если запрос попал в ветку Разрешенные устройства, а авторизация не происходит на одном из указанных устройств или на одном из потомков указанных устройств, то в авторизации будет отказано с кодом 40 "Доступ к устройству (NAS'у) закрыт".

Если запрос попал в ветку Отказать в авторизации, то в авторизации будет отказано с кодом 44 "Доступ приостановлен".

12. Сессии

В ходе жизненного цикла сессия, привязанная к устройству, проходит несколько статусов: ожидание (waiting), активна (working), приостановлена (suspended), закрыта (closed) и завершена (finished). Сессии могут создаваться/закрываться по сигналу (RADIUS, DHCP), либо по наличию трафика (netflow/sflow) и его отсутствию в течение какого-то времени (автосессии).

При типе инициации "по сигналу" соединение может быть приостановлено, а затем закрыто при отсутствии в течение определённого времени пакетов, подтверждающих её активность (RADIUS-Update, DHCP-Request). Таймауты после последнего подобного пакета задаются в секундах переменными конфигурации устройства connection.suspend.timeout (таймаут после последнего подтверждающего пакета, после которого соединение будет считаться приостановленным) и connection.close.timeout (таймаут после последнего подтверждающего пакета, когда соеденение будет закрыто, если оно уже приостановлено). Приход подтверждающего пакета переводит соединение из приостановленного статуса в активный. Значения параметры connection.suspend.timeout и connection.close.timeout рекомендуется указывать чуть больше, чем 2 * (время между RADIUS/DHCP пакетами). При завершении соединения по сигналу Stop-пакетом (RADIUS-Stop) оно фактически завершается через количество секунд, определяемое переменной connection.finish.timeout. Это позволяет, в частности, реализовать сбор "запоздалой" информации о трафике, которая может прийти после Stop-пакета.

Внимание

После перезапуска Accounting для всех сессий считает время последней активности от момента старта. Это сделано для того, чтобы при возможном долгом простое Accounting после запуска не начал завершать все сессии по таймауту.

Для автоматических сессий (сессий по трафику) параметр connection.close.timeout определяет время в секундах после последнего поступления информации о трафике данной сессии, по прошествии которого, сессия будет завершена. Для таких сессий не рекомедуется устанавливать слишком маленькое значение connection.close.timeout. Параметр connection.auto.minDuration указывает минимальную длительность для сессии по трафику. Рекомендуемые значения для сессий по трафику:

connection.close.timeout=3600
connection.auto.minDuration=1800

Приостановленная сессия не учитывается в ограничении на количество сессий, однако её IP-адрес не выдаётся до тех пор, пока она не завершена.

Также как у сервиса, у сессии может быть состояние: подключена или отключена. Состояние "подключена" означает, что доступ открыт, клиент может нормально работать, "отключена" - используется для схем без физического отключения сессий, например, когда вместо PoD-пакета при нехватке денег на балансе отправляется CoA с запретом всех направлений, кроме сервера статистики; или при инициации сессии по трафику, когда доступом управляет коммутатор: в состоянии "отключена" тарификация сессии не производится.

По умолчанию состояние сессии всегда "подключена". Переключить состояние сессии можно в обработчике процессора протокола при приходе update-пакета RADIUS (или же start/stop пакета сервисной сессии), в зависимости от содержимого этого пакета: request.setOption( InetRadiusProcessor.DEVICE_STATE, InetServ.STATE_ENABLE ) или request.setOption( InetRadiusProcessor.DEVICE_STATE, InetServ.STATE_DISABLE ). А также в обработчике активации сервисов, если по RADIUS-пакетам не ясно в каком состоянии сессия: для этого в connectionModify( e ) при обработке переключения доступа нужно установить e.setConnectionStateModified( true ).

Для сессий в состоянии "отключена" можно назначить другие значения таймаутов после последнего RADIUS-пакета: connection.disable.suspend.timeout (по умолчанию равен значению connection.suspend.timeout) и connection.disable.close.timeout (по умолчанию равен значению connection.close.timeout), т.к. на отдельных маршрутизаторах для сессий в таком состоянии можно увеличить интервал посылки update-пакетов.

При работе с RADIUS, если по Start-пакету нельзя определить в каком состоянии началась сессия или ни в Start-пакете, ни в Update от NASа не приходит IP-адрес, в конфигурации устройства - NAS'а, или в конфигурации его типа устройства, или в одном из предков следует указать параметр connection.start.fromAccess=1. В этом режиме при отправке Access-сервером Access-Accept в ответ на Access-Request в базу будет добавлена запись по сессии в статусе ожидание (waiting), которую считает Accounting-сервер при получении Start-пакета. По умолчанию этот режим отключен.

Бывают ситуации, когда start-пакет не дошел до Accounting-сервера. В этом случае, при connection.start.fromUpdate=1 (значение по умолчанию) сессия создастся от текущего момента. При connection.start.fromUpdate=2 Accounting проверит, что время сессии из update/stop пакета не больше, чем значение connection.close.timeout и создаст сессию от ее начала, иначе, если время сессии больше чем connection.close.timeout, сессия создастся от текущего момента. При connection.start.fromUpdate=0 сессия без старт-пакета создана не будет.

При наступлении нового дня происходит логический разрыв сессии, т.е. сессия заканчивается в 23:59:59 предыдущего дня и начинается новая в 00:00:00 нового дня. Также для правильного переобсчета сессия логически разрывается при активации или деактивации тарифной опции. При посервисном аккаунтинге (SmartEdge или ISG) необходимость в разрыве отпадает, для того, чтобы отключить этот режим, в конфигурации нужно указать session.split.onTariffOption=0.

При использовании схем без физического отключения сессий (исключая посервисный аккаунтинг) или при инициации сервиса по трафику для правильного переобсчета необходимо также логически разрывать сессию при переключении ее состояния (подключена/отключена). Для этого в конфигурации нужно указать session.split.onDeviceState=1.

Пример конфигурации устройства:

# При выдаче Access-Accept добавлять запись в базу;
# необходимо, если используется Reject-to-Accept и по Start-пакету нельзя определить в каком состоянии соединение
#connection.start.fromAccept=0
# При создании сессии по Update-пакету, 0 - не создавать сессии без Start-пакета, 1 - создать сессию от текущего момента,
# 2 - создавать сессию от реального времени начала, если время сессии не больше connection.close.timeout
#connection.start.fromUpdate=1

# Таймаут перевода соединения в статус suspended при остутствии RADIUS-пакетов
connection.suspend.timeout=900
# Таймаут перевода соединения в статус suspended при остутствии RADIUS-пакетов для сессии в состоянии отключен
# (по умолчанию используется значение connection.suspend.timeout)
#connection.disable.suspend.timeout=900
# Таймаут закрытия соединения при остутствии RADIUS-пакетов или, для сессий, создаваемых по наличию трафика, при отсутствии flow-пакетов
# (не складывается с connection.suspend.timeout)
connection.close.timeout=130
# Таймаут закрытия соединения при остутствии RADIUS-пакетов или, для сессий, создаваемых по наличию трафика, при отсутствии flow-пакетов
# в состоянии отключен (не складывается с connection.disable.suspend.timeout, по умолчанию используется значение connection.close.timeout)
#connection.disable.close.timeout=1300
# Таймаут завершения закрытой сессии
connection.finish.timeout=5

# Нужно ли логически разрывать сессию при переключении состояния
session.split.onDeviceState=0
# Нужно ли логически разрывать сессию при активации или деактивации тарифной опции
session.split.onTariffOption=1

13. Общий алгоритм модуля, установка и принципы настройки серверов

Замечание

BGInetAccess и BGInetAccounting обновляются как обычные серверные приложения биллинга. Необходимо обновить каждое из приложений перед первым запуском.

Внимание

В документации представлены общие настройки. Примеры для конкретных схем вы можете найти на BGBilling Wiki.

В модуле представлены два типа серверов: Access и Accounting. Первый тип отвечает за управлением доступом сервисов и параметрами оказания услуг: скорость, перенаправления, различные ограничения и т.п. Второй тип производит тарификацию сессий. Оба типа серверов по сути своей являются контейнерами, в которых могут быть запущены Слушатели, поддерживающие протоколы (RADIUS, DHCP, NetFlow-сервера). Обработку пакетов слушателей выполняют Обработчики, которые также определяются в конфигурации.

13.1. Установка серверов.

Установка Access и Accounting-серверов просходит одинаково. Разница только в названиях папок, служб и системных переменных.

13.1.1. Установка Access-сервера.

13.1.1.1. Установка на платформу Linux

1) Извлеките BGInetAccess из архива и скопируйте в каталог /usr/local;

2) Перейдите в каталог /usr/local/BGInetAccess;

3) Удалите все .ini, .bat и .exe файлы:

rm -f ./*.bat & rm -f ./*.exe & rm -f ./*.ini

4) Откройте для редактирования файл setenv.sh и пропишите в нем путь к Java-машине, например так:

...
	cd ${0%${0##*/}}.
	
	JAVA_HOME=/opt/java/jdk16
	
	if [ -z "$JAVA_HOME" ]; then
	  echo "The JAVA_HOME environment variable is not defined"
	  echo "This environment variable is needed to run this program"
	  exit 1
	fi
	...

5) Проверьте .sh файлы на наличие символов ^M, если символы присутствуют их можно удалить вручную, либо воспользоваться утилитой:

dos2unix *.sh

6) Установите права запуска для всех *.sh файлов:

chmod 744 *.sh

7) Возьмите из каталога BGInetAccess/script скрипт запуска bginet_access и скопируйте его в каталог /etc/init.d, установите права на исполнение (см. выше). Если вы изменили каталог установки или переименовывали BGInetAccess, скорректируйте скрипт.

8) Выясните текущий уровень запуска системы командой:

[root@gate init.d]# runlevel
	N 3

9) Создайте линк для автоматического запуска Access-сервера:

ln -s /etc/init.d/bginet_access  /etc/rcN.d/S99bginet_access

где N - требуемый уровень запуска.

10) Произведите настройку inet-access.xml;

11) Обновитe как обычные серверные приложения биллинга;

11) Для запуска и останова сервера BGInetAccess используйте скрипты access_start.sh и access_stop.sh.

Замечание

При необходимости установки нескольких BGInetAccess-серверов на одной машине конечный каталог может быть переименован, например, в BGInetAccessVPN. Также требуется переименование и корректировка скрипта запуска, разнесение портов в inet-access.xml.

13.1.1.2. Установка на платформу Windows

Для установки BGInetAccess на платформу Windows на диск С:.

1) Убедитесь, что на машине, где вы собрались ставить BGInetAccess стоит Java-машина. Если её нет, установите версию не меньше 1.6.20. Загрузить можете с нашего сайта;

2) Загрузите с сервера BGInetAccess;

3) Распакуйте архив на диск C:;

4) Установите переменную окружения BGINET_ACCESS_HOME=C:\BGInetAccess. Как устанавливать переменные окружения можете посмотреть в инструкции по установке сервера и клиента биллинга;

5) Установите службу BGInetAccess, для чего запустите файл access_install.bat;

6) Убедитесь, что служба появилась в списке служб Windows. В дальнейшем, можете удалить эту службу, используя access_uninstall.bat;

7) Обновитe как обычные серверные приложения биллинга;

8) Для запуска и останова сервера BGInetAccess используйте консоль запуска и управления службами, служба BGInetAccess.

13.1.2. Установка Accounting-сервера.

13.1.2.1. Установка на платформу Linux

1) Извлеките BGInetAccounting из архива и скопируйте в каталог /usr/local;

2) Перейдите в каталог /usr/local/BGInetAccounting;

3) Удалите все .ini, .bat и .exe файлы:

rm -f ./*.bat & rm -f ./*.exe & rm -f ./*.ini

4) Откройте для редактирования файл setenv.sh и пропишите в нем путь к Java-машине, например так:

...
	cd ${0%${0##*/}}.
	
	JAVA_HOME=/opt/java/jdk16
	
	if [ -z "$JAVA_HOME" ]; then
	  echo "The JAVA_HOME environment variable is not defined"
	  echo "This environment variable is needed to run this program"
	  exit 1
	fi
	...

5) Проверьте .sh файлы на наличие символов ^M, если символы присутствуют их можно удалить вручную, либо воспользоваться утилитой:

dos2unix *.sh

6) Установите права запуска для всех *.sh файлов:

chmod 744 *.sh

7) Возьмите из каталога BGInetAccounting/script скрипт запуска bginet_accounting и скопируйте его в каталог /etc/init.d, установите права на исполнение (см. выше). Если вы изменили каталог установки или переименовывали BGInetAccounting, скорректируйте скрипт.

8) Выясните текущий уровень запуска системы командой:

[root@gate init.d]# runlevel
	N 3

9) Создайте линк для автоматического запуска Accounting-сервера:

ln -s /etc/init.d/bginet_accouting /etc/rcN.d/S99bginet_accouting

где N - требуемый уровень запуска.

10) Произведите настройку inet-accounting.xml;

11) Обновитe как обычные серверные приложения биллинга.

11) Для запуска и останова сервера BGInetAccounting используйте скрипты accounting_start.sh и accounting_stop.sh.

Замечание

При необходимости установки нескольких BGInetAccounting-серверов на одной машине конечный каталог может быть переименован, например, в BGInetAccountingVPN. Также требуется переименование и корректировка скрипта запуска, разнесение портов в inet-accounting.xml.

13.1.2.2. Установка на платформу Windows

Для установки BGInetAccounting на платформу Windows на диск С:.

1) Убедитесь, что на машине, где вы собрались ставить BGInetAccounting стоит Java-машина. Если её нет, установите версию не меньше 1.6.20. Загрузить можете с нашего сайта;

2) Загрузите с сервера BGInetAccounting;

3) Распакуйте архив на диск C:;

4) Установите переменную окружения BGINET_ACCOUNTING_HOME=C:\BGInetAccounting. Как устанавливать переменные окружения можете посмотреть в инструкции по установке сервера и клиента биллинга;

5) Установите службу BGInetAccounting, для чего запустите файл accounting_install.bat;

6) Убедитесь, что служба появилась в списке служб Windows. В дальнейшем, можете удалить эту службу, используя accounting_uninstall.bat;

7) Обновитe как обычные серверные приложения биллинга.;

8) Для запуска и останова сервера BGInetAccounting используйте консоль запуска и управления службами, служба BGInetAccounting.

13.2. Общая часть конфигурации

Слушатели, процессоры и другие сущности контейнера определяются в конфигурационном файле inet-access.xml, либо inet-accounting.xml.

Рассмотрим общую часть XML-конфигурации обоих серверов.

<?xml version="1.0" encoding="UTF-8"?>
<application context="access">
 <!-- Уникальное имя приложения -->
 <param name="app.name" value="BGInetAccess"/>
 <!-- Уникальный числовой id приложения -->
 <param name="app.id" value=""/>

 <!-- Параметры подключения к БД -->
 <param name="db.driver" value="com.mysql.jdbc.Driver"/>
 <param name="db.url" value="jdbc:mysql://127.0.0.1/bgbilling?useUnicode=true&amp;characterEncoding=UTF-8&amp;allowUrlInLocalInfile=true&amp;zeroDateTimeBehavior=convertToNull&amp;jdbcCompliantTruncation=false&amp;queryTimeoutKillsConnection=true"/>
 <param name="db.user" value="bill"/>
 <param name="db.pswd" value="bgbilling"/>

 <!-- Параметры подключения к MQ -->
 <param name="mq.url" value="failover:(tcp://localhost:61616)"/>
 <param name="mq.user" value="bill"/>
 <param name="mq.pswd" value="bgbilling"/>

 <!-- id модуля -->
 <param name="moduleId" value=""/>
 <!-- id корневого устройства -->
 <param name="rootDeviceId" value=""/>

 <param name="datalog.radius.dir" value="data/radius"/>
 <param name="datalog.dhcp.dir" value="data/dhcp" />
 ....

Параметры:

app.name определяет имя приложения, оно используется, например в системе алармов;
app.id - уникальный числовой идентификатор приложения среди всех приложений биллинга с данным параметром в XML-конфигурации, значение его не должно меняться всё время жизни системы;
moduleId - код экземпляра модуля Inet, к которому относится сервер.

Далее следуют стандартные параметры с настройкой доступа к серверу БД и к MQ-серверу (серверам).

Каждый сервис привязан к своему устройству. В конфигурации каждого из серверов Access и Accounting указывается корневое устройство, от которого, включительно, начинается загрузка в память устройств и сервисов. Код этого устройства указывается в параметре rootDeviceId.

Параметры вида datalog.* определяют каталоги для хранения бинарных логов RADIUS, DHCP, NetFlow-пакетов. Хранение данных Access-сервером необходимо для возможности по запросу предоставления пакетов авторизации сессии в интерефейсе клиента. Хранение данных Accounting-сервером позволяет выполнять переобработку логов. Access-сервер хранит RADIUS (Access-запросы) и DHCP-пакеты. Accounting - RADIUS (Accounting-запросы) и NetFlow-пакеты. Хранение в бинарном виде в файлововй системе позволяет разгрузить БД от большого объёма информации. Логи сохраняются с разбивкой по каталогам устройств-источников.

Каждому устройству может быть сопоставлен свой объект класса-активатора сервисов и объект класса-процессора протокола. Классы объектов указываются в настройках типа устройства, классы должны расширять абстрактные классы ru.bitel.bgbilling.modules.inet.access.sa.ServiceActivatorAdapter и ru.bitel.bgbilling.modules.inet.access.sa.ProtocolHandlerAdapter соответственно. В момент старта сервера для каждого устройства, в типе которого указанны классы, создаётся отдельный объект и вызывается метод init, в котором могут быть считаны параметры конфигурации. Все методы объекта класса-обработчика активации вызываются последовательно от устройства далее у всех его предков до корневого узла сервера, что позволяет производить настройки в иерархии устройств.

При создании сервиса на устройстве, к которому оно привязано, вызывается метод serviceCreate объекта класса-активатора. В этом методе возможно указание настроек, которые должны быть добавлены на устройство только при создании сервиса. Этот же метод вызывается, когда сервис был добавлен будущим числом и это число наступило. При удалении сервиса или истечении даты его закрытия на устройстве вызывается метод serviceCancel.

Опции могут быть определены на сервисе и сессии. Помимо опции у сервиса определяется его состояние. С помощью опций сервиса возможно управление параметрами статического доступа. При этом нет необходимости в потреблении сервисом трафика, нет необходимости в сессиях. Опции указываются непосредственно в свойствах сервиса. При изменении статуса сервиса или опций сервиса вызывается метод объекта класса-активатора устройства serviceModify.

Сервис потребляет услуги модуля в ходе сессий, при этом для тарификации используются тарифные планы. Каждая сессия привязана к устройству, не обязательно к тому, к которому привязан сервис. Логика привязки сессии к устройству определяется слушателем (RADIUS, DHCP, NetFlow), об этом будет описано позднее. В конфигурации того устройства, к которому привязана сессия, может быть определено устройство, с которого получается информация по трафику данной сессии. Устройства и интерфейсы определяется переменной: flow.agent.link=<device_id>:<iface_id>

Где:

<device_id> - код устройства, с которого снимается трафик;
<iface_id> - код интерфейса устройства, через который выходит трафик сессии.

Например:

flow.agent.link=1:-1

Указание другого устройства, отличного от устройства сессии имеет смысл при съёме трафика по протоколу NetFlow с вышестоящего роутера. Код интерфейса при этом должен совпадать с кодом интерфейса, идущим во Flow-записях и обозначающий интерфейс роутера, смотрящий на устройство сессии. Более подробно об это переменной можно просчитать тут.

Сессия сервиса также обладает набором опций, который состоит из опций сервиса и опций тарифного плана. Второй набор опций может менятся в ходе тарификации. Первый - в результате правки сервиса. При изменении параметров сессии в объекте класса-активатора устройства, к которому привязана сессия вызываются метод connectionModify. При завершении - connectionClose. Для старта сессии необходимо наличие NetFlow-трафика по IP-адресу сервиса, либо наличие сигнала (RADIUS, DHCP).,

Как уже указывалось ранее, в конфигурации серверов могут быть указаны слушатели, рассмотрим их.

13.3. Слушатель InetRadiusListener

Слушатель предназначен для обработки RADIUS-пакетов. Общие сведения о протоколе RADIUS доступны здесь.

Добавляется в контейнер следующим образом.

 <context name="radius">
	 <!-- Cоздание процессора RADIUS-пакетов -->
  <bean name="radiusProcessor" class="ru.bitel.bgbilling.modules.inet.radius.InetRadiusProcessor"/>
  
  <!-- Служебный ScheduledExecutorService, необходимый для dataLogger -->
  <scheduledExecutorService name="hrlydtlggr" corePoolSize="1" />

  <!-- Cоздание dataLogger, сохраняющего RADIUS-пакеты на диск (только один экземпляр) -->
  <bean name="radiusDataLogger" class="ru.bitel.bgbilling.modules.inet.radius.RadiusHourlyDataLogger">
   <param name="scheduledExecutor">hrlydtlggr</param>
  </bean>

  <!-- Cоздание слушателя RADIUS-пакетов на порту с передачей ему процессора и dataLogger -->
  <bean name="radiusListener" class="ru.bitel.bgbilling.modules.inet.radius.InetRadiusListener">
   <constructor>
    <!-- Хост (интерфейс), на котором будет открыт сокет. Если пусто - на всех -->
    <param name="host" value=""/>
    <!-- Порт, на котором будет открыт сокет -->
    <param name="port" value="1812"/>
    <!-- Размер буфера приема слушателя -->
    <param name="recvBufferSize">512 * 1024</param>
    <!-- Рекомендуемый SO_RCVBUF-сокета -->
    <param name="soRCVBUF"></param>
    <!-- Количество потоков-обработчиков -->
    <param name="threadCount">10</param>
    <!-- Максимальное количество пакетов в очереди на обработку -->
    <param name="maxQueueSize">200</param>
    <!-- Передача процессора -->
    <param name="processor">radiusProcessor</param>
    <!-- Режим работы, RadiusListener.Mode.authentication -->
    <param name="mode">RadiusListener.Mode.authentication</param>
    <!-- Передача dataLogger -->
    <param name="dataLogger">radiusDataLogger</param>
   </constructor>
  </bean>
 </context>

Параметры:

radiusProcessor - класс процессора, реализующий логику обработки пакетов;
radiusDataLogger - объект, осуществляющий запись бинарных логов, по умолчанию это объект типа ru.bitel.bgbilling.modules.inet.radius.RadiusHourlyDataLogger (сохранение бинарных логов с разбивкой по источникам и часам);
host - IP-адрес, на котором слушатель, пустое значение - прослушивать любой IP-адрес;
port - прослушиваемый UDP-порт;
soRCVBUF - рекомендуемый SO_RCVBUF (socket recieve buffer) для сокета. На FreeBSD большие значения могут вызвать ошибку и сервер не запустится;
byteBufferCapacity - размер буфера для приёма пакетов;
threadCount - число потоков-обработчиков пакетов, рекомендуемые значения 10-30, не рекомендуется указывать более 100;
maxQueueSize - максимальный размер очереди пакетов, при превышении размера очереди пакеты начинают отбрасываться и высылается аларм, рекомендуемые значения 200-1000. Следует учитывать, что если по какой-то причине сервер не успевает обрабатывать пакеты, очередь растет, то какие-то пакеты из очереди могут быть обработаны с опозданием и NAS уже выслал повторный запрос, который опять попадет в очередь и опять может быть обработан с опозданием. Поэтому большое значение вместо распределения нагрузки может вызвать ее увеличение;
mode - режим работы, может принимать значения RadiusListener.Mode.authentication для обработки Access-Request-пакетов в InetAccess и RadiusListener.Mode.accounting для обработки Accounting-пакетов в InetAccounting.

13.3.1. Процессор ru.bitel.bgbilling.modules.inet.radius.InetRadiusProcessor

Предназначен для авторизации и аккаунтинга по протоколу RADIUS большинства типов коммутируемых соединений.

Загружает список NAS'ов из дочерних узлов корневого узла сервера, начиная с самого корневого узла. Если нужно фильтовать по типам устройств (т.е. какие-то дочерние узлы не учитывать как NAS'ы), то в конфигурации корневого устройства в параметре radius.deviceTypeIds необходимо указать id типов устройств-NAS'ов через запятую. У устройства-NAS'а поле Идентификатор должно быть заполнено.

Поиск NAS'а для пришедшего пакета производится сначала по атрибуту NAS-Identifier с поиском по идентификатору устройства, затем, если устройство не найдено, по NAS-IP-Address с поиском по хостам устройств. Сессия сервиса привязывается к устройству, представляющему NAS.

При авторизации поиск сервиса может осуществляться как по логину, так и по интерфейсу или VLAN'у. Для указания режима поиска необходимо прописать в конфигурации устройства-NAS'а или в конфиге любого его устройства-предка параметр:

# Режим поиска сервиса: 0 (по умолчанию) - по логину, 1 - по интерфейсу на устройстве (в предобработке должны быть
# проставлены опции AGENT_REMOTE_ID и AGENT_CIRCUIT_ID или INTERFACE_ID), 2 - по VLAN на устройстве (в предобработке
# должны быть проставлены опции AGENT_REMOTE_ID и AGENT_CIRCUIT_ID или VLAN_ID), 4 - по VLAN на устройстве или
# дочернем устройстве (в предобработке должны быть проставлены опции AGENT_REMOTE_ID и AGENT_CIRCUIT_ID или VLAN_ID),
# 5 - по MAC-адресу на устройстве (в предобработке должна быть проставлена опция MAC_ADDRESS), 6 - по MAC-адресу на
# устройстве или дочернем устройстве (в предобработке должна быть проставлена опция MAC_ADDRESS).
radius.servSearchMode=0

По умолчанию поиск сервиса происходит по значению атрибута User-Name, по его совпадению с логином сервиса. После логина в атрибуте User-Name может быть указан реалм c разделителем @, например "vasya@local". Если реалм не указан, то предполагается, что пользователь использует реалм default. При этом принудительное указание реалма default (например, "vasya@default") не допускается.

Внимание

По умолчанию перед поиском сервиса по логину из User-Name удаляется значение домена и не удаляются пробелы в начале и в конце. Также поиск идет с учетом регистра. Изменить поведение можно в конфигурации устройства (см. Пример конфигурации устройства-NAS'а).

radius.servSearchMode может принимать значения:

0 - поиск по логину из атрибута User-Name;
1 - поиск по интерфейсу на (найденном) устройстве;
2 - поиск по VLAN'у на устройстве (в предобработке должны быть проставлены опции AGENT_REMOTE_ID и AGENT_CIRCUIT_ID или VLAN_ID);
4 - поиск по VLAN'у на устройстве и его дочерних устройствах (в предобработке должны быть проставлены опции AGENT_REMOTE_ID и AGENT_CIRCUIT_ID или VLAN_ID);
5 - поиск по MAC-адресу на устройстве (в предобработке должна быть проставлена опция MAC_ADDRESS);
6 - поиск по MAC-адресу на устройстве и дочерних устройствах (в предобработке должна быть проставлена опция MAC_ADDRESS);
7 - поиск по адресу, указанному в User-Name, из диапазона адресов сервиса (в типе сервиса должно быть указано serv.search.address=1).

Также возможен дополнительный поиск дочернего сервиса:

radius.servSearchMode=<servSearchMode>-<subServSearchMode>

<subServSearchMode> может принимать значения:

0 или отсутсвует - нет поиска дочернего сервиса
1 - поиск дочернего сервиса по MAC-адресу, если такого дочернего сервиса нет - ошибка авторизации;
2 - поиск дочернего сервиса по MAC-адресу, если такого дочернего сервиса нет - сессия будет привязана к родительскому сервису.

Список допустимых реалмов указывается в параметре устройства/типа сервиса radius.realm через запятую, например:

#radius.realm=default
radius.realm=default, local

Параметр может быть указан как в конфигурации устройства (или типа устройтва), так и в конфигурации типа сервиса - в последнем случае значение будет главнее, чем тот же параметр в конфигурации устройства. По умолчанию допускается только реалм default.

При поиске по интерфейсу или VLAN'у, сервис может быть привязан к дочернему для NAS'а устройству - например, в случае Cisco ISG или Redback CLIPS - сервис привязан к коммутатору, NAS'ом выступает маршрутизатор. В этом случае необходимо в предобработке RADIUS-запроса установить опцию AGENT_REMOTE_ID со значением идентификатора дочернего коммутатора. Если опция будет присутствовать и такое дочернее устройство существует, то поиск сервиса будет идти относительно этого агентского устройства, иначе, по умолчанию, поиск идет относительно устройства-NAS'а.

request.setOption( InetRadiusProcessor.AGENT_REMOTE_ID, "1CBDB9E64878" );

Данную опцию необходимо устанавливать как в preprocessAccessRequest, так и в preprocessAccountingRequest. Значение обычно извлекается из RADIUS-атрибутов запроса, содержащих, например, значение субопций DHCP option 82. Значение можно установить как строкой, так и массивом байт (byte[]). В случае, если опция установлена в предобработке запроса, будет произведен поиск агентского устройства на совпадение с полем Идентификатор.

Для определения интерфейса или VLAN возможны два способа: установка опции AGENT_CIRCUIT_ID или установка напрямую опции INTERFACE_ID/VLAN_ID. В первом случае значение номера интерфейся или VLAN из опции будет извлечено по параметрам конфигурации агентского устройства dhcp.option82.interfaceId.position, dhcp.82.interfaceId.length, dhcp.option82.vlanId.position, dhcp.option82.vlanId.length. Во втором - значение должно быть равно интерфейсу или порту.

Пример (установка опций из атрибутов-значений субоций DHCP option 82):

RadiusAttribute<?> agentRemoteId = request.getAttribute( 2352, 96 );
if( agentRemoteId != null )
{
  ByteBuffer data = agentRemoteId.getData();
  data.position( 2 );
  data = data.slice();

  request.setOption( InetRadiusProcessor.AGENT_REMOTE_ID, data );
}

RadiusAttribute<?> agentCircuitId = request.getAttribute( 2352, 97 );
if( agentCircuitId != null )
{
  ByteBuffer data = agentCircuitId.getData();
  data.position( 2 );
  data = data.slice();

  // значение интерфейса или VLAN'а будет извлечено из этого параметра
  request.setOption( InetRadiusProcessor.AGENT_CIRCUIT_ID, data );
}

Пример (vlan per user - поиск по vlan):

/*
// Если агентское устройство всегда известно - раскомментарить, режим поиска 2;
// иначе - режим поиска 4 (по vlan с учетом всех дочерних устройств)
RadiusAttribute<?> agentRemoteId = request.getAttribute( 2352, 96 );
if( agentRemoteId != null )
{
  ByteBuffer data = agentRemoteId.getData();
  data.position( 2 );
  data = data.slice();

  request.setOption( InetRadiusProcessor.AGENT_REMOTE_ID, data );
}*/

Pattern vlanPattern = Pattern.compile( "(.+) vlan-id (\\d+)" );

String nasPortId = request.getStringAttribute( -1, 87, null );
if( nasPortId != null )
{
  Matcher m = vlanPattern.matcher( nasPortId );
  if( m.find() )
  {
    String vlanId = m.group( 2 );
    request.setOption( InetRadiusProcessor.VLAN_ID, vlanId );
  }
}

Таким образом для поиск сервиса возможен:

- по атрибуту User-Name (по умолчанию);
- по опциям AGENT_REMOTE_ID (идентификатор агентского устройства - устройства, на котором, собственно, интерфейс) и INTERFACE_ID (или AGENT_CIRCUIT_ID, содержащий номер интерфейса);
- по опциям AGENT_REMOTE_ID (не обязательна, если в пределах NAS'а VLAN уникальны) и VLAN_ID (или AGENT_CIRCUIT_ID, содержащий номер VLAN'а).

При аутентификации во всех случаях происходит проверка пароля, поэтому в некоторых случаях пароль нужно устанавливать на NAS'е, в коде preprocessAccessRequest или, при необходимости, отключить проверку пароля для NAS'а:

# Включение (1, по умолчанию) или отключение (0) проверки пароля для NAS'а
#radius.password.verification=1

Когда сервис определён, определяется набор атрибутов сессии, последовательным добавлением:

- атрибутов, определённых для реалма;
- атрибутов, определённых для опций.

Атрибуты реалма определяются в конфигурации устройства-NASа следующим образом:

radius.realm.<realm>.attributes=<attributes>

Где:

<realm> - реалм;
<attributes> - атрибуты.

Полный набор опций сессии определяется объединением опций, указанных в самом сервисе и опций из тарифного плана. Соответствие кодов опций атрибутам определяется в конфигурации устройства-NASа следующим образом:

radius.inetOption.<option_id>.attributes=<attributes>

Где:

<option_id> - числовой код опции;
<attributes> - RADIUS атрибуты.

Пример конфигурации, где определены атрибуты для реалмов и опций:

radius.realm.default.attributes=Service-Name:1=RSE-SVC-EXT;Service-Options:1=1

radius.inetOption.1.attributes=Service-Parameter:1=Rate=100000 Burst=12500000
radius.inetOption.2.attributes=Service-Parameter:1=Rate=100000 Burst=12500000

Выдача IP-адреса производится через атрибут Framed-Ip-Address, либо из диапазона (адреса), указанного в самом сервисе, либо, если он не указан или занят - из пула, определённого в конфигурации устройства параметром radius.realm.<realm>.ipCategories=<cat_codes>, где:

<realm> - реалм;
<cat_codes> - id коды категорий ресурсов IP-адресов через запятую.

Например:

radius.realm.default.ipCategories=4

В случае ошибки авторизации высылается пакет AUTHENTICATION_REJECT с отображением ошибки и её кода в мониторе модуля. Допустимые коды ошибок данного процессора.

Вместо AUTHENTICATION_REJECT может быть выслан AUTHENTICATION_ACCEPT-пакет с дополнительными атрибутами. Перечень кодов ошибок, для которых производится подмена Reject-To-Accept определяется переменной конфигурации NAS'а radius.disable.accessCodes=<codes>, где <codes> - перечень кодов ошибок авторизации через запятую. Например:

radius.disable.accessCodes=1,2,3,4,10,11,12

Соответственно, для Reject-To-Accept могут быть собственные диапазоны IP-адресов, например:

radius.disable.ipCategories=3

Для поддержки Reject-To-Accept при ошибке с кодом 1 (Логин не найден), т.е. для предоставления гостевого доступа, необходимо создать договор с балансом меньше лимита и сервисом модуля Inet со статусом закрыт, а id сервиса прописать в конфигурации устройства:

radius.disable.servId=<inetServId>

Таким образом, сессии с ненайденным сервисом будут привязываться к указанному сервису.

При превышении числа сессий над ограничением, установленным для сервиса, генерируется ошибка авторизации. Данная ошибка также может быть обработана механизмом Reject-To-Accept с выдачей адреса из пула фиктивных адресов.

При RADIUS Access-Request можно также использовать MAC-адрес, чтобы авторизовывать запросы только с определенным MAC-адресом. MAC-адрес из Access-Request пакета устанавливается в Обработчике процессора протокола, в методе preprocessAccessRequest: request.setOption( InetRadiusProcessor.MAC_ADDRESS, macAddress ). Стандартные обработчики процессора протокола, поставляемые с модулем уже реализуют этот функционал, нужно только прописать в конфигурации устройства или типа устройства:

# Вендор атрибута, где хранится MAC-адрес
#radius.macAddress.vendor=9
# Код атрибута, где хранится MAC-адрес
#radius.macAddress.type=1
# Префикс атрибута (если есть), где хранится MAC-адрес. Например, для cisco avpair
#radius.macAddress.prefix=client-mac-address=

Таким образом, при извлечении MAC-адреса из RADIUS-пакета, он будет сравнен с MAC-адресом из аутентифицированного сервиса при условии, что в этом сервисе заведен MAC-адрес.

Для автоматического привязывания MAC-адреса к сервису в конфигурации модуля/типа сервиса/устройства/типа устройства можно прописать:

# Нужно ли автоматически проставлять в сервис MAC-адрес, если его еще нет.
# Можно указать в конфигурации модуля, конфигурации устройства, конфигурации типа сервиса.
# 0 - не привязывать, 1 - привязывать, если поле сервиса пустое, 2 - перетирать новым значением, 3 - добавлять
# (в последних двух случаях отказа в авторизации по MAC-адресу не будет)
serv.macAddress.auto=1

Таким образом при первой удачной авторизации MAC-адрес будет привязан к сервису и с другим MAC-адресом клиент уже не сможет авторизоваться.

Аналогично MAC-адресу можно использовать поле Идентификатор сервиса. Например, в качестве идентификатора использовать значение атрибута Calling-Station-Id, устанавливая в Обработчике процессора протокола, в методе preprocessAccessRequest: request.setOption( InetRadiusProcessor.IDENTIFIER, callingStationId ).

Для автоматического привязывания идентификатора к сервису в конфигурации модуля/типа сервиса/устройства/типа устройства можно прописать:

# Нужно ли автоматически проставлять в сервис идентификатор, если его еще нет.
# Можно указать в конфигурации модуля, конфигурации устройства, конфигурации типа сервиса.
# 0 - не привязывать, 1 - привязывать, если поле сервиса пустое, 2 - перетирать новым значением, 3 - добавлять
# (в последних двух случаях отказа в авторизации по идентификатору не будет)
serv.identifier.auto=1

Для привязки сервиса к устройству - т.е. для того, чтобы клиент мог авторизоваться только на устройстве (NAS'е), привязанному к сервису, или являющимся дочерним по отношению к нему (устройству), необходимо указать в конфигурации устройства/типа устройства/типа сервиса:

# Привязка авторизации сервиса к устройству, указанному в сервисе договора
# 0 - клиент может авторизоваться на любом устройстве (NAS'е), 1 - клиент может авторизоваться только на прописанном в сервисе устройстве,
# или являющимся дочерним по отношению к нему
serv.device.link=1

При подключении абонента может быть ситуация, когда в биллинге сессия еще активная, а клиент на самом деле уже отключился и пытается подключиться заново. Это может произойти при потере связи с NAS'ом (т.е. STOP-пакет не пришел, но connection.close.timeout еще не произошел), или, например, при использовании IPoE с Cisco/Redback (когда абонент подключил другое устройство, а Cisco/Redback по таймауту DHCP-lease еще не поняли, что старое соединение можно закрывать). Для обработки такой ситуации можно использовать параметр конфигурации radius.connection.checkDuplicate. Он работает в связке с Calling-Station-Id - если происходит попытка авторизации, а количество активных соединений превышено и среди активных соединений есть соединение с таким же Calling-Station-Id, то при указании radius.connection.checkDuplicate:

1 - происходит попытка сброса старого соединения (например, отправка PoD-пакета), абонента на этой авторизации не пускаем;
2 - происходит попытка сброса старого соединения, его завершение в биллинге, абонента на этой авторизации не пускаем, должно пустить при следующей попытке, т.к. старой сессии уже не будет;
3 - происходит завершение старого соединения в биллинге, абонента на этой авторизации не пускаем, должно пустить при следующей попытке, т.к. старой сессии уже не будет;
4 - происходит попытка сброса старого соединения, затем через 5 секунд завершение в биллинге, абонента на этой авторизации не пускаем;
5 - попытка сброса старого соединения в биллинге, завершение и пускаем немедленно (т.е. игнорируется ошибка );
6 - завершение старого соединения в биллинге, пускаем абонента немедленно;
7 - попытка в течении 5 секунд сбросить соединение, затем закрытие сессии в биллинге с ожиданием полного выполнения закрытия (т.е. IP-адрес станет свободным), пускаем абонента
8 - попытка сброса и сразу закрытие в биллинге с ожиданием полного выполнения закрытия (т.е. IP-адрес станет свободным), пускаем абонента;
9 - закрытие старого соединения в биллинге с ожиданием полного выполнения закрытия (т.е. IP-адрес станет свободным), пускаем абонента.

Для более быстрого подключения абонента при использовании и динамическим адресом рекомендуем использовать 4, 5, 6. Для статических адресов (чтобы абонент мог получить свой адрес) - 8,9.

Для обработки ситуации, когда количество активных соединений превышено, но соединения с таким Calling-Station-Id не найдено, и нужно отключить просто самое старое соединение, нужно указать цифру во втором разряде, например: 88.

Для сброса соединения с таким же Calling-Station-Id, даже если количество соединений не превышено, нужно указать цифру в третьем разряде, например, 808, 909, 888 или 818.

Этот параметр можно указать для типа сервиса, в конфигурации типа сервиса: serv.radius.connection.checkDuplicate.

13.3.1.1. Посервисный аккаунтинг

Для поддержки посервисного аккаунтинга (например, при использовании Cisco ISG или Redback CLIPS) в обработчике процессора протокола необходимо указывать AcctSessionId родительского соединения (аккаунтинга) и имя сервиса (ServiceName), по которому пришел аккаунтинг-пакет: request.setOption( InetRadiusProcessor.PARENT_ACCT_SESSION_ID, parentAcctSessionId ); и request.setOption( InetRadiusProcessor.SERVICE_NAME, serviceName );

Пример для Redback SmartEdge 100:

	@Override
	public void preprocessAccountingRequest( RadiusPacket request, RadiusPacket response, ConnectionSet connectionSet )
	    throws Exception
	{
		int acctStatusType = request.getIntAttribute( -1, RadiusDictionary.Acct_Status_Type, -1 );

		switch( acctStatusType )
		{
			// если сервисный аккаунтинг
			case 101:
			case 102:
			case 103:
			{
				// получаем id родительского соединения
				final String parentAcctSessionId = request.getStringAttribute( -1, parentAcctSessionIdType, null );
				// получаем имя сервиса, по которому идет аккаунтинг
				final String serviceName = request.getStringAttribute( radiusVendor, serviceNameType, null );
				
				// подменяем Acct-Status-Type, чтобы биллинг понял типы пакетов
				request.setIntAttribute( -1, RadiusDictionary.Acct_Status_Type, acctStatusType - 100 );
				// устанавливаем id родительской сессии
				request.setOption( InetRadiusProcessor.PARENT_ACCT_SESSION_ID, parentAcctSessionId );
				// устанавливаем имя сервиса текущего аккаунтинга
				request.setOption( InetRadiusProcessor.SERVICE_NAME, serviceName );
			}
				break;

			default:
			{
			}
				break;
		}
	}

Тогда Accounting считает данное соединение как дочернее родительскому, а в поле username соединения (в базе) устанавливается ServiceName.

При обработке трафиков используется ServiceName - он может выступать в качестве фильтра правила привязки трафиков: если указано ServiceName, то данное правило будет отрабатывать только для сервисной сессии с таким ServiceName, и наоборот, если поле ServiceName в правиле пусто, то данное правило не будет отрабатывать ни для какой сервисной сессии.

В поле ServiceName можно указать несколько сервисов через запятую (RSE-SVC-EXT, RSE-SVC-EXT1024) или же указать REGEXP внутри двух слешей (/^RSE-SVC-EXT.*$/).

Например, если у вас внешний трафик идет посервисным аккаунтингом с ServiceName=RSE-SVC-EXT, то нужно назначить такую привязку:

13.3.1.2. Пример конфигурации устройства-NAS'а
# Порт для отправки PoD и CoA-запросов (по умолчанию - порт, заданный в параметрах устройства Хост/порт)
#radius.port=<порт устройства>
 
# При выдаче Access-Accept добавлять запись в базу.
# Hеобходимо, если используется Reject-To-Accept и по Start-пакету нельзя определить в каком состоянии соединение
connection.start.fromAccept=1
# Бывают ситуации, когда Start-пакет не дошел до Accounting-сервера. В этом случае, при
# 1 (значение по умолчанию) - сессия создастся от текущего момента,
# 2 - Accounting проверит, что время сессии из Update/Stop пакета не больше, чем значение connection.close.timeout и создаст сессию от ее начала, иначе,
# если время сессии больше чем connection.close.timeout, сессия создастся от текущего момента,
# 0 - сессия без Start-пакета создана не будет.
#connection.start.fromUpdate=1
# При создании сессии по Update-пакету нужно ли игнорировать отсутствие IP-адреса сессии (Framed-Ip-Address). По умолчанию сессия
# по Update-пакету без адреса не создается (0).
#connection.start.fromUpdate.ignoreFramedIpLack=0

# Таймаут перевода соединения в статус suspended при остутствии радиус пакетов
connection.suspend.timeout=900
# Таймаут закрытия соединения при остутствии радиус пакетов (не складывается с connection.suspend.timeout)
connection.close.timeout=900
# При закрытии соединения по таймауту, 0 (по умолчанию) - просто закрыть,
# 1 - попытаться сбросить также на NAS'е (вызвать connectionClose у обработчика активации сервисов)
#connection.close.timeout.forceClose=1
 
# Атрибуты, выдаваемые при авторизации по реалму default (default - реалм по умолчанию)
radius.realm.default.attributes=

# Коды ошибок, при которых отвечать Access-Accept в состоянии disable (rejectToAccept)
radius.disable.accessCodes= 
# Какие адреса выдавать при ответе Access-Accept в состоянии disable: 
# 0 (по умолчанию) - из radius.disable.ipCategories, 1 - так же, как если бы не было ошибки (в том числе привязанные к сервису в договоре)
#radius.disable.mode=0

# Атрибуты, выдаваемые при ответе Access-Accept в состоянии disable
radius.disable.attributes=

# Id фиктивного сервиса, к которому будут привязываться сессии, по которым нормальный сервис не был найден (код ошибки: 1, логин не найден).
# Необходим, если в radius.disable.accessCodes присутствует код 1
#radius.disable.servId=
 
# Атрибуты, при наличии которых соединение должно считаться в состоянии DISABLE (т.е. с ограниченным доступом)
#radius.disable.pattern.attributes=

# Вендор атрибута, где хранится MAC-адрес
#radius.macAddress.vendor=9
# Код атрибута, где хранится MAC-адрес
#radius.macAddress.type=1
# Префикс атрибута (если есть), где хранится MAC-адрес. Например, для cisco avpair
#radius.macAddress.prefix=client-mac-address=


# Режим поиска сервиса: 0 (по умолчанию) - по логину, 1 - по интерфейсу на устройстве (в предобработке должны быть
# проставлены опции AGENT_REMOTE_ID и AGENT_CIRCUIT_ID или INTERFACE_ID), 2 - по VLAN на устройстве (в предобработке
# должны быть проставлены опции AGENT_REMOTE_ID и AGENT_CIRCUIT_ID или VLAN_ID), 4 - по VLAN на устройстве или
# дочернем устройстве (в предобработке должны быть проставлены опции AGENT_REMOTE_ID и AGENT_CIRCUIT_ID или VLAN_ID),
# 5 - по MAC-адресу на устройстве (в предобработке должна быть проставлена опция MAC_ADDRESS), 6 - по MAC-адресу на
# устройстве или дочернем устройстве (в предобработке должна быть проставлена опция MAC_ADDRESS).
#radius.servSearchMode=0
# Нужно ли проверять пароль: 0 - нет, 1 (по умолчанию) - да.
#radius.password.verification=1


# Проверка на повторную аутентификацию при Access-Request. Бывает нужна в случаях, когда NAS сбрасывает (теряет) сессию, но
# Stop-пакет не присылает и клиент пытается подключиться повторно, но у него стоит ограничение на максимум одну сессию. При совпадении
# callingStationId с одной из активных сессий и установленным параметром: 1 - осуществляется попытка закрытия старой сессии (connectionClose),
# 2 - попытка закрытия сессии (connectionClose) и завершение ее в базе, не дожидаясь стоп пакета, 3 - завершение в базе.
#radius.connection.checkDuplicate=0

# Нужно ли убирать домен перед поиском сервиса по логину из поля User-Name. По умолчанию - да (1).
# Следует отключить, если при посылке CoA и PoD пакетов NAS'у необходим атрибут User-Name.
radius.username.removeDomain=1
# Нужно ли убирать пробелы из поля User-Name перед поиском логина. По умолчанию - нет (0).
# Следует отключить, если при посылке CoA и PoD пакетов NAS'у необходим атрибут User-Name.
#radius.username.removeWhitespace=0
# Должен ли поиск по логину идти без учета регистра. По умолчанию - нет (0).
#radius.username.ignoreCase=0

# Включение (1, по умолчанию) или отключение (0) проверки пароля для NAS'а
#radius.password.verification=1

# Шаблон вывода ошибки в мониторе с использованием атрибутов из RADIUS-пакета
#radius.accessError.infoPattern=LOGIN:$User-Name


# Привязка кодов опций модуля к атрибутам
# данные атрибуты будут выдаваться в AccessAccept при удачной авторизации и при наличии активных опций в тарифе или сервисе
radius.inetOption.1.attributes=
radius.inetOption.2.attributes=
radius.inetOption.3.attributes=

# Параметры активации сервисов
# длина паузы, если возникла ошибка
#sa.error.pause=60
# количество заданий за раз
#sa.batch.size=20
# время (сек) ожидания завершения всех заданий (при асинхронной работе)
#sa.batch.wait=5
# пауза (сек) после обработки заданий
#sa.batch.pause=0
# время (сек) ожидания новой задачи перед вызовом disconnect.
#sa.batch.waitNext=5
 
# Параметры обработчика активации сервисов
# откуда при отправке CoA брать атрибуты опций (по умолчанию - те же атрибуты, что выдаются при удачной авторизации)
#sa.radius.option.attributesPrefix=nas.radius.inetOption.
#sa.radius.connection.attributes=NAS-Port, Acct-Session-Id, User-Name, Framed-IP-Address, NAS-IP-Address, NAS-Identifier
# атрибуты CoA-запроса для прекращения доступа (используется при sa.radius.connection.withoutBreak=1)
#sa.radius.disable.attributes={@radius.disable.attributes}
# фиксированные атрибуты, добавляемые в запрос перед отправкой CoA
#sa.radius.coa.attributes=
# добавлять ли при отправке CoA-атрибуты реалма (для default - из radius.realm.default.attributes)
#sa.radius.realm.addAttributes=0
# фиксированные атрибуты, добавляемые в запрос перед отправкой PoD
#sa.radius.pod.attributes=

13.4. Слушатель InetDhcpListener

Предназначен для обработки DHCP-пакетов для схем DHCP.82, ISG/CLIPS+DHCP.82. Используется в InetAccess, добавляется в контейнер следующим образом:

<context name="dhcp">
  <!-- Cоздание процессора dhcp-пакетов -->
  <bean name="dhcpProcessor" class="ru.bitel.bgbilling.modules.inet.dhcp.InetDhcpProcessor"/>

  <scheduledExecutorService name="hrlydtlggr" corePoolSize="1" />

  <!-- Cоздание dataLogger, сохраняющего dhcp-пакеты на диск  -->
  <bean name="dhcpDataLogger" class="ru.bitel.bgbilling.modules.inet.dhcp.DhcpHourlyDataLogger">
    <param name="scheduledExecutor">hrlydtlggr</param>
  </bean>
 
  <!-- Cоздание слушателя dhcp-пакетов на порту с передачей ему процессора и dataLogger -->
  <bean name="dhcpListener" class="ru.bitel.bgbilling.kernel.network.dhcp.DhcpListener">
    <constructor>
      <!-- Хост (интерфейс), на котором будет открыт сокет. Если пусто - на всех -->
      <param name="host" value=""/>
      <!-- Порт, на котором будет открыт сокет -->
      <param name="port" value="67"/>
      <!-- Размер буфера приема слушателя -->
      <param name="byteBufferCapacity">512 * 1024</param>
      <!-- Количество потоков-обработчиков -->
      <param name="threadCount">10</param>
      <!-- Максимальное количество пакетов в очереди на обработку -->
      <param name="maxQueueSize">200</param>
      <!-- Передача процессора -->
      <param name="processor">dhcpProcessor</param>
      <!-- Передача dataLogger -->
      <param name="dataLogger"></param>
    </constructor>
  </bean>
</context>

Параметры:

host - IP-адрес, на котором слушатель, пустое значение - прослушивать любой IP-адрес;
port - прослушиваемый UDP порт;
byteBufferCapacity - размер буфера для приёма пакетов;
threadCount - число потоков-обработчиков пакетов, рекомендуемые значения 10-50, не рекомендуется указывать более 100;
maxQueueSize - максимальный размер очереди пакетов, при превышении размера очереди пакеты начинают отбрасываться и высылается аларм. Рекомендуемые значения 200-1000. Следует учитывать, что если по какой-то причине сервер не успевает обрабатывать пакеты, очередь растет, то какие-то пакеты из очереди могут быть обработаны с опозданием и DHCP-клиент уже выслал повторный запрос, который опять попадет в очередь и опять может быть обработан с опозданием. Поэтому большое значение вместо распределения нагрузки может вызвать ее увеличение;
dataLogger - объект, осуществляющий запись бинарных логов, по умолчанию это объект типа ru.bitel.bgbilling.modules.inet.dhcp.DhcpHourlyDataLogger (сохранение бинарных логов с разбивкой по источникам и часам);
processor - процессор, реализующий логику обработки пакетов.

13.4.1. Процессор ru.bitel.bgbilling.modules.inet.dhcp.InetDhcpProcessor

Предназначен для выдачи IP-адресов по протоколу DHCP с опцией 82. Опцию в запрос должен подставить коммутатор, пропускающий запрос, далее запрос обязательно должен переслать DHCP-Relay. Идентификация сервисов осуществляется на основании полей circuitId и remoteId, но также могут быть настроены любые другие поля, определяющие порт коммутатора клиента.

Загружает список устройств-коммутаторов, начиная с корневого узла. Типы устройств-коммутаторов определяются в переменной конфигурации корневого узла dhcp.relay.deviceTypeIds через запятую. Также загружаются привязанные к коммутаторам сервисы договоров.

Когда приходит DHCP-запрос, из него извлекается поле Relay-IP. Осуществляется поиск устройства-релея сначала по совпадению этого поля с адресом устройства в биллинге. Затем, если поиск был отрицательным - осуществляется поиск по совпадению IP-адреса, с которого пришёл DHCP-запрос с IP-адресом устройства.

Если по каким-то причинам клиентские устройства (например, NetGear JWNR2000) в DHCP-REQUEST посылают xid, отличный от DHCP-DISCOVER, можно убрать привязку к xid-запросам, прописав в конфигурации устройства-коммутратора/типа устройства/конфигурации модуля:

# Привязка к xid DHCP-запросов
# 0 - выкл., 1 (по умолчанию) - вкл.
dhcp.xid=1

Далее алгоритм работы определяется переменными конфигурации найденного устройства-релея. Следующие параметры определяют, какие опции извлекаются для идентификации устройства-коммутатора клиента и непосредственно клиента по порту или VLAN.

# Удаление заголовка, при необходимости, 0 - не удалять, 2 - 2 удалить байта (тип+длина) из значения DHCP-опции.
# При удалении поля position для agentRemoteId, vlanId, interfaceId нужно уменьшить на тоже кол-во байт
#dhcp.option82.removeHeader=0
dhcp.option82.removeHeader=2

# Параметры для извлечения из пакета agentRemoteId
# вид значения в опции agentRemoteId: 0 (по умолчанию) - байты, 1 - строка
#dhcp.option82.agentRemoteId.type=0
# код субопции 82, содержащей идентификатор коммутатора клиента, позиция и длина последовательности идентификатора
dhcp.option82.agentRemoteId.code=2
dhcp.option82.agentRemoteId.position=0
dhcp.option82.agentRemoteId.length=6

# код субопции 82, содержащей VLAN, позиция и длина в субопции
dhcp.option82.vlanId.code=1
dhcp.option82.vlanId.position=0
dhcp.option82.vlanId.length=2
# код субопции 82, содержащей интерфейс, позиция и длина в субопции
dhcp.option82.interfaceId.code=1
dhcp.option82.interfaceId.position=3
dhcp.option82.interfaceId.length=1

Параметры, описанные выше подойдут для обработки такого пакета:

Message type: BOOT_REQUEST
Dhcp message type: DHCP Discover{1}
htype: 1, hlen: 6, hops: 1
xid: 1067065417, secs: 0, flags: 0
Client IP: 0.0.0.0
Your IP: 0.0.0.0
Server IP: 0.0.0.0
Relay IP: 109.233.170.1
Client MAC: {00804840A46F}
  Host name{12}={support-desktop}
  Parameter request list{55}={1, 28, 2, 3, 15, 6, 119, 12, 44, 47, 26, 121, 42}
  Agent information{82}=
    sub{1}={000403420101}
    sub{2}={00060012CF539F5E}

В данном случае будет проигнорирован заголовок: sub{1}={03420101}, sub{2}={0012CF539F5E} и извлечены значения agentRemoteId=0012CF539F5E (MAC-адрес в виде набора байтов), VLAN=0x0342, interfaceId=0x01.

От некоторых коммутаторов значения могут приходить в строковом виде, например: sub{2}={3137322E31362E39392E33363A313031} (на самом деле, это обычная строка в шестнадцетиричном представлении), для обработки этой опции нужен такой конфиг:

# Удаление заголовка, при необходимости, 0 - не удалять, 2 - 2 удалить байта (тип+длина) из значения DHCP-опции.
# При удалении поля position для agentRemoteId, vlanId, interfaceId нужно уменьшить на тоже кол-во байт
dhcp.option82.removeHeader=0

# Параметры для извлечения из пакета agentRemoteId
# вид значения в опции agentRemoteId: 0 (по умолчанию) - байты, 1 - строка
#dhcp.option82.agentRemoteId.type=1
# код субопции 82, содержащей идентификатор коммутатора клиента, позиция и длина последовательности идентификатора
dhcp.option82.agentRemoteId.code=2
dhcp.option82.agentRemoteId.position=0
dhcp.option82.agentRemoteId.length=0

# Извлечение vlanId и interfaceId из строкового представления не поддерживается, данную процедуру нужно будет провести в 
# обработчике процессора протокола, как описано ниже.
# код субопции 82, содержащей VLAN, позиция и длина в субопции
#dhcp.option82.vlanId.code=1
#dhcp.option82.vlanId.position=0
#dhcp.option82.vlanId.length=2
# код субопции 82, содержащей интерфейс, позиция и длина в субопции
#dhcp.option82.interfaceId.code=1
#dhcp.option82.interfaceId.position=3
#dhcp.option82.interfaceId.length=1

При необходимости, данные параметры можно установить вручную в обработчике процессора протокола, в методе preprocessDhcpRequest (аналогично InetRadiusProcessor).

final DhcpOption agentRemoteId = request.getSubOption( option82RemoteIdCode );
if( agentRemoteId != null )
{
  byte[] value = new byte[option82RemoteIdLength];
  System.arraycopy( agentRemoteId.value, option82RemoteIdPosition, value, 0, option82RemoteIdLength );
  request.setOption( InetDhcpProcessor.AGENT_REMOTE_ID, value );
}

final DhcpOption vlanId = request.getSubOption( option82VlanIdCode );
if( vlanId != null )
{
  int vlan = InetUtils.parseInt( vlanId.value, option82VlanIdPosition, option82VlanIdLength );
  request.setOption( InetDhcpProcessor.VLAN_ID, vlan );
}

Пример обработки для строкового представления (извлечение agentRemoteId не обязательно, если указано dhcp.option82.agentRemoteId.type=1):

@Override
public void preprocessDhcpRequest( DhcpPacket request, DhcpPacket response )
     throws Exception
{
  DhcpOption circuitId = request.getSubOption( (byte)1 );
  DhcpOption remoteId = request.getSubOption( (byte)2 );

  request.setOption( InetDhcpProcessor.AGENT_REMOTE_ID, new String( remoteId.value, "UTF-8" ) );
  request.setOption( InetDhcpProcessor.INTERFACE_ID, new String( circuitId.value, "UTF-8" ) );
}

По описанным выше значениям AGENT_REMOTE_ID, INTERFACE_ID и VLAN, которые будут извлечены из пакета, происходит поиск устройства и сервиса. Конфигурация поиска устройства и сервиса на устройстве:

dhcp.deviceSearchMode=<deviceSearchMode>
dhcp.servSearchMode=<servSearchMode>
#dhcp.servSearchMode=<servSearchMode>-<subServSearchMode>

Идентификация коммутатора, расположенного под релеем и сервиса на коммутаторе, может производится в нескольких режимах. Режимы определяется переменными конфигурации устройства-релея.

<deviceSearchMode> может принимать значения:

0 (рекомендуется) - по giaddr или IP-адресу источника идет поиск устройства, далее у этого устройства вызывается предобработка preprocessDhcpRequest (где можно при необходимости извлечь и установить AGENT_REMOTE_ID, а также INTERFACE_ID или VLAN_ID), далее по установленному AGENT_REMOTE_ID или, если AGENT_REMOTE_ID не установлен - по конфигурации dhcp.option82.agentRemoteId.x agentRemoteId извлекается из пакета и идет поиск агентского устройства, далее у агентского устройства, если таковое найдено вызывается preprocessDhcpRequest (где можно при необходимости извлечь и установить INTERFACE_ID или VLAN_ID). Здесь запоминаются оба устройства, как deviceId и agentDeviceId;
1 - по giaddr или IP-адресу источника идет поиск устройства, по его конфигурации идет извлечение agentRemoteId, далее по agentRemoteId идет поиск агентского устройства. Здесь запоминается последнее найденное устройство как deviceId, agentDeviceId для биллинга будет 0;
2 - по giaddr или IP-адресу источника идет поиск устройства, найденное устройство будет запомнено как deviceId, agentDeviceId для биллинга будет 0.

Поиск сервиса происходит на агентском устройстве (agentDeviceId), если оно найдено, иначе на устройстве (deviceId).

<servSearchMode> может принимать значения:

1 - поиск по интерфейсу на (найденном) устройстве;
2 - поиск по VLAN'у на устройстве;
3 - поиск на устройстве по интерфейсу и MAC-адресу;
4 - поиск по VLAN'у на устройстве и его дочерних устройствах;
5 - поиск по MAC-адресу на устройстве;
6 - поиск по MAC-адресу на устройстве и дочерних устройствах.

После поиска сервиса можно дополнительно использовать поиск дочернего устройства (как элемент дополнительной авторизации).

<subServSearchMode> может принимать значения:

0 или отсутсвует - нет поиска дочернего сервиса
1 - поиск дочернего сервиса по MAC-адресу, если такого дочернего сервиса нет - ошибка авторизации;
2 - поиск дочернего сервиса по MAC-адресу, если такого дочернего сервиса нет - сессия будет привязана к родительскому сервису.

Процесс DHCP-авторизации состоит из двух запросов: DISCOVER и REQUEST. В первом запросе клиент запрашивает IP-адреса, какие ему могут предложить DHCP сервера. Во втором просит закрепить за ним конкретный IP-адрес. На DHCP-сервер биллинга попадают запросы с опцией 82, которая позволяет идентифицировать клиента. После идентификации клиента ему выдаётся IP-адрес. Идентификатором сессии при DHCP.82 авторизации выступает MAC-адрес клиента. Допускается одновременная инициализация нескольких сессий за одним портом коммутатора.

Адрес сессии выделяется либо из диапазона, указанного в самом сервисе, либо, если он исчерпан - из пула, определённого в конфигурации устройства. Пул адресов устройства определяется параметром конфигурации dhcp.ipCategories=<cat_codes>, где <cat_codes> - id коды категорий ресурсов IP адресов через запятую. Например:

dhcp.ipCategories=4

При превышении числа одновременных сессий сервиса над установленным в свойстве сервиса генерируется ошибка авторизации. В этом случае штатно DISCOVER-запросы будут игнорироваться, а на все REQUEST-запросы будет высылаться ответ DHCP_NAK. Для предотвращения нагрузки на DHCP-сервер постоянной обработкой запросов возможно определение пула фиктивных адресов, выдаваемых при ошибках авторизации. Пул определяется переменной конфигурации устройства dhcp.disable.ipCategories=<cat_codes>, где <cat_codes> - id коды категорий ресурсов IP адресов через запятую. Например:

dhcp.disable.ipCategories=3,4

При превышении количества сессий сервиса над ограничением в его свойствах при включенном pool.error выдаются несколько адресов из этого пула, после чего DHCP-запросы игнорируются. Это сделано для невозможности исчерпания пула фиктивных адресов отправкой большого количества DHCP-запросов с разными MAC-адресами. Количество сессий сверх ограничения, для которых могут быть выданы фиктивные адреса задаётся переменной конфигурации dhcp.additionalUnauthorizedSessionCount.

При смене абонентом устройства идет новый запрос DHCP-Discover, но может быть ситуация, когда старая сессия еще не закрыта по таймауту (пример - только что было продление адреса и абонент сменил устройство). В этом случае будет считаться что у абонента уже есть одна сессия и что IP-адрес этой сессии еще занят. Для того, чтобы на DHCP-Discover происходило закрытие активных сессий на сервисе, нужно указать dhcp.connection.closeOnNew=1.

Помимо IP-адреса в ответе DHCP-запроса могут передаваться различные опции. Они определяются из IP-ресурса, из которого выдан адрес, а также с помощью переменных конфигурации dhcp.option.<option_name>=<option_value> и dhcp.net.option.<net>.<mask>.<option_name>=<option_value>, где:

<net> - сеть, для которой выдаётся параметр;
<mask> - маска сети;
<option_name> - название опции;
<option_value> - значение опции.

Первый параметр устанавливает опции безусловно, второй - в зависимости от выданного IP-адреса. Возможные значения названий опций и их значений перечислены в таблице.

Таблица 17.1. Опции

Название опцииЗначение в видеВ DHCP пакете
leaseTimeЧисло в секундах.Опция 51, срок аренды IP-адреса
timeOffsetЧисло в секундах.Опция 2.
gateСтрока с IP-адресом в виде NNN.NNN.NNN.NNN.Опция 3, маршрутизатор
serverIdentifierСтрока с IP-адресом в виде NNN.NNN.NNN.NNN.Опция 54, идентификатор DHCP-сервера
dnsСтрока с одним или несколькими адресами вида NNN.NNN.NNN.NNN, разделённых запятой.Опция 6, DNS-сервера
domainNameСтрока.Опция 15, домен
subnetMaskСтрока с IP-адресом в виде NNN.NNN.NNN.NNN.Опция 1, маска подсети
renewalTimeЧисло в секундах.Опция 58, время, после которого DHCP-клиент должен перейти в RENEW
rebindingTimeЧисло в секундах.Опция 59, время, после которого DHCP-клиент должен перейти в REBIND

Для поддержки прямых RENEW запросов (т.е. когда RENEW запрос идет напрямую от абонента, не проходя через relay), в конфигурации нужно указать dhcp.renew=1. При этом для таких запросов можно указать специфичный набор опций, как dhcp.renew.option.<option_name>.

Пример конфигурации:

dhcp.option.serverIdentifier=0.0.0.0
dhcp.option.leaseTime=60
#
#dhcp.option.renewalTime=
#dhcp.option.rebindingTime=
#dhcp.inetOption.1.leaseTime=120
#
dhcp.net.option.193.106.88.0:255.255.255.0.gate=193.106.88.1
dhcp.net.option.193.106.88.0:255.255.255.0.dns=194.165.18.6
#
dhcp.net.option.172.16.24.0:255.255.255.0.gate=172.16.24.1
dhcp.net.option.172.16.24.0:255.255.255.0.dns=194.165.18.6

13.4.2. Процессор ru.bitel.bgbilling.modules.inet.dhcp.InetDhcpHelperProcessor

Предназначен для работы в связке с RADIUS-процессором. При успешной авторизиции или старте сессии InetDhcpHelperProcessor запоминает сессию по ключу, который создается из шаблона dhcp.key.pattern, указанного в конфиге. В шаблоне могут быть указаны следующие параметры:

deviceId - устройство, к которому привязана сессия, т.е. NAS, с которого идет RADIUS-аккаунтинг,
remoteId - агентское устройство, обычно коммутатор с которого пришел DHCP-relay-запрос на NAS,
circuitId - порт или VLAN, в зависимости от указанного типа поиска,
mac - MAC-адрес, для данной схемы он должен быть в RADIUS-атрибуте Calling-Station-Id.

При получении DHCP-запроса по указанному dhcp.key.pattern извлекаются данные из DHCP-пакета, т.е. по giaddr или IP-адресу, от которого запроса идет поиск устройства deviceId, аналогично InetDhcpProcessor из пакета извлекаются agentRemoteId и circuitId, по agentRemoteId идет поиск агентского устройства remoteId, и по circuitId - порта или VLAN, MAC-адрес извлекается из соответсвующего поля DHCP-пакета.

По этому ключу идет поиск среди запомненных RADIUS-сессий и выдача соответствующего ответа c IP-адресом из сессии.

Т.е. задача настроить так, чтобы из RADIUS-пакета и DHCP-пакета извлекались одни и те же данные (устройство, агентское устройство, порт/VLAN, MAC-адрес). Для этого в обработчике процессора протокола происходит извлечение из RADIUS-пакета DHCP-опций remoteId и circuitId.

Работа процессора зависит от параметра radius.servSearchMode :

- при поиске по логину (не рекомендуется, устарел, не удобен для связки с DHCP), в логине пользователя должны содержаться разделёнными двоеточием субопции DHCP.82 remoteId и circuitId, в номере звонящего - строка с HEX MAC-адреса. IP-адрес запоминается по ключу код устройства + опции + MAC-адрес;
- при остальных видах поиска из DHCP-запроса извлекаются идентификатор агентского устройства и номер порта или VLAN, аналогично InetDhcpProcessor. IP-адрес запоминается по ключу код устройства + код агентского устройства + номер интерфейса/VLAN + MAC.

Во всех случаях в RADIUS-атрибуте Calling-Station-Id должен быть проставлен MAC-адрес, чтобы при перезагрузке Access-сервера данные загрузились из сессий.

# Параметр привязки IP-адреса (сессии) к DHCP
dhcp.key.pattern=$deviceId:$remoteId:$circuitId:$mac
# Если по какой-то причине невозможно узнать из RADIUS-запроса агентское устройство или номер интерфейса/VLAN, то привязку можно сократить до кода устройства + MAC:
#dhcp.key.pattern=$deviceId:$mac

Процессор загружает список устройств-коммутаторов, начиная с корневого узла. Типы устройств-коммутаторов можно отфильтровать в переменной конфигурации корневого узла dhcp.relay.deviceTypeIds через запятую. Алгоритм поиска устройства при получении запроса идентичен ru.bitel.bgbilling.modules.inet.dhcp.InetDhcpProcessor.

Пример пакетов для обработчика ISGProtocolHandler:

RADIUS:
Packet type: Access-Request
Identifier: 140
Authenticator: {12 6B D7 9F 37 1E A1 39 BA 8C CD 13 0B CD 98 7B}
Attributes:
  User-Name=00060012cf539f5e:000403420101:0080.4840.a46f
  NAS-Identifier=7201-ipoe.nettrans.ru
  NAS-Port-Id=0/0/1/834
  User-Password=123
  Event-Timestamp=1314183142
  NAS-IP-Address=94.125.95.117
  NAS-Port=412
  Service-Type=5
  Acct-Session-Id=720000000000019C
  NAS-Port-Type=33
  cisco-avpair=circuit-id-tag=000403420101
  cisco-avpair=remote-id-tag=00060012cf539f5e
  cisco-NAS-Port=0/0/1/834


DHCP:
Message type: BOOT_REQUEST
Dhcp message type: DHCP Discover{1}
htype: 1, hlen: 6, hops: 1
xid: 1067065417, secs: 0, flags: 0
Client IP: 0.0.0.0
Your IP: 0.0.0.0
Server IP: 0.0.0.0
Relay IP: 109.233.170.1
Client MAC: {00804840A46F}
  Host name{12}={support-desktop}
  Parameter request list{55}={1, 28, 2, 3, 15, 6, 119, 12, 44, 47, 26, 121, 42}
  Agent information{82}=
    sub{1}={000403420101}
    sub{2}={00060012CF539F5E}

Пример конфигурации для таких пакетов:

# Параметры извлечения опций из RADIUS-пакета
# игнорирование заголовка опций (длина)
radius.agent.option.removeHeader=2
# RADIUS-атрибут cisco-avpair
radius.agent.option.remoteId.type=1
# префикс для cisco-avpair с опцией remoteId
radius.agent.option.remoteId.prefix=remote-id-tag=
# RADIUS-атрибут cisco-avpair
radius.agent.option.circuitId.type=1
# префикс для cisco-avpair с опцией circuitId
radius.agent.option.circuitId.prefix=circuit-id-tag=


# Параметры извлечения опций из DHCP-пакета
# игнорирование заголовка опций (длина)
dhcp.option82.removeHeader=2
# Параметры для извлечения из пакета agentRemoteId
# код субопции 82, содержащей идентификатор коммутатора клиента, позиция и длина последовательности идентификатора
dhcp.option82.agentRemoteId.code=2
dhcp.option82.agentRemoteId.position=0
dhcp.option82.agentRemoteId.length=6

# Параметры извлечения INTERFACE_ID и VLAN
# (position и length используются и для извлечения их из circuitId, найденном в RADIUS-пакете!)
# код субопции 82, содержащей VLAN, позиция и длина в субопции
dhcp.option82.vlanId.code=1
dhcp.option82.vlanId.position=0
dhcp.option82.vlanId.length=2
# код субопции 82, содержащей интерфейс, позиция и длина в субопции
dhcp.option82.interfaceId.code=1
dhcp.option82.interfaceId.position=3
dhcp.option82.interfaceId.length=1

# Шаблон, по которому создается ключ для привязки RADIUS-сессии и DHCP-пакетов.
# $deviceId - устройство (обычно NAS и relay-агент, с которого пришел DHCP-запрос на биллинг)
# $remoteId - агенское устройство (обычно коммутатор, к которому подключен абонент), определенное по agentRemoteId
# $circuitId - в зависимости от типа поиска сервиса либо interfaceId, либо VLAN
# $mac - MAC-адрес
radius.key.pattern=$deviceId:$remoteId:$circuitId:$mac

13.5. Слушатель InetFlowListener

Для того, чтобы принимать и обрабатывать flow-пакеты (netflow/netflow v9/sflow) в inet-accounting.xml должен быть прописан соответствующий слушатель. Если необходимо приходящие пакеты перед обработкой сохранять на диск, в слушатель нужно передать dataLogger. Объект dataLogger описывается один раз и передается всем flow-слушателям, с которых нужно сохранять данные.

У слушателя необходимо указать параметры:

type - его тип: netflow, netflow9, sflow;
host - хост (интерфейс), на котором будет открыт сокет, по умолчанию на всех интерфейсах;
port - порт, на котором будет открыт сокет;
recvBufferSize - размер буфера приема слушателя;
soRCVBUF - рекомендуемый размер буфера приема сокета (SO_RCVBUF);
threadCount - количество потоков-обработчиков;
agentDeviceIds - id устройств, источников flow-потоков, если на данном порту нужно обрабатывать данные только у определенных источников;
dataLogger - dataLogger, с помощью которого приходящие пакеты будут записываться в лог файлы.
		<!-- Служебный ScheduledExecutorService, необходимый для dataLogger -->
		<scheduledExecutorService name="hrlydtlggr" corePoolSize="1"/>

		<!-- Cоздание dataLogger, сохраняющего flow-пакеты на диск (только один экземпляр) -->
		<bean name="flowDataLogger" class="ru.bitel.bgbilling.modules.inet.collector.IPHourlyDataLogger">
			<param name="scheduledExecutor">hrlydtlggr</param>
		</bean>

		<!-- Cоздание слушателя flow-пакетов на порту с передачей ему dataLogger -->
		<bean name="flowListener" class="ru.bitel.bgbilling.modules.inet.collector.InetFlowListener">
			<constructor factoryMethod="newInstance">
				<!-- Тип слушателя, netflow, netflow9 или sflow -->
				<param name="type" value="netflow"/>
				<!-- Хост (интерфейс), на котором будет открыт сокет. Если пусто - на всех -->
				<param name="host" value=""/>
				<!-- Порт, на котором будет открыт сокет -->
				<param name="port" value="2001"/>
				<!-- Размер буфера приема слушателя -->
				<param name="recvBufferSize">4 * 1024 * 1024</param>
				<!-- Рекомендуемый SO_RCVBUF сокета -->
				<param name="soRCVBUF">512 * 1024</param>
				<!-- Количество потоков-обработчиков -->
				<param name="threadCount" value="10"/>
				<!-- id устройств-источников, если на данном порту нужно получать пакеты только c определенных источников -->
				<param name="agentDeviceIds" value=""/>
				<!-- id устройств-источников, если на данном порту нужно обрабатывать пакеты только c определенных источников -->
				<param name="processAgentDeviceIds" value=""/>
				<!-- 1 - если нужно запретить сохранять и обрабатывать пакеты, в которых нет записей с IP-адресами из IP-ресурсов,
				     2 - с учетом периодов IP-ресурсов -->
				<param name="ipResourceFilter" value=""/>
				<!-- Передача dataLogger -->
				<param name="dataLogger">flowDataLogger</param>
			</constructor>
		</bean>

Внимание

Каждый слушатель использует буферы памяти в direct memory, которая не находится в обычном heap java, общий размер которых можно расчитать как recvBufferSize (+ recvBufferSize) + threadCount * datalog.flow.chunk.size(datalog.chunk.size). Direct memory может использоваться также другими слушателями, а также при обработке логов. При превышении доступной памяти произойдет ошибка java.lang.OutOfMemoryError: Direct buffer memory. В старых билдах JRE MaxDirectMemorySize по умолчанию ограничен 64МБ, в новых - ограничен размером свободной оперативной памяти. Для того, чтобы указать конкретное значение, используется параметр в строке запуска -XX:MaxDirectMemorySize.

Обычно достаточно оставить параметр agentDeviceIds пустым, что будет означать, что поток будет приниматься со всех устройств-источников, начиная от корневого устройства Accounting-сервера. Однако в ситуации, когда с одного IP-адреса приходит два потока с разных источников, чтобы Accounting корректно разделял данные на два источника, необходимо создать два устройства-источника с одним и тем же IP-адресом и добавить два слушателя на двух разных портах и в agentDeviceIds одного прописать первый источник, во втором - второй. Таким образом трафик, идущий с одного и того же адреса на один порт будет считаться как трафик с одного источника, на другой порт - с другого источника.

В конфигурации типа устройства-источника (или в конфигурации устройства) необходимо указать какой поток идет с источника:

#Тип источника, netflow, netflow9 или sflow
#по умолчанию - netflow
flow.agent.type=netflow

Когда сессия стартует на каком-либо устройстве, по умолчанию считается, что это устройство и есть источник flow потока для данной сессии. Например, когда устройство одновременно является NAS'ом и источником netflow.

В схеме, когда flow-сенсор находится выше, необходимо указать для каждого устройства (например, NAS'а) привязку к источнику. Например, источник - это устройство с кодом 3. В конфигурации устройства-NAS'а прописываем, что трафик с любого интерфейса источника 3 может принадлежать сессии с данного NAS'а:

flow.agent.link=3:-1

Или, трафик с интерфейсов 1 или 2 может принадлежать сессии с данного NAS'а. Т.е. flow пакеты даже с таким же IP-адресом, как у сессии, но с другим интерфейсом, привязаны к ней не будут.

flow.agent.link=3:1,2

Для того, чтобы указать, что устройство является источником для всех своих дочерних устройств, достаточно в конфигурации типа устройства-источника прописать:

flow.agent.link={@deviceId}:-1

Внимание

При использовании InetFlowListener возможна схема, когда будет множество устройств-коммутаторов с интерфейсами, которые никак не связаны с Flow-агентом и поэтому у них не указан в конфигурации flow.agent.link. Исторически сложилось, что если параметр flow.agent.link не указан, то устройство само считается Flow-агентом с указанными интерфейсами. Для экономии памяти рекомендуется указать для таких устройств flow.agent.link={@deviceId}:-1.

Если необходимо исключить из сохранения и обработки пакеты, в которых отсутствуют записи с IP-адресами, принадлежащими одному из заведенных диапазонов IP-ресурсов, в inet-accounting.xml для слушателя нужно указать параметр <param name="ipResourceFilter" value="1"/>, или же глобально (т.е. для всех слушателей) - в конфигурации модуля:

# Фильтр flow пакетов:
# 0 (по умолчанию) - не фильтровать, 1 - не сохранять и не обрабатывать пакеты, в которых нет записей с IP-адресами из IP-ресурсов,
# 2 - то же самое, что 1, но с учетом периодов IP-ресурсов.
flow.ipResourceFilter=1

13.6. Настройка BGInetAccess сервера

В дополнение к стандартным параметрам в конфигурации у Access-сервера присутствует параметр accounting.deviceTypeIds, определяющий коды типов устройств, которые являются Accounting-серверами. Поиск устройств начинается с корневого устройства Access-сервера, включительно. Т.к. одно и то же устройство может быть и Access и Accounting сервером. Таким образом, "под" одним устройством Access-сервера может располагаться несколько устройств Accounting-серверов. Пример типовой настройки, которая идет в дистрибутиве:

<application context="access">
	<!-- Уникальное имя приложения -->
	<param name="app.name" value="BGInetAccess"/>
	<!-- Уникальный числовой id приложения -->
	<param name="app.id" value=""/>

	<!-- Параметры подключения к БД -->
	<param name="db.driver" value="com.mysql.jdbc.Driver"/>
	<param name="db.url" value="jdbc:mysql://127.0.0.1/bgbilling?useUnicode=true&amp;characterEncoding=UTF-8&amp;allowUrlInLocalInfile=true&amp;zeroDateTimeBehavior=convertToNull&amp;jdbcCompliantTruncation=false&amp;queryTimeoutKillsConnection=true&amp;connectTimeout=1000"/>
	<param name="db.user" value="bill"/>
	<param name="db.pswd" value="bgbilling"/>
	<param name="db.validationTimeout" value="10"/>
	
	<!-- Параметры подключения к MQ -->
	<param name="mq.url" value="failover:(tcp://localhost:61616)"/>
	<param name="mq.user" value="bill"/>
	<param name="mq.pswd" value="bgbilling"/>
	
	<!-- id модуля -->
	<param name="moduleId" value=""/>
	<!-- id корневого устройства -->
	<param name="rootDeviceId" value=""/>
	<!-- Типы фейковых устройств, являющихся аккаунтинг серверами -->
	<param name="accounting.deviceTypeIds" value=""/>

	<!-- Внутренняя переменная приложения, не изменять -->
	<param name="commonIdentifierName" value="rootDeviceId"/>

	<!-- Параметры сохранения логов данных -->
	<!-- Директория, в которую сохранять radius логи -->
	<param name="datalog.radius.dir" value="data/radius" />
	<!-- Размер блока данных в файле лога, также размер буфера на лог файл -->
	<param name="datalog.radius.chunk.size" value="262144" />
	<!-- Сжимать radius логи: 0 - не сжимать, 1 - zlib -->
	<param name="datalog.radius.compression.type" value="1" />
	<!-- Директория, в которую сохранять flow логи -->
	<param name="datalog.dhcp.dir" value="data/dhcp" />
	<!-- Размер блока данных в файле лога, также размер буфера на лог файл -->
	<param name="datalog.dhcp.chunk.size" value="131072" />
	<!-- Сжимать flow логи: 0 - не сжимать, 1 - zlib -->
	<param name="datalog.dhcp.compression.type" value="1" />
	
	
	<!-- Создание Access -->
	<bean name="access" class="ru.bitel.bgbilling.modules.inet.access.Access" />

	<context name="radius">
		<!-- Cоздание процессора RADIUS-пакетов -->
		<bean name="radiusProcessor" class="ru.bitel.bgbilling.modules.inet.radius.InetRadiusProcessor"/>
		
		<!-- Служебный ScheduledExecutorService, необходимый для dataLogger -->
		<scheduledExecutorService name="hrlydtlggr" corePoolSize="1" />

		<!-- Cоздание dataLogger, сохраняющего radius-пакеты на диск (только один экземпляр) -->
		<bean name="radiusDataLogger" class="ru.bitel.bgbilling.modules.inet.radius.RadiusHourlyDataLogger">
			<param name="scheduledExecutor">hrlydtlggr</param>
		</bean>

		<!-- Cоздание слушателя RADIUS-пакетов на порту с передачей ему процессора и dataLogger -->
		<bean name="radiusListener" class="ru.bitel.bgbilling.modules.inet.radius.InetRadiusListener">
			<constructor>
				<!-- Хост (интерфейс), на котором будет открыт сокет. Если пусто - на всех -->
				<param name="host" value=""/>
				<!-- Порт, на котором будет открыт сокет -->
				<param name="port" value="1812"/>
				<!-- Буфер приема на поток -->
				<param name="recvBufferSize">512 * 1024</param>
				<!-- Рекомендуемый SO_RCVBUF сокета -->
				<param name="soRCVBUF"></param>
				<!-- Количество потоков-обработчиков -->
				<param name="threadCount">10</param>
				<!-- Максимальное количество пакетов в очереди на обработку -->
				<param name="maxQueueSize">200</param>
				<!-- Передача процессора -->
				<param name="processor">radiusProcessor</param>
				<!-- Режим работы, RadiusListener.Mode.authentication -->
				<param name="mode">RadiusListener.Mode.authentication</param>
				<!-- Передача dataLogger -->
				<param name="dataLogger">radiusDataLogger</param>
			</constructor>
		</bean>
	</context>
	
	<context name="dhcp">
		<!-- Cоздание процессора dhcp-пакетов -->
		<bean name="dhcpProcessor" class="ru.bitel.bgbilling.modules.inet.dhcp.InetDhcpProcessor"/>
	
		<scheduledExecutorService name="hrlydtlggr" corePoolSize="1" />

		<!-- Cоздание dataLogger, сохраняющего DHCP-пакеты на диск  -->
		<bean name="dhcpDataLogger" class="ru.bitel.bgbilling.modules.inet.dhcp.DhcpHourlyDataLogger">
			<param name="scheduledExecutor">hrlydtlggr</param>
		</bean>
	
		<!-- Cоздание слушателя dhcp-пакетов на порту с передачей ему процессора и dataLogger -->
		<bean name="dhcpListener" class="ru.bitel.bgbilling.kernel.network.dhcp.DhcpListener">
			<constructor>
				<!-- Хост (интерфейс), на котором будет открыт сокет. Если пусто - на всех -->
				<param name="host" value=""/>
				<!-- Порт, на котором будет открыт сокет -->
				<param name="port" value="10067"/>
				<!-- Буфер приема на поток -->
				<param name="recvBufferSize">512 * 1024</param>
				<!-- Количество потоков-обработчиков -->
				<param name="threadCount">10</param>
				<!-- Максимальное количество пакетов в очереди на обработку -->
				<param name="maxQueueSize">200</param>
				<!-- Передача процессора -->
				<param name="processor">dhcpProcessor</param>
				<!-- Передача dataLogger -->
				<param name="dataLogger">dhcpDataLogger</param>
			</constructor>
		</bean>
	</context>

</application>

13.7. Настройка BGInetAccounting сервера

Кроме стандартных параметров в конфигурации у Access-сервера нет дополнительных параметров.Пример типовой настройки, которая идет в дистрибутиве:

<application context="accounting">
	<!-- Уникальное имя приложения -->
	<param name="app.name" value="BGInetAccounting"/>
	<!-- Уникальный числовой id приложения -->
	<param name="app.id" value=""/>

	<!-- Параметры подключения к БД -->
	<param name="db.driver" value="com.mysql.jdbc.Driver"/>
	<param name="db.url" value="jdbc:mysql://127.0.0.1/bgbilling?useUnicode=true&amp;characterEncoding=UTF-8&amp;allowUrlInLocalInfile=true&amp;zeroDateTimeBehavior=convertToNull&amp;jdbcCompliantTruncation=false&amp;queryTimeoutKillsConnection=true&amp;connectTimeout=1000"/>
	<param name="db.user" value="bill"/>
	<param name="db.pswd" value="bgbilling"/>
	<param name="db.validationTimeout" value="10"/>
	
	<!-- Параметры подключения к MQ -->
	<param name="mq.url" value="failover:(tcp://localhost:61616)"/>
	<param name="mq.user" value="bill"/>
	<param name="mq.pswd" value="bgbilling"/>

	<!-- id модуля -->
	<param name="moduleId" value=""/>
	<!-- id корневого устройства -->
	<param name="rootDeviceId" value=""/>

	<!-- Внутренняя переменная приложения, не изменять -->
	<param name="commonIdentifierName" value="rootDeviceId"/>
	
	<!-- Параметры сохранения radius-пакетов в файлы логов -->
	<!-- Директория, в которую сохранять radius логи -->
	<param name="datalog.radius.dir" value="data/radius" />
	<!-- Размер блока данных в файле лога, также размер буфера на лог файл -->
	<param name="datalog.radius.chunk.size" value="524288" />
	<!-- Сжимать radius логи: 0 - не сжимать, 1 - zlib -->
	<param name="datalog.radius.compression.type" value="1" />
	<!-- Параметры сохранения flow-пакетов в файлы логов -->
	<!-- Директория, в которую сохранять flow логи -->
	<param name="datalog.flow.dir" value="data/flow" />
	<!-- Размер блока данных в файле лога, также размер буфера на лог файл и поток слушателя -->
	<param name="datalog.flow.chunk.size" value="524288" />
	<!-- Сжимать flow логи: 0 - не сжимать, 1 - zlib -->
	<param name="datalog.flow.compression.type" value="1" />


	<!-- Создание Accounting -->
	<bean name="accounting" class="ru.bitel.bgbilling.modules.inet.accounting.Accounting"/>

	<context name="radius">
		<!-- Cоздание процессора RADIUS-пакетов -->
		<bean name="radiusProcessor" class="ru.bitel.bgbilling.modules.inet.radius.InetRadiusProcessor"/>

		<!-- Служебный ScheduledExecutorService, необходимый для dataLogger -->
		<scheduledExecutorService name="hrlydtlggr" corePoolSize="1"/>

		<!-- Cоздание dataLogger, сохраняющего RADIUS-пакеты на диск (только один экземпляр) -->
		<bean name="radiusDataLogger" class="ru.bitel.bgbilling.modules.inet.radius.RadiusHourlyDataLogger">
			<param name="scheduledExecutor">hrlydtlggr</param>
		</bean>

		<!-- Cоздание слушателя radius-пакетов на порту с передачей ему процессора и dataLogger -->
		<bean name="radiusListener" class="ru.bitel.bgbilling.modules.inet.radius.InetRadiusListener">
			<constructor>
				<!-- Хост (интерфейс), на котором будет открыт сокет. Если пусто - на всех -->
				<param name="host" value=""/>
				<!-- Порт, на котором будет открыт сокет -->
				<param name="port" value="1813"/>
				<!-- Размер буфера приема слушателя -->
				<param name="recvBufferSize">1 * 1024 * 1024</param>
				<!-- Рекомендуемый SO_RCVBUF сокета -->
				<param name="soRCVBUF"></param>
				<!-- Количество потоков-обработчиков -->
				<param name="threadCount">10</param>
				<!-- Максимальное количество пакетов в очереди на обработку -->
				<param name="maxQueueSize">200</param>
				<!-- Передача процессора -->
				<param name="processor">radiusProcessor</param>
				<!-- Режим работы, RadiusListener.Mode.accounting -->
				<param name="mode">RadiusListener.Mode.accounting</param>
				<!-- Передача setup -->
				<param name="setup">setup</param>
				<!-- Передача dataLogger -->
				<param name="dataLogger">radiusDataLogger</param>
			</constructor>
		</bean>
	</context>
	
	<!-- Cоздание процессора flow-пакетов -->
	<context name="collector">
		<!-- Служебный ScheduledExecutorService, необходимый для dataLogger -->
		<scheduledExecutorService name="hrlydtlggr" corePoolSize="1"/>

		<!-- Cоздание dataLogger, сохраняющего flow-пакеты на диск (только один экземпляр) -->
		<bean name="flowDataLogger" class="ru.bitel.bgbilling.modules.inet.collector.IPHourlyDataLogger">
			<param name="scheduledExecutor">hrlydtlggr</param>
		</bean>

		<!-- Cоздание слушателя flow-пакетов на порту с передачей ему dataLogger -->
		<bean name="flowListener" class="ru.bitel.bgbilling.modules.inet.collector.InetFlowListener">
			<constructor factoryMethod="newInstance">
				<!-- Тип слушателя, netflow, netflow9 или sflow -->
				<param name="type" value="netflow"/>
				<!-- Хост (интерфейс), на котором будет открыт сокет. Если пусто - на всех -->
				<param name="host" value=""/>
				<!-- Порт, на котором будет открыт сокет -->
				<param name="port" value="2001"/>
				<!-- Размер буфера приема слушателя -->
				<param name="recvBufferSize">4 * 1024 * 1024</param>
				<!-- Рекомендуемый SO_RCVBUF сокета -->
				<param name="soRCVBUF">512 * 1024</param>
				<!-- Количество потоков-обработчиков -->
				<param name="threadCount" value="10"/>
				<!-- id устройств-источников, если на данном порту нужно обрабатывать данные только у определенных источников -->
				<param name="agentDeviceIds" value=""/>
				<!-- Передача dataLogger -->
				<param name="dataLogger">flowDataLogger</param>
			</constructor>
		</bean>

		<!-- 
		<bean name="flowListener" class="ru.bitel.bgbilling.modules.inet.collector.InetFlowListener">
			<constructor factoryMethod="newInstance">
				<param name="type" value="netflow9"/>
				<param name="host" value=""/>
				<param name="port" value="9367"/>
				<param name="recvBufferSize">4 * 1024 * 1024</param>
				<param name="soRCVBUF">512 * 1024</param>
				<param name="threadCount" value="8"/>
				<param name="agentDeviceIds" value="4"/>
				<param name="dataLogger">flowDataLogger</param>
			</constructor>
		</bean>
		
		<bean name="flowListener" class="ru.bitel.bgbilling.modules.inet.collector.InetFlowListener">
			<constructor factoryMethod="newInstance">
				<param name="type" value="netflow"/>
				<param name="host" value=""/>
				<param name="port" value="9368"/>
				<param name="recvBufferSize">4 * 1024 * 1024</param>
				<param name="soRCVBUF">512 * 1024</param>
				<param name="threadCount" value="8"/>
				<param name="agentDeviceIds" value="20"/>
				<param name="dataLogger">flowDataLogger</param>
			</constructor>
		</bean>
		 -->
		 
		<context name="detail">
			<!-- Cоздание обработчика flow-детализации -->
			<bean name="detailWorker" class="ru.bitel.bgbilling.modules.inet.accounting.detail.InetDetailWorker"/>
		</context>
	</context>


13.8. Общий алгоритм настройки

Это общая обзорная статья описывающая общий алгоритм настройки модуля Inet. Рекомендуется к прочтению, потом можно перейти к примеру настроек VPN и IPoE. Там некоторая информация дублируется,а некоторая представлена в большем объёме. Примеры более сложных схем, таких как Cisco ISG, RedBack Clips и описаны в нашей wiki, но вначале рекомендуем изучить, понять и попробовать простые схемы, а потом уже приступать к более сложным.

Итак настройка начинается с того, что заводится головное устройство с отдельным типом ( обычно тип и устройство называют access+accounting). Это устройство является общим, с него не собирают трафик, не дают через него доступ и т.п. Это все лишь корень дерева, который может содержать некоторые общие настройки.

И это тот корень, который должен быть прописан в rootDeviceId настроек access+accounting серверов.

Внимание

Access и Accounting сервера должны быть обязательно и настроены (даже если в них ни одного слушателя, например вы не используете Radius/netflow/dhcp) .

Далее заводится дочернее устройство с отдельным типом. Тут в иерархии может быть сколько угодно устройств в общем случае . Но это минимальная конфигурация.

Далее заводится тип сервиса.

Внимание

Тут важно чтобы у сервиса был либо явно указано устройство к которому оно привязано(тогда каждый раз придётся указывать устройство при добавлении сервиса на договор), либо указана переменная const.device.id в типе сервиса. В случае VPN, например, часто договора привязаны к одному NAS-у, поэтому имеет смысл указывать const.device.id . Если несколько NAS-ов и сессия привязывается по факту к тому NAS-у с которого она вышла, то все NAS объединяются в устройствах в одну общую папку и в const.device.id прописывается эта папка.

Далее добавляем сервис на договор .

Внимание

Вид сервиса зависит от переменной title.pattern в типе сервиса(после исправления переменной нужно пересохранить сервис). В самом сервисе может быть в общем случае что угодно (логин, устройство и т.п ), зависит все это от настроек типа сервиса. Более сложные схемы позволяют заводить дочерние сервисы.

Если нужно указать статический ip адрес на сервисе, то не забываем про IP ресурсы и переменную ip.resource.categoryId.

Для выдачи динамических ip адресов не забываем про параметр radius.realm.<realm>.ipCategories в конфигурации устройства.

Тут мы должны создать (если нам это нужно) типы трафика. И привязку этих типов трафика. Привязка может быть либо по netflow или radius. Про настройку привязки читайте тут. Пример привязки для Radius есть тут, для netflow - тут. Новую привязку нужно указать в типе сервиса. Естественно до настройки привязки не забываем добавить сами типы трафиков.

Если вы не хотите учитывать трафик вообще(не по netflow не по radius), то можете этот момент пропустить, либо вернутся в нему позже.

Далее заводим простой тариф(пример минимального тарифа) . В тарифе должны быть цены и услуги для всех типов трафика(в том числе и для типа трафика Время). И добавляем тариф на договор .

Внимание

После изменения тарифа не забываем выбрать в контекстном меню "Оповещение об изменениях", чтобы Access и Accounting сервера об этом узнали.

В этом месте, если ещё не настроили, то можно настроить и запустить Access и Accounting сервера. Если они уже запущены, то стоит зайти в дерево устройств и нажать там кнопку "Перечитать конфигурацию на серверах" или перезапустить Acсess и Accounting чтобы они получили новые данные.

Внимание

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

При нормальной работе access сервера состояние сервиса на договоре (не путать со статусом) должно смениться с удален на подключен(если баланс больше лимита). В случае VPN можно проверить установку сессий.

В случае если нужно управлять доступом в зависимости от состояния баланса и статуса договором(что фактически отражено в состоянии сервиса), то нужно чтобы на типе сервиса стоял обработчик активации сервисов. Есть несколько стандартных обработчиков, которые есть сразу в выпадающем списке в типе сервиса, если они не подходят, то можно создать свой. Есть примеры на нашей wiki. Пример настройки подобной схеме есть в главе про IPoE.

Если нужно в нужно менять какие-то скорости или другие параметры, то это делается с помощью опции (не путать с тарифными опциями) в тарифе. Пример тарифа с опциями. Привязка опции к конкретным атрибутам радиуса указывается в конфигурации устройства(Параметр inet.option). Если опция меняет параметры доступа, то обработчик активации сервисов должен обрабатывать её смену в соответствующем методе.

В случае VPN если нужно менять опции на лету, на уже установленных соединениях с помощью Radius Coa запросов и сбрасывать сессий из биллинга с помощью Radius Pod запросов, то нужно использовать обработчик активации сервиса ru.bitel.bgbilling.modules.inet.dyn.device.radius.CoAServiceActivator(он есть среди доступных).

13.8.1. Пример настройка VPN доступа(PPPoE/PPPtp).

Заводится тип устройства VPN. И Устройство этого типа как дочернее к Access+Accounting.

Тут желательно ещё раз перечитать главу о InetRadiusProcessor. В самом устройстве настроить

Тут в качестве идентификатора нужно указать значение из атрибута NAS-Identifier radius-запросов, в качестве Хост/порт указать значение из атрибута NAS-IP-Address radius-запросов. Должно быть обязательно заполнено одно из этих полей (при наличии соответствующего атрибута), иначе система не сможет определить к какому устройству привязать radius-пакет.Подробнее об этом описано тут.

Далее заводится тип сервиса.

Тут тип инициации по сигналу, так как сессия стартует по radius access запросу. Тип адреса - динамический Адрес про статический описано ниже. Как настраивать привязки описано тут.

Привязку Radius нужно указывать если учёт трафика идёт по Radius протоколу. Как настроить конкретный пример для привязки Radius описано ниже. . В случае если подсчёт трафика идёт по Netflow указываете привязку Netflow и как её настроить описано тут. На первом этапе пока можете не указывать привязку и вернуться в ней позже.

Ставите галочку возле поле "Логин-Пароль". Если вы хотите при добавлении сервиса на договор каждый раз указывать устройство явно, к которому они привязано, то ставите галочку "устройство". Но в случае VPN обычно чаще бывают такие варианты

1) Есть всего один сервер NAS и к нему привязаны все сервисы . В этом случае проще указать const.device.id в типе сервиса и галочку устройство не указывать. Тогда все сервисы этого типа будут автоматом привязаны к этому устройству.

2) Если несколько NAS-ов и сессия привязывается по факту к тому NAS-у, с которого она вышла, то все NAS объединяются в устройствах в одну общую папку и в const.device.id прописывается эта папка. Вот так это выглядит в устройствах.

Так же указываем title.pattern в типе сервиса.

Далее добавляем сервис на договор .

Внимание

Отображение сервиса(в данном примере показывает логин) зависит от переменной title.pattern в типе сервиса(после исправления переменной нужно пересохранить сервис).

Если нужно указать статический ip адрес на сервисе, то не забываем про IP ресурсы и переменную ip.resource.categoryId.

Далее заводим простой тариф(пример минимального тарифа) . В тарифе должны быть цены и услуги для всех типов трафика. И добавляем тариф на договор .

Тут уже можно настроить RadiusListener-ы в Access и Accounting серверах(если еще не настроили). Перезапустить их, и попробовать авторизовать клиента.

Если нужно учитывать трафики по Radius, то вначале добавляем трафики

Потом добавляем привязку для Radius

Если нужно настроить сбор трафика по netflow, то читаем вот эту статью.

После настройки привязки, не забываем её указать в типе сервиса.

Если нужно в нужно менять какие-то скорости или другие параметры, то это делается с помощью опции (не путать с тарифными опциями) в тарифе. Пример тарифа с опциями. Привязка опции к конкретным атрибутам радиуса указывается в конфигурации устройства(Параметр inet.option). Для настройки корректного сброса VPN сессий (с помощью Radius Pod запросов) и для смены параметров(скорости) на лету, без установки новой сессии( Radius COA запрос) нужно в типе устройства поставить обработчик активации сервиса ru.bitel.bgbilling.modules.inet.dyn.device.radius.CoAServiceActivator(он есть среди доступных).

Пример настройки VPN соединения на основе MPD есть в нашей wiki.

13.8.2. Пример настройки IPoE, управление доступом.

Заводим новый тип устройства, назовём его Dlink.

Добавляем устройство этого типа как дочернее к устройству Access+Accounting.

В самом устройстве прописываем хост:порт(порт ставим 22 для ssh), и логин/пароль пользователя для управления.

Заводим тип сервиса:

Тут тип инициации сессий:

1) по трафику(это если вы собирайте трафик по netflow и хотите его учитывать).

2) По сигналу(Если вы хотите чтобы сессия стартовала по dhcp запросу ).

Так как режим какой-то должен быть выбран, то поставьте пока по трафику, даже если сессии вообще не будет(не будет не сигналов, ни трафика). Потом можно будет поменять по мере настройки.

Тип адреса - статический адрес(про динамический будет описано позже). Ставим галочку возле устройства. В title.pattern настроили так, чтобы отображался ip адрес.

Так как мы выбрали статический ip, то нам надо создать для него категорию в ресурсах ip-адресов.

И не забываем id этот категории прописать в переменную ip.resource.categoryId в конфигурации устройства:

Добавляем сервис на договор, выбираем устройство и ip.

Для управления доступом у нам используется обработчик активации сервисов, написанные на динамическом коде. Есть несколько стандартных обработчиков активации сервисов(доступные в стандартной поставке), такие как:

ru.bitel.bgbilling.modules.inet.dyn.device.terminal.SSHServiceActivator - Универсальный обработчик активации сервисов по ssh.

ru.bitel.bgbilling.modules.inet.dyn.device.terminal.TelnetServiceActivator - Универсальный обработчик активации сервисов по telnet.

ru.bitel.bgbilling.modules.inet.dyn.device.snmp.SnmpServiceActivator - Универсальный обработчик активации сервисов по snmp.

ru.bitel.bgbilling.modules.inet.dyn.device.mikrotik.MikrotikServiceActivator - Универсальный обработчик активации сервисов по для Mikrotik, работающий по протоколу Mikrotik Api.

Все они есть в стандартной поставке и описаны в wiki. Есть так же другие .

Пусть для примера мы решили использовать ssh. Тогда мы выбираем ru.bitel.bgbilling.modules.inet.dyn.device.terminal.SSHServiceActivator в типе устройства.

И конфигурации его указываем команды на подключение и отключение.

#Команды включения сервиса на устройстве
sa.command.serv.enable=permit ip host $ip any
#Команды выключения сервиса на устройстве
sa.command.serv.create=permit ip host $ip any
#Команды создания сервиса на устройстве.
sa.command.serv.disable=deny ip host $ip any
#Команды удаления сервиса с устройства.
sa.command.serv.cancel=deny ip host $ip any

Это команды указаны просто как пример. В данном случае при отправке команд переменная ip будет заменена на тот Ip адрес, который мы поставили в сервисе. Как задавать команды описано в описании ru.bitel.bgbilling.modules.inet.dyn.device.terminal.SSHServiceActivator.

С этого момента можно попробовать проверить открытие/закрытие доступа на устройстве. Если вы не хотите собирать netlow и обсчитывать трафик, а просто хотите открывать/закрывать доступ на устройстве по ip или интерфейсу, то этого будет достаточно . Можно проверять доступ, меняя баланс на договоре(например расходами и платежами) так чтобы состояние сервиса изменилось (когда баланс больше лимита, то подключено, когда меньше - отключено) и смотреть на устройстве правильно ли отработали команды. В этом режиме не создаются никакие сессии, а только управляется доступ в зависимости от баланса. Этот режим можно использовать, например, для безлимитчиков, для которых не нужно собирать трафик. Так же состояние сервиса можно менять вручную из меню вызываемого по правой кнопкой мыши, это бывает полезно для отладки обработчика активации сервиса.

В случае управления по интерфейсу(открывать/закрывать доступ на интерфейсе) нужно будет выбрать его в типе сервиса и поменять команды на типе устройства (макрос $iface). Все макросы ru.bitel.bgbilling.modules.inet.dyn.device.terminal.SSHServiceActivator активатора описаны в wiki. Если вы хотите использовать например не ssh, а telnet,то все настраивается аналогично, только указывает другой порт в устроите (23 вместо 22 ) и другой обработчик активации сервиса - ru.bitel.bgbilling.modules.inet.dyn.device.terminal.TelnetServiceActivator. Для mikrotik есть отдельный обработчик ru.bitel.bgbilling.modules.inet.dyn.device.mikrotik.MikrotikServiceActivator, работающий по mikrotik api(порт 8728). Для протокола snmp есть ru.bitel.bgbilling.modules.inet.dyn.device.snmp.SnmpServiceActivator.

Если кроме управления, вы хотите ещё собирать статистику по netflow, то нужно указать ip-адрес в типе сервиса, указать тип инициации по трафику (чтобы сессия создавались по трафику) и в типе сервиса. И настроить netflow согласно этой статье. Также в этом случае понадобится настроит тариф(пример минимального тарифа), в тарифе должны быть цены и услуги для всех типов трафика, и добавить тариф на договор . Если все будет нормально работать, то у вас должны появляться сессии с трафиком netflow.

Если вы хотите выдавать динамический ip с помощью dhcp option 82, то нужно настроить InetDhcpListener в Access-сервере. Настроить на устройстве переменные dhcp.deviceSearchMode и dhcp.servSearchMode. Тип инициации сессии тогда в типе сервиса нужно установить "по сигналу" (она будет создаваться по dhcp запросу).

13.8.. Сбор netlow.

Тут описана настройка сбора netflow для любой схемы. Вначале нужно завести типы трафика

и сделать привязку netflow

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

Тут перечитываем статью про InetFlowListener и исходя из этого строим иерархию устройств и прописываем flow.agent.link. Т.е если у вас само устройство, является источником, то это простая иерархия

В этом случае в самом устройстве flow.agent.link можно не прописывать вообще. Если нужно указать конкретный интерфейс(например 10), то нужно прописать на устройстве свой id и конкретный интерфейс:

flow.agent.link=2:10

Если netflow собирается с какого-то другого ip(агрегатор это другая машина), то нужно добавить и иерархию выше ещё одно устройство - источник. В данном случае для этого устройства лучше сделать отдельный тип Netflow source и добавить устройство этого типа в иерархию.

Или также возможен случай, когда netflow агрегатор один для нескольких устройств, тогда он является промежуточным предком для нескольких устройств:

В случае промежуточного агригатора нужно либо

1) указать

flow.agent.link={@deviceId}:-1

В устройстве netflow

2) Либо указывать в дочерних устройствах.

flow.agent.link=8:-1

Netflow описывается одинаково для PPPoe и IPoE схем.

Для сбора netflow на Accounting-сервера нужно не забыть прописать InetFlowListener.

14. Монитор соединений.

Для отслеживания сессий и ошибок авторизации можно использовать Монитор соединений.

Тут возможен просмотр текущих и завершённых сессий, ошибок авторизации с фильтрацией по времени, устройству. По нажатию правой кнопки мыши во всплывающем меню доступны следующие операции:

Открыть договор - открыть договор, к которому принадлежит выбранная сессия.

Закрыть - Физически закрывает выбранную сессию. Происходит попытка закрыть сессию на устройстве.

Завершить - Логически завершает выбранную сессию. Сессия закрывается только в биллинге.

Сервисные сессии - показывает список сервисных сессий для выбранной сессии.

По двойному нажатию мыши на сессию отображаются логи для выбранной сессии (возможно только для radius и dhcp).

15. Личный кабинет (web-статистика)

В личном кабинете клиент может просмотреть отчет по сессиям, отчет по трафикам или сменить пароль сервиса.

15.1. Доступ к личному кабинету по логину/паролю сервиса

Для того, чтобы клиент мог зайти в личный кабинет по логину и паролю сервиса, в конфигурации ядра необходимо изменить параметр web.auth.modes, добавив авторизацию модуля Inet. Например, если код модуля Inet 5:

# Авторизация клиента в личном кабинете по договору и по логину
web.auth.modes=0:1,5:1

Затем необходимо редактировать страницу авторизации webroot/xsl/login.xsl. Можно сделать так, чтобы в одной форме авторизация шла и по номеру договора и по логину Inet - для этого в hidden-поле midAuth после запятой код модуля Inet:

	<form method="post" action="{$WEBEXECUTER}">
		<input type="hidden" name="midAuth" value="0,5"/>
		<table class="filter" >
			<tr>
				<td align="left" nowrap="1">Номер договора<br/>или логин:</td>
				<td><input type="text" name="user" size="15" class="inputLogin" /></td>
			</tr>
			<tr>
				<td align="left" nowrap="1">Пароль:</td>
				<td><input type="password" name="pswd" size="15" class="inputPassword" /></td>
			</tr>
			<tr>
				<td></td>
				<td style="text-align: right"><xsl:call-template name="submit"><xsl:with-param name="title" select="'Вход'"/></xsl:call-template></td>
			</tr>
			<tr>
				<td colspan="2" align="right">
					<a href="{$PUBEXECUTER}?action=PasswordForgot&amp;module=admin" style="font-size: x-small">Забыли пароль?</a>
				</td>
			</tr>
		</table>
	</form>

Или же просто скопировать форму и вставить ниже, после формы авторизации по номеру договора, в поле midAuth оставив только код модуля Inet:

	<form method="post" action="{$WEBEXECUTER}">
		<input type="hidden" name="midAuth" value="5"/>
		<table class="filter" >
			<tr>
				<td align="left" nowrap="1">Логин:</td>
				<td><input type="text" name="user" size="15" class="inputLogin" /></td>
			</tr>
			<tr>
				<td align="left" nowrap="1">Пароль:</td>
				<td><input type="password" name="pswd" size="15" class="inputPassword" /></td>
			</tr>
			<tr>
				<td></td>
				<td style="text-align: right"><xsl:call-template name="submit"><xsl:with-param name="title" select="'Вход'"/></xsl:call-template></td>
			</tr>
			<tr>
				<td colspan="2" align="right">
					<a href="{$PUBEXECUTER}?action=PasswordForgot&amp;module=admin" style="font-size: x-small">Забыли пароль?</a>
				</td>
			</tr>
		</table>
	</form>

В последнем случае в окне авторизации будут две формы на выбор: в одной, как обычно, ввод номера договора и пароля к личному кабинету (статистике), в другой - ниже - ввод логина и пароля сервиса.

15.2. Отчет по сессиям

Клиент может просмотреть отчет по сессиям сервиса за месяц или определенный период месяца, выгрузить его в csv или html. Для каждой сессии можно просмотреть детализацию по наработке, если таковая в сессии есть.

15.3. Отчет по трафикам

В отчете по трафикам отображается наработка по трафикам по уже завершенным сессиям. По умолчанию он не отображается - чтобы его показывать, необходимо в конфигурации модуля установить параметр:

web.menuItem3=Отчет по трафикам Inet

Данные можно получить за месяц, количество в день:

Или же за день - количество в час:

15.4. Смена пароля сервиса

В личном кабинете клиент может сменить пароль для сервиса, если в типе сервиса используется логин:

15.5. Учетные периоды

В личном кабинете клиент может просмотреть список своих учетных периодов.

16. Интеграция с модулем Card

В модуле Inet возможна интеграция с модулем Card для автоматической активации карт при первой авторизации по протоколу RADIUS.

Каждая карточка имеет три параметра: серийный номер (уникальный, не должен повторятся ), логин и пароль. При первом подключении по логину и паролю карты после попытки стандартной аутентификации, InetRadiusProcessor запросит поиск карты с таким логином у модуля Card. Если карта будет найдена, ее статус и время действия будут активны, активация разрешена, а пароль совпадет, то модуль Card создаст договор, на основе шаблона договора, указанного в карте.

В шаблон договора нужно добавить модуль Inet с созданием сервиса и указать тип сервиса, с которым будет создан сервис, а также статус по умолчанию и максимальное кол-во активных сессий. Если в конфигурации выбранного типа сервиса присутствует параметр const.device.id, то созданный при активации карты сервис будет привязан к указанному устройству, иначе он будет привязан к устройству, с которого происходила активация карты (первое подключение).

В конфигурации модуля или же конфигурации устройства нужно указать параметры:

card.moduleId - код модуля Card
card.activate.serviceIds - id разрешенных услуг активации модуля Card. Услуга активации привязана к карте, и если услуга активации карты отсутствует в данном параметре, то карта активирована не будет. Если в параметре указано значение 0, то карты с любыми услугами активации могут быть активированы.
card.login.min - минимальное значение карточного логина, указывается для того, чтобы поиск карты не выполнялся для любого не найденного цифрового логина. Если указано 0 (по умолчанию), то ограничение не действует.
card.login.max - максимальное значение карточного логина, указывается для того, чтобы поиск карты не выполнялся для любого не найденного цифрового логина. Если указано 0 (по умолчанию), то ограничение не действует.

Пример конфигурации:

# Параметры активации карточек модуля card при использовании InetRadiusProcessor.
# Данные параметры можно указать как в конфиге модуля, так и в конфиге устройства.
# код модуля card
#card.moduleId=
# id услуг активации
#card.activate.serviceIds=
# минимальное значение карточного логина, используется чтобы указать, какие числовые логины нужно искать в карточках;
# если 0, то ограничение не действует.
#card.login.min=0
# максимальное значение карточного логина, используется чтобы указать, какие числовые логины нужно искать в карточках;
# если 0, то ограничение не действует.
#card.login.max=0

Так как при активации карты создаются сервисы с цифровым логином, то для того, чтобы обычные логины не пересекались и, при создании сервиса с автоматическим генерированием логина, сгенерированный логин не попал в диапазон логинов карточек, в конфигурации модуля необходимо правильно указать параметры:

# Параметры генерации логина
# минимальное значение логина при генерации логина
#serv.login.min=1
# максимальное значение логина при генерации логина (т.е. если в базе присутствуют логины 1,2,3 и 10000000,
# то при генерации создастся логин 4, а не 10000001)
#serv.login.max=9999999

17. Переобработка логов.

В модуле Inet возможно переобработать логи. В результате переобработки меняется количество трафика на сессиях. Эта необходимость может возникнуть в тех случаях, когда что-то было настроено неверно, например привязка трафиков и нужно это исправить задним числом. Обработать можно radius и netflow-логи. Сделать это можно на вкладке "Логи":

Тут с левой стороны находятся устройства, на которых собираются логи. А с правой - данные о логах для выбранного устройства. По оси абсцисс идут дни, по оси ординат идут часы. Каждый квадратик - это информация о логах за конкретный день и час для выбранного устройства, подкрашивается определенным цветом в зависимости от выбранных галочек. Значения галочек:

Есть данные - означает наличие логов за конкретный час;

В обработке - означает то, что данный час находиться в обработке.

Пересоздание сессий - означает то, что для данного часа добавлена задача на пересоздание сессий.

Правой кнопкой мыши можно вызвать всплывающее меню, в котором доступны следующие пункты:

Добавить в обработку (текущее устройство) - добавление в обработку выбранного дня;

Удалить из обработки (текущее устройство) - удаление из обработки выбранного дня.

Пересоздание сессий(текущее устройство) - Пересоздание сессий(текущее устройство) добавление задания на пересоздание сессий для выбранного дня.

Удалить задание на пересоздание сессий(текущее устройство) - удаление задания на пересоздание сессий для выбранного дня.

Оперировать (добавлять и удалять из обработки ) можно только дни. Это связанно с особенностью работы модуля inet. Следует учитывать, что обработка текущего дня приостанавливает процессы обсчета текущих сессий и, поэтому, стоит прибегать к этому только тогда, когда это действительно необходимо. При этом если произойдет split сессий во время переобработики (split сессий происходит на границе суток и например при активации тарифной опции на договоре ), то детализация сессии может потеряться и чтобы ее получить потребуется повторная переобработка. Поэтому лучше дождаться следующего дня и запустить сегодняшний день задним числом.

В текущий момент поддерживаются такие схемы.

1) Один собирающий логи accounting сервер. netflow и radius могут идти с разных устройств, могут с одного . Если netflow и radius идет с одного устройства, то типы трафика должны быть различными для netflow и radius(иначе они будут перетирать друг-друга). Для разных устройств можно заводить одинаковые типы трафика.

2) 2 accounting-сервера собирающих логи( например, один собирает netflow, другой radius) . netflow и Radius обязательно идут с разных устройств, причем коренные устройства этих accounting-серверов( rootDeviceId) должны указывать у каждого на разные объединяющиеся устройства, которые не являются предками друга друга. Типы трафика для устройств netflow и radius могут быть разными, могут одинаковыми, это значения не имеет так в случае разных устройств они не пересекаются. В этом случае каждый accouning сервер обрабатывает только те задачи, которые добавлены для устройств являющихся предками его корня( rootDeviceId ). Тут важно чтобы не было пересечений, иначе чужой accounting сервер может удалить всю детализацию по устройству, если логи этого устройства находятся на другом accounting- сервере.

В общем случае еще могут быть accounting сервера не собирающие логи. В этом случае у них в настройке должно стоять:

<param name="processLogs" value="false" /> 

По умолчанию там true. Аналогично так можно пометить сервера собирающие логи, но игнорирующие задания на их переобработку. Схема с общим устройством для netflow и radius и 2-ми accounting серверами собирающими логи(один собирает netflow, другой radius)- не поддерживается . В этом случае результаты переобработки логов не предсказуемы(возможно что один accountig-сервер будет перетирать работу другого). Такая схема запрещена к настройке.

Сессий пересоздаются по факту наличия трафика, старые сессии при этом этом будут потеряны. К пересозданию сессий нужно прибегать в крайнем случае, когда произошли какие-то сбои в работе системы и сессии не создавались. В остальных случаях вам скорее всего хватит обработки логов или переобсчета. После пересоздания сессий сессий нужно запустить обработку логов, чтобы на них появился трафик. При этом на новых сессиях не будет наработки по времени. Пересоздание сессий для текущего дня игнорируется.

18. Переобсчет.

В модуле Inet возможно переобсчитать наработку, стоимость сессий и баланс. Необходимость в этом может возникнуть, если, например, тариф был настроен неверно. Это можно сделать на вкладке "Переобсчет":

Тут выбирается месяц переобсчета (опционально можно выбрать день), договоры. Нужно учитывать, что при переобсчете текущего дня происходит остановка всех процессов тарификации на accounting-серверах и поэтому не следует этим злоупотреблять. Текущий час при этом игнорируется. При этом если произодет split сессий во время переобсчета такущего дня (split сессий происходит на границе суток и например при активации тарифной опции на договоре ), то наработка сессии может потеряться и чтобы ее получить потребуется повторный переобсчет.

Если accounting-серверов несколько, то нужно указать в конфигурации модуля inet переменную :

#id accounting-серверов через запятую
accounting.application.ids=

Переобсчет в этом случае распараллеливается по нескольким accounting-cерверам(на уровне договоров, она часть на одном, другая - на другом). Если переменная не указанна, то переобсчет происходит на первом попавшемся accounting-сервере. Еще следует избегать по возможности переобсчета текущего дня в текущем месяце( при переобсчете всего текущего месяца текущий день тоже переобсчитывается), так как при этом останавливаются все процессы тарификации на всех accounting серверах и запускаются после окончание переобсчета. При этом если какой-то accounting-сервер не перечислен в переменной accounting.application.ids, то он не будет остановлен и не получит данных об изменениях (например после переобсчета пользователь уже вышел за границу диапазона в тарифа, но accounting-сервер ничего про это не знает.

19. Отчеты модуля Inet.

В договоре для модуля Inet доступен один отчет по сессиям на вкладке Отчеты:

Тут возможно отображение текущих, завершенных сессий с возможностью фильтрации по месяцу/дням, сервисам, типам трафика. Во всплывающем меню по правому клику мышки доступны функции:

Закрыть - Физически закрывает выбранную сессию. Происходит попытка закрыть сессию на устройстве;

Завершить - Логически завершает выбранную сессию. Сессия закрывается только в биллинге;

Получить детализацию - выслать детализацию по сессии на e-mail;

Сервисные сессии - показывает список сервисных сессий для выбранной сессии;

Получить лог - отобразить логи для выбранной сессии (возможно только для radius и dhcp).

20. Коды ошибок авторизации

Таблица 17.2. Коды ошибок

Код ошибкиОписание
0Авторизация успешна.
1Логин не найден.
2Неверный пароль.
3Превышен лимит сессий.
4Учётный период не активирован.
10Сервис заблокирован.
11Договор заблокирован.
12Недостаточно средств.
30Карта просрочена.
31Карта заблокирована.
34Картой был пополнен баланс.
40Доступ к устройству (NAS'у) закрыт.
43Реалм запрещён.
44Доступ приостановлен.
46MAC-адрес запрещен.
62Не определён тарифный план.
63Не определёна цена в тарифном плане.

21. Настройка WiFi-агента для работы с модулем Inet

21.1. Описание WiFi-агента

WiFi-агент предназначен для манипулирования клиентами в WiFi-сетях. Он взаимодействует с сервером BGBilling и Access и Accouinting-серверами по RADIUS-протоколу для передачи информации о появлении клиента, его уходе и актуальном времени сессии. Также он управляет маршрутизатором. Общая схема взаимодействия может быть представлена на следующей диаграмме :

В данный момент WiFi-агент и WiFi-портал реализованы одним приложением и поднимаются на машине маршрутизатора. Это решение работает только для ОС семейства Linux (под FreeSBD и т.п. возможен запуск, если адаптировать скрипты). Пользователь выходит в WiFi-сеть, по DHCP получает IP-адрес с DHCP-сервера, установленного в этой сети, и через точку доступа попадает на маршрутизатор, на котором стоит ОС Linux со службой iptables. Iptables настраивается таким образом, что по умолчанию для клиента закрыты все порты кроме порта, на котором висит WiFi-портал. Все запросы на 80-ый порт перебрасываются на страницу портала, на которой пользователь вводит логин и пароль для доступа к WiFi-сетям. Страница авторизации имеет такой вид:

Пользователь водит логин/пароль.

Далее Портал обращается к Access-серверу и шлёт на него авторизационный RADIUS-пакет. Если авторизация проходит успешно (в ответ получен RADIUS-пакет подтверждения авторизации), то портал шлёт об этом запрос WiFi-агенту. WiFi-агент, в свою очередь, шлёт стартовый RADIUS-пакет на Access-сервер и меняет правила iptables, разрешая пользователю выйти в интернет. После успешной авторизации пользователя перекидывают на сервисную страницу :

На эту же страницу пользователь может попасть всегда (даже после авторизации), зайдя на http://192.168.184.39:9090 (путь зависит от настроек). Здесь он видит свой баланс, ссылку на первоначальный ресурс, который он набирал до того, как его перекинули на страницу авторизации. Также есть альтернативная ссылка на эту страницу через https.

Сессия клиента может быть завершена следующими способами :

1. Клиент зашёл на страницу портала и нажал кнопку "выйти";

2. Клиент исчерпал свой баланс и Access-сервер послал сообщение WiFi-агенту о завершении работы клиента с данным ip;

3. WiFi-агент, периодически проверяющий (в текущий момент через каждый 60 сек) состояние счётчиков iptables, определит, что клиент был неактивен в течении некоторого времени.

В случае завершения работы (не важно каким из выше перечисленных способов) WiFi-агент пошлёт Stop-пакет Accounting-серверу и удалит разрешающие правила iptables для нужного IP-адреса.

C точки зрения модуля Inet WiFi-агент выступает как NAS-устройстово в дереве устройств. В текущий момент он поддерживает следующие возможности :

1.Работа с Accounting-сервером по RADIUS-протоколу (Start, Stop, Update).

2. Тарификация с помощью любых тарифов (по времени, по трафику netflow, по RADIUS-пакетам), которые можно завести в системе BGBilling и которые поддерживаются модулем Inet. Для обсчёта трафика на маршрутизаторе нужно поднять NetFlow-агент . Также клиент имеет возможность выбора REALM-ов сразу на странице авторизации.

4. Доступ к статистике клиента и все возможности, которые предоставляет ядро BGBilling и модуль Inet для Web-интерфейса (просмотр баланса, мониторинг сессий и т.п).

4. Возможно ограничение скорости (Шейпинг) каналов в зависимости от RADIUS-атрибутов, переданных Access-сервером;

5. Вызов внешних скриптов при входе и выходе пользователя в сеть, что позволяет сжимать каналы в зависимости от тарифа или сбрасывать установленные соединения или выполнять любые другие действия;

6. Вызов внешних скриптов для получения исходящего/входящего трафика клиента (по умолчанию используются счетчики iptables);

7. Защита WiFi-сети от ARP-спуффинга;

8. Функция восстановления пароля через почтовый ящик клиента;

9. Возможность взаимодействия с модулем Карточки, т.е. возможность активации карты и последующей авторизацией по этой карточке в сети WiFi;

10. Возможность клиента работать с https-версией портала.

21.2. Установка, настройка и запуск

В текущий момент WiFi-агент и WiFi-портал реализованы одним приложением, которое и называется WiFi-агент. Для его установки его нужно скачать с сайта и распаковать в какую-нибудь папку .Например в папку /user/local. Далее для простоты будем считать, что мы установили в эту папку.

При установке рекомендуется идти от простого к сложному . Т.е. вначале заставить работать более простую конфигурацию, а потом уже пытаться добавлять дополнительные возможности.

Далее идут шаги, необходимые, для установки.

1) Для работы WiFi-агента нужна Java-машина;

2) Все настройки агента хранятся в файле inet_wifi_agent.properties. Вот пример этого файла :

#wifi agent class
wifi.agent.class=ru.bitel.bgbilling.modules.inet.wifi.InetWiFiAgent

#mq options
mq.url=failover:(nio://127.0.0.1:61616?socketBufferSize=1000000)
mq.user=bill
mq.pswd=bgbilling

#radius options
radius.auth.host=127.0.0.1
radius.auth.port=1812

radius.account.host=127.0.0.1
radius.account.port=1813

radius.nasId=den_nas
radius.secret=hello

#Слать Update-пакеты на Accounting-сервер (1  по умолчанию)
radius.update.send=1

#billing server options
billing.server.login=admin
billing.server.passwd=admin
billing.server.http.url=http://localhost:8080/bgbilling
#billing.server.https.url=https://localhost:8443/bgbilling
billing.server.moduleId=XXX

billing.server.show.statistics=0
billing.server.password.remind=0

#portal options
portal.http.port=9090
#portal.https.port=9091
#portal.https.keystore.password=bgbilling
#portal.card.link=http://127.0.0.1:8080/bgbilling/pubexecuter?action=CreateContract&module=card&mid=5&activateType=1

#tariff options
#portal.use.realm=1
#portal.tarif.1.realm=wifi_128_128
#portal.tarif.1.title=128 kb/s
#portal.tarif.2.realm=wifi_256_128
#portal.tarif.2.title=256 kb/s

portal.http.url=http://localhost:9090
#portal.https.url=https://localhost:9091

#wifi agent options
wifi.agent.port=5555
wifi.agent.port.admin=5556

wifi.agent.radius.live.time=60000
wifi.agent.client.live.time=24000000

wifi.agent.arp.command=/sbin/arp
#wifi.agent.server.https=1

#radius attributes
#wifi.agent.radius.atrubute.1.vendor.code=1111
#wifi.agent.radius.atrubute.1.attr.code=1
#wifi.agent.radius.atrubute.1.type=integer
#wifi.agent.radius.atrubute.2.vendor.code=1111
#wifi.agent.radius.atrubute.2.attr.code=2
#wifi.agent.radius.atrubute.2.type=integer

#dhcp options
#dhcp=1
#dhcp.server.host=192.168.184.254
#dhcp.server.port=67
#dhcp.agent.host=192.168.184.39
#dhcp.minThreadCount=10
#dhcp.maxThreadCount=10

#возможность использования символьных ссылок на файлы портала  
#portal.allow.linking=1
#обработка ssi (обрабатываются shtml файлы )
#portal.use.ssi=1

Установите переменную billing.server.moduleId=<числовой код экземпляра модуля Inet>. При необходимости скорректируйте параметры доступа к базе данных и к MQ-серверу.

А теперь остановимся более подробно на каждой настройке .

radius.auth.host, radius.auth.port - хост и порт, на котором поднят RADIUS-слушатель на Access-сервере;

radius.auth.port, radius.account.port - хост и порт, на котором поднят RADIUS-слушатель на Accounting-сервере;

radius.nasId - идентификатор NAS'а (устройства, которое предствляет WiFi-агент в модуле inet);

radius.secret - секретный ключ для NAS'а (как настроить NAS для WiFi-агента будет описано ниже);

radius.update.send - Слать Update-пакеты на Accounting-сервер. По умолчанию включено;

billing.server.login, billing.server.passwd - логин и пароль доступа к серверу (те же самые, что используются в клиенте биллинга). Нужны для получения баланса пользователя. Данный пользователь должен быть заведён в системе и обладать правами на действия : "Основной модуль->Договор->Просмотр договора" и "Основной модуль->Договор->Баланс-Просмотр Баланса". О том как администрировать пользователей читайте здесь;

billing.server.http.url, billing.server.https.url - URL сервера биллинга (тот же самый, по которому обращается клиент биллинга). Соответственно для http и https. Если https-соединение не нужно, то не указывайте billing.server.https.url.

billing.server.moduleId - код модуля Inet на BGBilling-сервере, c которым будет работать этот агент;

billing.server.show.statistics - показывать ли ссылку на статистику сервера (1- показывать; 0 - не показывать, стоит по умолчанию ). При этом если в текущий момент клиент работает c порталом по http, то для него это будет ссылка на http-версию статистики, а если он работает по https с порталом, то это будет ссылка на https-версию статистики;

portal.http.port, portal.https.port - порты портала для обычного и безопасного соединения. Если https-соединение не нужно, то не указывайте portal.https.port;

portal.https.keystore.password - пароль для https-соединения. Для работы https-соединения нужен файл .keystore (основанный на этом пароле), который необходимо положить в папку агента. Как получить этот файл описано здесь. Если https-соединение не нужно, то не указывайте этот параметр;

portal.http.url, portal.https.url - URL портала для http и https соединений. Это URL, по которому будут обращаться клиенты WiFi-сети, чтобы попасть на сервисную страницу. Если https-соединение не используется, то параметр portal.https.url не указывается;

wifi.agent.port - это порт, на котором будет подниматься WiFi-агент и Access-сервер будет обращаться к этому порту для сбрасывания клиента.

wifi.agent.port.admin - порт для управления WiFi-агентом;

wifi.agent.client.live.time - время жизни (в миллисекундах) клиента . Т.е. это время неактивности клиента, через которое WiFi-агент считает, что клиента больше нет, сбрасывает сессию клиента (отсылает Stop-пакет Accounting-серверу, очищает iptables, вызывает внешние скрипты). По умолчанию стоит 40 минут. Активность клиента проверяется по изменению счётчиков iptables в цепочке WIFI (о том как настроить iptables читайте ниже);

wifi.agent.arp.command - путь к команде arp в ОС Linux. Она нужна для получения mac-адреса клиента и манипулирования arp-таблицами (в случае настойки защиты от ARP-спуффинга). По умолчанию обычно /sbin/arp;

wifi.agent.server.https - использовать или нет при взаимодействии между WiFi-агентом и сервером протокол https (1 - https; 0-http, стоит по умолчанию).

3) Для работы внешних скриптов нужно настроить файл conf.sh (часть этих настоек дублируется в inet_wifi_agent.properties). Пусть у нас имеется Linux-маршрутизатор c двумя сетевыми интерфейсами: eth0 - локальный (сеть 172.16.1.0/24, через него выходя клиенты WiFi), eth1 - внешний интерфейс для выхода в интернет (имеет внешний ip - 81.30.199.220).

#путь к Java-машине, установленной в системе
JAVA_HOME=/opt/java/jre
#порты портала для обычного и безопасного соединения 
PORTAL_HTTP_PORT=9090
PORTAL_HTTPS_PORT=9091
#это порт на котором будет подниматься WiFi-агент и Access-сервер будет обращаться к этому порту.
WIFI_AGENT_PORT=5555
#имя цепочки iptables, в которой будут хранится разрешающие правила для клиентов.
WIFI_CHAIN_NAME=WIFI
#интерфейс, на котором происходит подсчёт клиентов WiFi-сети
WIFI_INTERFACE=eth0
#внешний интерфейс
EXTERNAL_INTERFACE=eth1
#внешний IP
EXTERNAL_IP=81.30.199.220
#сеть клиентов WIFI
WIFI_NET=172.16.1.0/24

4) Необходимо сделать запускаемыми все скрипты в папке агента . Для этого надо перейти в эту папку и выполнить команду :

chmod 755 *.sh *.pl

5) Настроить скрипты входа/выхода абонента.

login.sh - сюда добавляются команды открытия доступа для авторизовавшегося клиента . В это скрипт в качестве параметра передаётся ip пользователя и RADIUS-атрибуты, полученные в Accept-пакете (настройка атрибутов описана ниже).

Скрипт имеет такой вид в стандартной поставке

#!/bin/sh
cd ${0%${0##*/}}.
. ./conf.sh

IP=$1
DOWNSTREAM_SPEED=$2
UPSTREAM_SPEED=$3

date  >> ./log/manad.out
echo `/sbin/iptables -I $WIFI_CHAIN_NAME 1 -t nat -j ACCEPT -s $IP` >> ./log/manad.out 2>&1
echo `/sbin/iptables -I $WIFI_CHAIN_NAME 1 -t nat -j ACCEPT -d $IP` >> ./log/manad.out 2>&1

if [ $USE_MANAD -eq 1 ]; then
./tell_manad.pl "add $IP $DOWNSTREAM_SPEED $UPSTREAM_SPEED" $MANAD_PORT
fi

#use it for shaping
#./shape.sh $IP $PARAM1 $PARAM2

logout.sh - сюда добавляются команды закрытия доступа для клиента . В этот скрипт в качестве параметра передаётся ip пользователя. Скрипт имеет такой вид в стандартной поставке:

!/bin/sh
cd ${0%${0##*/}}.
. ./conf.sh

IP=$1

date  >> ./log/manad.out

echo `/sbin/iptables -D $WIFI_CHAIN_NAME -t nat -j ACCEPT -s $IP` >> ./log/manad.out 2>&1
echo `/sbin/iptables -D $WIFI_CHAIN_NAME -t nat -j ACCEPT -d $IP` >> ./log/manad.out 2>&1

if [ $USE_MANAD -eq 1 ]; then
./tell_manad.pl "remove $IP" $MANAD_PORT
fi

6) Настроить скрипт проверки активности клиента - ip_counts.pl. Скрипт поставялется в стандартной поставке и расчитан на парсинг цепочки с разрешающми правилами . На выходе скрипт выдает данные вот в таком формате

192.168.185.10 13423 6878 
192.168.185.20 133423 6878

Тут для каждого ip, найденного в цепочке, выводится информация о входящих (первый солбец) и исходящих байтах (второй столбец) на этот адрес . Столбцы разделены символом табуляции. Стандартный скрипт раcчитан на работу со стандартным файлом login.sh, считывает счетчики iptables из цепочки WIFI. Скрипт можно менять, главное, чтобы выходной формат оставался такой же, как описан выше.

7) Необходимо настроить iptables. По умолчанию WiFi-агент при старте системы инициализирует правила в системе с помощью скрипта iptables.sh. Рекомендуется все ваши настойки iptables тоже помещать в это скрипт. Этот скрипт также может использовать администратор для очистки правил и сбрасывания всех текущих клиентов. Вот пример этого скрипта:

#!/bin/sh  
cd ${0%${0##*/}}.
. ./conf.sh

/sbin/iptables -F -t nat
/sbin/iptables -F -t filter

/sbin/iptables -P PREROUTING DROP -t nat

#external interface ##################################################################################### 
#ssh 
/sbin/iptables -A PREROUTING -s ! $WIFI_NET -t nat -p tcp --dport 22 -d  $EXTERNAL_IP -j ACCEPT
#drop others from external interface
/sbin/iptables -A PREROUTING -s ! $WIFI_NET -t nat -j DROP
#end of external interface ################################################################# 

#internal interface ################################################################################################### 

#before wifi chain we must add redirects for authorized users  
/sbin/iptables -A PREROUTING  -t nat -p tcp --dport 80 -d $EXTERNAL_IP -j REDIRECT --to-ports $PORTAL_HTTP_PORT 
/sbin/iptables -A PREROUTING  -t nat -p tcp --dport 443 -d $EXTERNAL_IP -j REDIRECT --to-ports $PORTAL_HTTPS_PORT 

#chain for  WiFi  (accept rules for authorized users) 

/sbin/iptables --delete-chain $WIFI_CHAIN_NAME -t nat
/sbin/iptables -N $WIFI_CHAIN_NAME -t nat
/sbin/iptables -A PREROUTING  -j $WIFI_CHAIN_NAME -t nat

#below is rules for internal not authorized users : 

#dns   
/sbin/iptables -A PREROUTING  -t nat -p udp --dport 53 -j ACCEPT

#http  
/sbin/iptables -A PREROUTING  -t nat -p tcp --dport 80 -j REDIRECT --to-ports $PORTAL_HTTP_PORT 
/sbin/iptables -A PREROUTING  -t nat -p tcp --dport $PORTAL_HTTP_PORT -j ACCEPT

#https  
/sbin/iptables -A PREROUTING -t nat -p tcp --dport 443 -j REDIRECT --to-ports $PORTAL_HTTPS_PORT 
/sbin/iptables -A PREROUTING -t nat -p tcp --dport $PORTAL_HTTPS_PORT -j ACCEPT

#statistics 
/sbin/iptables -A PREROUTING  -t nat -p tcp --dport 8080 -d $EXTERNAL_IP -j ACCEPT

# NAT 
iptables -A POSTROUTING -o $EXTERNAL_INTERFACE  -s $WIFI_NET -j SNAT -t nat --to-source $EXTERNAL_IP

#RST packets for dropping estblished connections  
/sbin/iptables -A FORWARD -p tcp  -j REJECT --reject-with tcp-reset

Этот скрипт нужно поправить под ваш случай. В процессе работы правила будут иметь вид :

# iptables -L -t nat -n
Chain PREROUTING (policy DROP)
target     prot opt source               destination         
ACCEPT     tcp  -- !172.16.1.0/24        81.30.199.220       tcp dpt:22 
DROP       all  -- !172.16.1.0/24        0.0.0.0/0           
REDIRECT   tcp  --  0.0.0.0/0            81.30.199.220       tcp dpt:80 redir ports 9090 
REDIRECT   tcp  --  0.0.0.0/0            81.30.199.220       tcp dpt:443 redir ports 9091 
WIFI       all  --  0.0.0.0/0            0.0.0.0/0           
ACCEPT     udp  --  0.0.0.0/0            0.0.0.0/0           udp dpt:53 
ACCEPT     tcp  --  0.0.0.0/0            0.0.0.0/0           tcp dpt:9090 
ACCEPT     tcp  --  0.0.0.0/0            0.0.0.0/0           tcp dpt:9091 
ACCEPT     tcp  --  0.0.0.0/0            81.30.199.220       tcp dpt:8080 

Chain POSTROUTING (policy ACCEPT)
target     prot opt source               destination         
SNAT       all  --  172.16.1.0/24        0.0.0.0/0           to:81.30.199.220 

Chain OUTPUT (policy ACCEPT)
target     prot opt source               destination         

Chain WIFI (1 references)
target     prot opt source               destination         
ACCEPT     all  --  172.16.1.105         0.0.0.0/0      
ACCEPT     all  --  172.16.1.57          0.0.0.0/0      
ACCEPT     all  --  172.16.1.94          0.0.0.0/0

# iptables -L -t filter -n
Chain INPUT (policy ACCEPT)
target     prot opt source               destination         

Chain FORWARD (policy ACCEPT)
target     prot opt source               destination         
REJECT     tcp  --  0.0.0.0/0            0.0.0.0/0           reject-with tcp-reset 

Chain OUTPUT (policy ACCEPT)
target     prot opt source               destination         

Chain RH-Firewall-1-INPUT (0 references)
target     prot opt source               destination

Очень не рекомендуется заносить правила в цепочку WIFI, т.к. она редактируется автоматически и могут возникнуть проблемы. Свои дополнительные правила вы можете заносить в любые другие цепочки и таблицы (учитывая логику работы iptables и WiFi-агента).

Например, если Access-сервер нахаодится на другой машине, то ему надо разрешить 5555-ый (в данном случае) порт для обращения к WiFi-агенту. Аналогично можно разрешить порты для ssh и т. п., если это необходимо. На шлюзовой машине, где ставиться агент, скорое всего, будет, как минимум, один внешний интерфейс и один внутренний интерфейс, через который будут работать клиенты WiFi. В этом случае, например, если по ssh будут обращаться только через внешний интерфейс, то можно повесить разрешающие правила на внешний интерфейс. Вариантов много, но главное, чтобы выход во внешнюю сеть был закрыт для клиентов локальной сети по умолчанию. Одним из вариантов организации сети может быть набор виртуальных (vlan) интерфейсов, которые будут заведены на данной шлюзовой машине (на интерфейсе eth0) и агент будет добавлять правила для всех клиентов этих виртуальных сетей. В этом случае агент может управлять сразу многими локальными сетями, которые могут быть физически разнесены далеко друг от друга.

Замечание

Отметим, что для правильной работы сети кроме правила NAT, добавленного выше, в случае ОС Linux необходимо ещё включить ipforwarding. Для дистрибутива Fedora необходимо поставить net.ipv4.ip_forward = 1 в /etc/sysctl.conf и выполнить команду echo 1 >> /proc/sys/net/ipv4/ip_forward (чтобы изменения немедленно применились). Рекомендуется вначале проверить работу точки доступа и выход в интернет через неё, прежде чем применять запрещающие правила iptables, описанные выше.

8) Установить скрипт service/bgwifiagent_inet как службу. Для этого нужно скопировать файл bgwifiagent_inet в /etc/rc.d/init.d и потом вызвать следующие команды

chmod 755 /etc/rc.d/init.d/bgwifiagent_inet
chkconfig --add bgwifiagent_inet
chkconfig --level {lev} bgwifiagent_inet on

Где {lev}- это уровень запуска в вашей системе. Узнать его можно так:

[root@king ~]# runlevel
N 5

Т.к. агент изменяет правила iptables, то в системе он должен запускаться с правами root'а.

9) В файле setenv.sh нужно прописать JAVA_HOME.

10) Перед запуском агента нужно запустить скрипт

./update.sh

в папке агента. Это обновит все библиотеки на нем (скачает с сервера).

11) Для запуска агента можно выполнить команду:

service bgwifiagent_inet start

Агент не запуститься если не будет связи с сервером BGBilling, или там не будет установлены лицензии на модуль Inet или сам портал .

12)Подсоединиться клиентом к серверу биллинга, настроить устройство NAS для работы с нашим агентом. В конфигурацию NAS нужно добавить:

Идентификатор (такой какой мы указали в radius.nasId), секретное слово ( такое же как и в radius.secret), Хост/порт в формате (host:port). host - хост, на котором работает wifi-агент, port - то же самый что и в wifi.agent.port (5555 ). На этот хост и порт Access сервер будет и слать сигнал о завершении работы в случае ухода баланса клиента в минис, ручном сбросе сессии и т.п. В типе сервиса нужно установить обработчик активации сервисов ru.bitel.bgbilling.modules.inet.dyn.device.wifi.WiFiServiceActivator(входит в стандартную поставку).

13) Установить Access и Accounting сервера для модуля Inet. Настройки серверов должны совпадать с параметрами radius.auth.host, radius.auth.port, radius.account.host, radius.account.port в файле inet_wifi_agent.properties.

21.3. Связь WiFi-агента с модулем "Карточки".

Если у вас установлен модуль "Карточки", то портал может отображать ссылку на активацию карты. Для это в конфигурационном файле inet_wifi_agent.properties вы должны прописать строку

portal.card.link=http://127.0.0.1:8080/bgbilling/pubexecuter?action=CreateContract&module=card&mid=5

Формат этой ссылки описан в документации по модулю Карточки.

21.4. Защита WiFi-сети от ARP-спуффинга

ARP-spoofing (ARP-poisoning) — техника сетевой атаки, применяемая преимущественно в Ethernet, но возможная и в других, использующих протокол ARP-сетях, основанная на использовании недостатков протокола ARP и позволяющая перехватывать трафик между узлами, которые расположены в пределах одного широковещательного домена. Суть её состоит в том, что любой желающий может посылать ARP-запросы, подменять таким образом ARP-таблицы на других компьютерах и сопоставлять свой mac-адрес c чужим ip-адресом

Одним из методов защиты является использование статических ARP-таблиц, т.е. запрет на изменение ARP-таблицы. Именно это решение мы предлагаем для использования в нашем WiFi-агенте. Для этого внутри WiFi-агента реализуется ещё одно приложение: DHCP relay-агент. По описанию протокола DHCP (RFC 2131) сервер DHCP может отвечать не только на запросы клиентов на получение ip-адреса, но и на запрос relay-агентов, которые пробрасывают запросы клиентов на сервер (проставляя свой адрес, чтобы сервер мог им ответить), а ответ отправляют клиенту. Таким образом обычно реализуется возможность получения ip-адресов, если DHCP сервер находится в другой сети и часто роль relay -агентов выполняют аппаратные шлюзы. Мы используем программный Relay агент для того, чтобы при получении IP-адреса от DHCP-сервера редактировать arp-таблицу на шлюзе (где установлен WiFi-агент) и для удаления записи из arp-таблицы по истечению срока аренды IP-адреса (который задаётся DHCP-сервером и проставляется клиенту, а клиент, в свою очередь, обязан до истечения срока аренды послать запрос на продление IP-адреса). Динамическое обновление arp-таблицы отключается и никто другой не может править arp-таблицу кроме DHCP relay агента.

Для запуска DHCP-агента нужно в файл inet_wifi_agent.properties добавить следующие настройки:

#dhcp options
dhcp=1

dhcp.servers.1.host=192.168.184.254
dhcp.servers.1.port=67

dhcp.servers.2.host=192.168.184.253
dhcp.servers.2.port=67

dhcp.agent.host=192.168.154.39
dhcp.minThreadCount=10
dhcp.maxThreadCount=10

dhcp.servers.1.host=192.168.184.254
dhcp.servers.1.port=67

Здесь

dhcp=1 - это флаг, говорящий о том, что нужно запускать DHCP-агент.

Далее идут настройки DHCP-серверов. Поддерживается несколько серверов (<id> - 1,2,3 и т.п. ):

dhcp.server.<id>.host - IP-адрес сервера DHCP. Он нужен Relay-агенту;

dhcp.server.<id>.port - порт, на котором запускается сервер DHCP. Вообще, стандартным портом для сервера DHCP является 67-ой. Но в данном случае, возможно, вам понадобиться изменить этот порт. Например, если DHCP-агент и DHCP-сервер находится в одной локальной сети . В этом случае они оба будут получать широковещательные DNCP-запросы клиентов на получение IP-адреса и сервер будет отправлять ответы клиентам напрямую. Нам же нужно, чтобы запрос приходил только к DHCP-aгенту, а агент его уже пробрасывал на сервер. Этого можно добиться с помощью организации сети или ещё какими-либо другими способами, но один из вариантов - это поднять сервер на другом порту, чтобы он не получал запросы клиентов на 67-ом. Стандартный сервер DHCPd позволяет это сделать . В этом случае вам понадобиться изменить этот параметр.

hcp.agent.host - IP-адрес DHCP-агента, на который потом будет отвечать DHCP-сервер. Этот адрес проставляется в DHCP-запрос, который проходит через relay-агент;

dhcp.minThreadCount, dhcp.maxThreadCount - это минимальное и максимальное количество потоков в пуле при обработке запросов от клиентов и серверов DHCP. Эти параметры можно оставить по умолчанию;

dhcp.arp.command - путь к команде arp в ОС Linux. Она нужна для манипулирования arp-таблицами. По умолчанию обычно /sbin/arp.

Для отключения динамического обновления arp-таблицы нужно выполнить команду

ifconfig eth0 -arp 

При этом нужно посмотреть какие адреса уже попали в эту таблицу и, при необходимости, её отредактировать (например, добавить адреса каких-либо серверов в локальной сети, которые имеют статический ip).

21.5. Настройка ограничения скорости (шейпинг) для трафика WiFi-сети

Шейпинг осуществляется с помощью iproute2. Его реализация происходит через внешний скрипты и настраиваемые RADIUS-атрибуты, получаемые в Accept-пакете от Access-сервера. Вы можете реализовать свой вариант или изменить наш под ваши нужды. Общий принцип такой :

1. Скрипт init.sh ( вызывается при старте системы) - в нем можно проводить инициализацию правил шейпинга;

2. login.sh - сюда добавляются правила шейпинга для нового клиента, появившегося в сети. В это скрипт в качестве параметра передаётся ip пользователя и атрибуты радиуса, полученные в accept-пакете(настройка атрибутов описана ниже).

3.logout.sh - здесь удаляются правила шейпинга при выходе клиента из сети. В этот скрипт в качестве параметра передаётся ip пользователя.

Мы вам предлагаем свой вариант реализации этих скриптов. Для корректной работы этого варианта в системе должен быть установлен perl. Для его конфигурации надо добавить в файл conf.sh следующие строчки:

USE_MANAD=1
MANAD_INTERFACE=eth0
MANAD_PORT=4567

Здесь USE_MANAD=1 обозначает, что будет использоваться шейпинг, MANAD_INTERFACE - это интерфейс, на котором будет контролироваться трафик клиента и MANAD_PORT - порт, на котором будет слушать perl-скрипт wifi_manad.pl, управляющий шейпингом. Этот скрипт слушает на определённому порту команды на удаление и добавление нового клиента . При добавлении клиента например с ip 192.168.184.33, скоростью входящего трафика (downstream ) - 256 кбит/сек, скоростью исходящего трафика (upstream) - 128 кбит/сек, он добавляет для него следующие правила :

/sbin/tc class add dev eth0 parent 1:0 classid 1:3 htb rate 256kbit burst 4k prio 1 
/sbin/tc qdisc add dev eth0 parent 1:3 handle 3: sfq perturb 10 quantum 1500 
 
/sbin/tc class add dev eth0 parent 1:0 classid 1:4 htb rate 128kbit burst 4k prio 1 
/sbin/tc qdisc add dev eth0 parent 1:4 handle 4: sfq perturb 10 quantum 1500 
 
/sbin/tc filter add dev eth0 parent 1:0 protocol ip prio 3 u32 match ip dst 192.168.184.33  flowid 1:3 
 
/sbin/tc filter add dev eth0 parent 1:0 protocol ip prio 4 u32 match ip src 192.168.184.33 flowid 1:4

А при удалении клиента 192.168.184.33 скрипт выполняет следующие команды:

/sbin/tc filter del dev eth0 parent 1:0 protocol ip prio 3
/sbin/tc filter del dev eth0 parent 1:0 protocol ip prio 4

/sbin/tc class del dev eth0 parent 1:0 classid 1:3 htb rate 256kbit burst 4k prio 1
/sbin/tc class del dev eth0 parent 1:0 classid 1:4 htb rate 128kbit burst 4k prio 1

Для правильной работы данного скрипта нужно настроить RADIUS-атрибуты, которые мы хотим получить из Accept-пакета от Access-сервера . В данном случае нас интересует два атрибута: ограничение входящей скорости (downstream) и значение исходящей скорости (upstream). Для этих атрибутов в файл в inet_wifi_agent нужно добавить следующие настройки:

wifi.agent.radius.atrubute.1.vendor.code=1111
wifi.agent.radius.atrubute.1.attr.code=1
wifi.agent.radius.atrubute.1.type=integer
wifi.agent.radius.atrubute.2.vendor.code=1111
wifi.agent.radius.atrubute.2.attr.code=2
wifi.agent.radius.atrubute.2.type=integer

Формат добавления атрибутов следующий:

agent.radius.atrubute.X. - общий вид

X - это код атрибута. Нумерация должна идти по порядку - 1, 2 и т.д . vendor.code - код производителя, attr.code - код атрибута, type - тип атрибута. RADIUS-атрибуты настраиваются в файле dictionary.xml Access-сервера и WiFi-портала (там тоже есть такой файл), и для данного примера можно добавить, например, такие атрибуты:

<vendor code="1111" name="linuxWiFi">
  <attribute add="no" name="WiFi-Downstream-Speed-Limit" type="integer" code="1"/>
  <attribute add="no" name="WiFi-Upstream-Speed-Limit" type="integer" code="2"/>
</vendor>

Для задания атрибутов возможны 2 варианта

1)Привязка атрибутов к realm'у. Например для realm'а default в конфигурации устройства можно указать:

radius.realm.default.attributes=WiFi-Downstream-Speed-Limit=256;WiFi-Upstream-Speed-Limit=128

2) Привязка атрибутов к опциям модуля Inet в конфигурации устройства:

radius.inetOption.1.attributes=WiFi-Downstream-Speed-Limit=128;WiFi-Upstream-Speed-Limit=128
radius.inetOption.2.attributes=WiFi-Downstream-Speed-Limit=256;WiFi-Upstream-Speed-Limit=256

Сами опции можно задавать в тарифе и в сервисе.???

Значения атрибутов, описанных в файле inet_wifi_agent.properties, в точно в таком же порядке (после ip-адреса) подаются в качестве параметров в скрипт login.sh, вызываемый после установки пользователем соединения.

21.6. Настройка REALM'ов

Клиент при авторизации может использовать REALM'ы. Список доступных REALM'ов может отображаться клиенту в виде выпадающего списка :

Пусть мы хотим использовать 2 REALM'а: входящий трафик 128 кбит/с и 256 кбит/с. Исходящий же трафик в обоих случаях пусть будет 128 кбит/сек. Для добавления этой возможности нужно добавить следующие настройки в файл inet_wifi_agent.properties:

#tariff options
portal.use.realm=1
portal.tarif.1.realm=wifi_128_128
portal.tarif.1.title=128 kb/s
portal.tarif.2.realm=wifi_256_128
portal.tarif.2.title=256 kb/s

В конфигурацию устройства для этого случая нужно добавить :

radius.realm.wifi_128_128.attributes=WiFi-Downstream-Speed-Limit=128;WiFi-Upstream-Speed-Limit=128
radius.realm.wifi_256_128.attributes=WiFi-Downstream-Speed-Limit=256;WiFi-Upstream-Speed-Limit=128

realmgr.default=default;wifi_128_128;wifi_256_128
radius.realm=default,wifi_128_128,wifi_256_128

Для разных realm'ов можно настроить различную привязку трафика к услугам.

21.7. Web-интерфейс

Web-интерфейс WiFi-портала сделан с помощью jsp и располагается в каталоге portal. Также используются технологии jstl и struts.

Глава 18. Модуль IPN

1. Назначение модуля

Модуль IPN предназначен для обсчёта постоянных подключений по протоколу IP путём сбора и анализа первичных логов. Первичные логи собираются либо напрямую коллектором BGIPNNetFlowCollector, либо сторонней программой, которая "подсовывает" бинарные логи в коллектор, оставляя ему лишь функцию обработки.

Также модуль может осуществлять автоматическую блокировку пользователей, посылая управляющие команды на шлюз пользователя. В данный момент модуль поддерживает следующие типы шлюзов:

  • FreeBSD роутер с файрволом ipfw;

  • Linux-роутер с файрволом iptables и системой контроля трафика iproute2;

  • DLINK 35xx, 38xx с поддержкой DHCP Options 82;

  • любой управляемый коммутатор в режиме простой блокировки порта;

  • CISCO как VPN-шлюз с RADIUS-авторизацией (предоставление виртуальных сетей корпоративным клиентам);

  • Mikrotik RouterOS;

  • Любое ваше оборудование, которое можно поддержать с помощью реализации шлюза на встроенном языке BeanShell.

Идентификатором клиента в системе выступает IP-адрес, либо интерфейс подключения.

Замечание

В настоящее время для данного модуля разработана более современная замена - модуль Inet. Модуль IPN оставлен для совместимости и постепенно будет удалён.

2. Настройка модуля

После инсталляции модуля, создания его экземпляра в Редакторе модулей и услуг необходимо завести услуги, определяющие типы трафика в модуле. Например: IPN внешний входящий, IPN внешний исходящий, IPN локальный входящий, IPN локальный исходящий.

На вкладке Конфигурация модуля установите конфигурацию по умолчанию.

# Аактивные и приостановленные статусы договора
contract.status.active.codes=0
contract.status.suspend.codes=3,4

web.menuItem1=IP-статистика (IPN)
web.menuItem2=Управление шлюзом (IPN)
web.menu.gateRules=Управление правилами шлюзов(IPN)
# Статус шлюза клиента после оплаты и разблокирования 0 - открыт, 1 - закрыт
status.after.unlock=1
# Коды услуг, не затрагиваемых при перерасчёте, например, если услуга используется для занесения наработки скриптом
#service.recalc.ignore=
# Статус шлюза по умолчанию (0 - открыт, 1 - закрыт, 2 - заблокирован, 3 - удалён, 4 - жёсткая блокировка)
default.contract.status=0
# Вывод только разрешенных услуг в Web-статистике. 0 - все услуги, 1 - только разрешенные услуги. 
web.service.allow=1
# Количество выводимых ошибок в периодических процессах
max.periodic.errors=30
#----------------------------------------
# Выборочное отключение проверки закрытого периода
# Обсчет максимальных трафиков
#closed.date.disabled.ActionMaxRecalculate=1
# Обсчет логов
#closed.date.disabled.ActionRecalculate=1
# Изменение адресов
#closed.date.disabled.ActionUpdateContractAddress=1
#----------------------------------------
# Шаблон имени файла детализации за период
#{dd1}{MM1}{yyyy1} - день, месяц, год начала периода, {dd2}.{MM2}.{yyyy2}-день, месяц, год конца периода, {dd2}.{MM2}.{yyyy2} день, месяц, год даты заказа выписки.
#{ip} - диапазон сети или ip-адрес
#{contract_title} - номер договора
#{user} - имя оператора, заказавшего выписку
#file.detail.template={cid}_{dd1}.{MM1}.{yyyy1}_{dd2}.{MM2}.{yyyy2}_{dd_now}.{MM_now}.{yyyy_now}

3. Базовые понятия и алгоритм работы модуля

Все базовые компоненты модуля изображены на схеме.

Клиент получает доступ в сеть, проходя через машину - Шлюз, ограничивающую доступ и машину - Источник. В некоторых случаях они могут быть совмещены на одном устройстве.

Функция источника - предоставление информации о трафике абонента посредством передачи NetFlow-потока на коллектор модуля IPN (BGIPNNetFlowCollector). Функция шлюза - получение от сервера управляющих команд, закрывающих или открывающих доступ пользователя к сети и их выполнение.

Обработка входных данных разделена на несколько этапов (описание упрощено, более подробно каждый этап рассмотрен далее):

  1. Коллектор принимает поток логов и сохраняет их в бинарные файлы определённого формата с разбивкой по часам, в логах содержится сырая информация о том с какого IP-адреса на какой какое количество байт было передано;

  2. При переходе часа отдельный поток коллектора обрабатывает файлы, помещая в БД агрегированную наработку по часам, привязывая IP-адреса к договорам и разделяя их по видам услуг;

  3. По расписанию планировщик тарифицирует агрегированную наработку, используя тарифные планы абонентов и начисляя наработку на баланс договоров. Переобсчёт производится каждый раз за весь месяц.

Сервер биллинга, планировщик и коллектор - отдельные процессы. Связь между ними осуществляется исключительно через БД. Так, сервер может передать через БД задание на переобработку логов коллектору, задание на переобсчёт логов планировщику заданий. Коллектор передаёт через базу серверу информацию по статусу часовых логов (загружен/обработан/отсутсвует) для отображения в менеджере источников.

4. Привязки услуг (категории трафика)

При обработке сырых логов с трафиком из бинарных логов для каждой записи, содержащей информацию:

fromAddr - IP-адрес отправителя пакета;
toAddr - IP-адрес получателя пакета;
fromIface - интерфес роутера, на который вошёл пакет;
toIface - интерфейс роутера, через который пакет покинул роутер;
fromPort - UDP/TCP-порт, с которого пакет ушёл;
toPort - UDP/TCP порт, на который пакет пришёл;
amount - количество байт в пакете;
tos/diffServ - поле DiffServ.

Выполняются следующие шаги, изображённые на схеме:

Из схемы видно, что каждый пакет обрабатывается как бы в "две стороны" и может быть отнесён к двум абонентам провайдера: как исходящий для одного и входящий для другого. Использование TCP/UDP-портов в идентификации абонента позволяет получать выделенный трафик по серверам клиента. Использование портов в идентификации услуги позволяет разделять трафик по типам сервиса (Mail, HTTP, FTP).

Привязки услуг определяют принципы разделения сырого трафика из логов по услугам. Редактирование осуществляется во вкладке Привязки услуг модуля. Каждая привязка отнесена к своему Плану привязок. Использование планов привязок позволяет по-разному разделять трафик по услугам для разных категорий абонентов.

Редактирование планов осуществляется в верхней области редактора. С момента установки в системе присутствует План по умолчанию.

Для создания нового плана его название вводится в текстовую область и кнопкой Создать план создаётся, при этом он также становится активным в выпадающем списке. Соответственно, для переименования плана он выбирается в выпадающем списке, в текстовую область вводится новое название плана и выбирается кнопка Переименовать. Удаление плана осуществляется выбором его в выпадающем списке и кнопкой Удалить. Кнопка Клонировать создаёт новый план привязок, с аналогичным клонируемому содержимым.

План по умолчанию нельзя ни удалить, ни переименовать. В таблице ниже отображаются привязки услуг для текущего плана привязок, редактирование осуществляется общей панелью инструментов. Кнопка Новый элемент открывает редактор привязки.

Все правила (привязки) в плане привязок упорядочены по номерам, в порядке которых осуществляется просмотр при определении услуги. Правила с меньшими номерами просматриваются ранее и в них можно определить наиболее жёсткие правила. Например, удобен следующий порядок правил: трафик с выделенных серверов, локальная сеть, прочий интернет. При нумерации правил удобно оставлять интервалы (10, 20, 40..), что позволит в дальнейшем вставить в пробелы другие правила.

Для примера работы правил рассмотрим сеть с выделенным почтовым сервером 10.0.0.10, локальной сетью 10.x.x.x и внешним интернетом через, например, NAT. Трафик входящий из внешнего интернета и с почтового сервера следует отнести к внешнему, а трафик с локальной сети - к внутреннему. Последовательно отображены редакторы добавления правил.

Также возможно делить трафик на услуги используя DiffServ. Для этого в правиле необходимо прописать значение вида 000.000.00, т.е. 8 бит, для каждого бита 1, 0 или x - любой. Например, 000.100.xx или 000.1x0.xx. 000.1x0.xx преобразуется в 000.100.00 и маску 111.101.00б сначала наложится маска, результат проверится на соответствие с 000.100.00. Если использовать DiffServ не нужно, просто оставьте поле пустым.

В поле Примечание можно ввести краткое описание правила, если поле оставляется пустым система сама генерирует комментарий. Обратите также внимание, что нулевой адрес начала или конца диапазона адресов означает отсутствие ограничений в данном правиле на адрес сверху или снизу. Каждое правило характеризуется периодом действия. При обработке логов за даты, не попадающие в период правила, правило будет игнорироваться.

После добавления данных правил таблица примет следующий вид:

5. Создание источников и интерфейсов

В терминах модуля IPN Источник - это роутер, с которого приходит NetFlow-поток с информацией от трафике, прошедшем через него. К источнику привязываются адреса клиентов. Привязка абонентов к источнику позволяет избежать двойного учёта пакета клиента, прошедшего через несколько роутеров.

Источник характеризуется IP-адресом и названием. IP-адрес сравнивается коллектором с адресами приходящих пакетов с информацией о трафике. Название визуально идентифицирует источник в графическом интерфейсе. Доступны типы источников логов:

NetFlow - обработка NetFlow-потока, либо логов flow-tools коллектором, в свойствах указывается адрес хоста, с которого приходит поток;
sFlow - обработка sFlow-потока коллектором, в свойствах указывается адрес хоста, с которого приходит поток;
SNMP - опрос коллектором счетчиков интерфейсов по SNMP-протоколу, в свойствах указывается адрес для опроса и community.

В конфигурации источника типа NetFlow возможно указание опции:

ignore.by.zero.dst.iface=1 - пропускать пакеты с нулевым интерфейсом назначения, т.к. на аппаратуре CISCO это означает что пакет не получил клиент
use.load=1 - отображать ли пункт меню Добавить в загрузку в менеджере источников

В конфигурации источника типа SNMP возможно указание опций:

snmp.port=<port> - для источника с типом SNMP - порт опроса, отличный от стандартного 161;
snmp.version=<version> - версия протокола 1, либо , по умолчанию используется версия 1.

Замечание

Типы источников FTP и Локальная или сетевая папка использовались в устаревших версиях биллинга, при загрузке логов сначала в БД и дальнейшей обработки. Данная схема не рекомендуется более к использованию как ресурсоемкая и в данном руководстве более не описывается, при необходимости вы можете использовать инструкции к старым версиям биллинга.

После создания источника ему присваивается уникальный Код источника (отображается в первом столбце таблицы, см. ниже), который должен быть указан в конфигурации коллектора. Разные источники могут обслуживать разные коллекторы, это позволяет разнести обработку логов по разным машинам, повышая масштабируемость системы.

После создания источника определяются его интерфейсы. Интерфейс в терминах биллинга - это сетевые интерфейсы роутера, к которым могут быть привязаны клиенты. Если учёт интерфейсов не требуется, то достаточно создать на вкладке Интерфейсы и зоны интерфейс ANY с кодом -1 и привязывать клиентов на данном роутере к нему.

Зона - это область в которой не должны пересекаться адреса клиентов. Зоны сделаны для поддержки в сети провайдера нескольких фиктивных сетей с одинаковыми адресами но на разных интерфейсах.

Зоны нужны лишь для контроля непересечения адресов клиентов. Зона привязывается к интерфейсу. Биллинг предоставляет три предопределённые зоны: Глобальная зона - единая зона на всех клиентов, Своя зона - зона в пределах интерфейса, Нет зоны - нет проверки уникальности.

Если всем клиентам выдаются адреса из непересекающихся сетей, достаточно использовать глобальную зону.

Дополнительно возможно создание своих собственных зон. Например, одна фиктивная сеть может быть разделена на несколько интерфейсов разных роутеров. Для редактирования зон используется вкладка Зоны.

6. Управление ресурсами IP-адресов

Система управления ресурсами позволяет отслеживать состояние доступных IP-адресов, автоматизировать выделение их клиентам. Управление базой адресов производится на вкладке Ресурсы модуля.

На подвкладке Категории определяются категории ресурсов. В качестве категорий целесообразнее всего определять сети провайдера.

Для редактирования категорий используется общая панель инструментов. Непосредственно просмотр ресурсов осуществляется на вкладке Управление.

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

Для добавления/удаления и изменения периода действия ресурсов используется панель инструментов над таблицей. Для добавления ресурсов необходимо выбрать категорию в дереве и нажать кнопку Открыть ресурсы.

Ресурсы можно добавить сетью, либо диапазоном адресов.

Кнопками Изменить период ресурсов и Изменить категорию возможно изменение периода доступности ресурсов, либо их категории. Предварительно ресурсы нужно выбрать в таблице используя клавиши Shft, Ctrl, либо комбинацию Ctrl+A (предварительно отфильтровав только нужные ресурсы).

Кнопка Удалить удаляет выбранные ресурсы, при этом они не должны быть задействованы ни в одном договоре.

Ресурс помечается как занятый только для диапазонов, находящихся в Глобальной зоне.

С версии 4.5 ресурсы модуля IPN хранятся как диапазоны.

После добавления ресурсов их необходимо синхронизировать с уже назначенными диапазонами договоров. Для этого необходимо нажать кнопку Синхронизировать занятые.

7. Добавление адресов абонентам

Подключение модуля IPN к договору осуществляется путем выбора узла Модули дерева договора и нажатием кнопки Новый элемент стандартной панели иструментов.

Добавление разрешённых услуг в договор необходимо:

  • При использовании в тарифных планах договора узлов Диапазон в режиме пропорционально периоду разрешённой услуги (см. далее о тарификации). Объем наработки в этом случае определяется пропорционально доле присутствия разрешённой услуги в месяце. Отсутствие разрешённой услуги означает полный объем;

  • Для ограничения видимых клиентом в отчёте Web статистики услуг модуля при установленной опции конфигурации модуля web.service.allow=1;

  • При начислении максимальных трафиков, см. далее.

Управление адресами абонента производится на вкладке Адреса редактора свойств модуля IPN.

Здесь можно добавлять сети и диапазоны. Вкладка сети позволяет вводить сети вида xx.xx.xx.xx/xx. Сеть - это частный случай диапазона и работает аналогичным образом. Во многих редакторах вывод сетей и диапазонов происходит единым списком. Сети используются в командах некоторых шлюзов IPN. Добавление адреса (добавление сети имеет аналогичный вид, за исключением формы ввода xx.xx.xx.xx/xx) :

При добавлении адреса указывается договор, интерфейс, к которому привязан адрес на источнике. Опционально может быть указан объект, к которому относится диапазон адресов. Если не установлена галочка Показать все объекты, то в выпадающем списке будут только объекты, имеющие активный период, иначе будут выведены все имеющиеся объекты. Для раскрытия списка источников дважды нажмите по верхнему узлу дерева Все источники.

В случае, если абонент идентифицируется не по адресу, а по интерфейсу, необходимо выбрать интерфейс в дереве, а диапазон адресов установить в 0.0.0.0-255.255.255.255. Интерфейс с зоной Своя зона должен быть предварительно создан на вкладке Интерфейсы и зоны модуля.

Начиная с 4.4 версии рядом с диапазоном адресов добавлена кнопка Взять из пула ресурсов.

При её нажатии открывается окно выбора адресов из пула, где можно выделить диапазон адресов требуемой размерности, либо подсеть.

На вкладке Привязка услуг редактора адреса можно выбрать план привязок для данного диапазона адресов абонента. Также можно добавить персональные правила определения услуг. При обработке логов для данного диапазона адресов первыми будут просмотрены персональные привязки, далее, если услуга не определена - правила выбранного плана привязок. Редактор персональных привязок полностью идентичен редактору привязок, относящихся к какому-либо плану.

Метод добавления адресов из пула является рекомендуемым к использованию. Также есть возможность учёта нумерной ёмкости с помощью специального диапазона на одном из договоров. Это метод использовался в системе до появления ресурсов адресов и на текущий момент считается устаревшим и менее удобным, чем работа через ресурсы.

Метод непосредственного заведения адресов рекомендуется использовать только на момент запуска модуля в эксплуатацию. В дальнейшем для удобства учёта номерной ёмкости работа с адресами выполняется по следующему алгоритму.

Создаётся договор, содержащий все сети адресов, либо несколько сетей, как удобнее. При этом диапазон адресов привязывается ко всем интерфейсам, где возможно использование данных адресов.

Для переноса одного или нескольких адресов с договора-пула на договор абонента выбирается строка с диапазоном и производится двойной клик мышью при нажатой клавише Ctrl. Адрес может быть перенесён только на один из открытых договоров. При переносе указывается источник и интерфейс, к которому относится абонент, а также дата, с которой адрес переходит новому договору

После переноса система автоматически изменит диапазон адресов договора-пула, либо разорвёт его на два диапазона если перенос был выполнен из середины пула.

7.1. Настройка выделения адресов в шаблоне договора

Для того, чтобы настроить автоматическое выделение подсети нужного размера из числа свободных подсетей в глобальной зоне для всех создаваемых договоров, можно воспользоваться настройками модуля IPN при редактировании шаблонов договоров. Во вкладке Модули добавьте модуль IPN в качестве подключаемого для договоров данного шаблона.

Затем во вкладке IPN отметьте галочкой флаг Выделить диапазон с маской и укажите необходимую маску подсети. Укажите категорию ресурсов и интерфейс источника, на котором будет выделена подсеть. Сохраните шаблон.

Внимание

Данный функционал производит корректный поиск свободных адресов только в глобальной зоне! Попытка создания найденной подсети на интерфейсе в других зонах может привести к конфликтам адресов (договор не будет создан и подсеть не будет выделена).

8. Настройка сбора и обработки логов

Замечание

BGIPNNetFlowCollector обновляется как обычное серверное приложение биллинга. Необходимо обновить приложение перед первым запуском.

В данном руководстве пропущена настройка экспорта NetFlow-логов на вашем роутере, вы можете обратится к его документации для выяснения данного момента. Для PC-роутеров вы можете использовать NetFlow-агент ipcad.

Установите на вашей машине BGIPNNetFlowCollector, который можно загрузить с нашего сайта. Распакуйте архив например на диск C: (для MS), либо /usr/local для Linux.

Следующий абзац актуален только для MS-систем.

Далее установите переменную среды BGIPN_NETFLOW_HOME=C:\BGIPNNetflowCollector. Как устанавливать переменные среды вы можете посмотреть в документации по установке сервера. Также на машине с коллектором должна быть установлена переменная JAVA_HOME. Если на этой машине уже установлен сервер биллинга, либо радиус сервер, она уже указана. Вызовите скрипт netflow_install.bat для установки службы и можете запускать/останавливать коллектор через консоль управления службами MS. После установки системных переменных перезагрузите машину с коллектором.

Для UNIX-систем укажите в файле netflow.sh переменную JAVA_HOME - путь к установленной jre, либо jdk (например /opt/jdk). Создайте службу запуска коллектора через скрипт netflow_start.sh и стопа через netflow_stop.sh, либо просто сделайте его автоматически стартующим после mysql-демона. Скрипты для /etc/init.d можно сделать по аналогии со скриптами bgbilling, bgscheduler.

Коллектор хранит логи в бинарных файлах собственного формата. При этом записи хранятся в своем изначальном виде - т.е. пакеты netflow и sflow хранятся как есть. Часовой лог может хранится в нескольких файлах. Лог совместим с форматом XDR. Лог состоит из заголовка и данных. Данные могут быть разбиты на блоки одинаковой длины, при этом, если данных в блоке меньше, чем его длина, то оставшееся место заполнено нулевыми байтами. Данные могут быть сжаты zlib (блоки сжимаются в одном zlib потоке).

Формат файла лога:

header {
 int magic = "BGDL" = 0x4247;
 int version = 2;
 int type = 1 (IP);
 int header_params_length;
 param<> {
   int param_type;
   int param_value_length;
   opaque value;
 }
}

data {
 block<> {
  int block_length;
  long reserved;
  int reserved;
  opaque block_data;
 }
}

Коллектор может работать как в автономном режиме, принимая и обрабатывая логи, так и взаимодействуя с flow-tools коллектором. Обработка логов производится непосредственно самим коллектором, что позволяет хорошо разносить нагрузку по машинам.

Логи складываются в дерево каталогов в следующем формате:

source_<код источника>
+ yyyy/
   + yyyy-MM/
      + yyyy-MM-dd/
         + log_yyyy-MM-dd-HH.nnn.bgdl

например, лог за 3 час 25-го мая 2009 года:

source_1
+ 2009/
   + 2009-05/
      + 2009-05-25/
         + log_2009-05-25-03.000.bgdl
         + log_2009-05-25-03.001.bgdl
         + log_2009-05-25-03.002.bgdl

Для начала работы необходимо сконфигурировать файл netflow_ipn.properties в соответствии с необходимым функционалом.

# Порт управления коллектором
port.admin=2003

# Опции подключения к БД
db.driver=com.mysql.jdbc.Driver
db.url=jdbc:mysql://127.0.0.1/bgbilling?useUnicode=true&characterEncoding=UTF-8
db.user=bill
db.pswd=bgbilling
db.maxActive=300
db.maxIdle=100

# Код модуля IPN
collector.mid=XXX

# Где будут храниться логи (папка должна существовать и должны быть полные права на неё для процесса коллектора)
log.dir=/usr/bill/log
# Обрабатывать логи
process=1
# Источники, логи которых будут обрабатываться коллектором
# данное поле не влияет на прием данных, а только на обработку логов
process.sources=<числовые коды источников>

# Кколичество обработчиков часовых логов,
# т.е. если необходимо обработать несколько часов, то их будут обрабатывать указанное кол-во потоков,
# на каждый час - один поток
#process.thread.count=1
# Количество потоков-обработчиков часового лога
# Указанное количество потоков будет обрабатывать часовой лог
# (не действует для старого формата логов и для логов snmp)
#process.datalog.thread.count=1

# Частота генерации заданий на обработку логов в минутах
# Если опция не указана, генерация происходит только на границе часа
#generate.minutes=30

# Каталог, куда будет выкладываться детализация на сервере
#ipn.collector.detail.folder=tmp

В параметре collector.mid файла netflow_ipn.properties укажите числовой код вашего модуля IPN, вы можете его узнать в редакторе модулей и услуг. Если база расположена на отличной от коллектора машине или вы меняли логин/пароль, скорректируйте опции подключения к БД. В параметре process.sources укажите числовые коды источников, логи которых коллектор будет обрабатывать, через запятую. Параметр log.dir определяет директорию расположения бинарных логов.

Замечание

Код источника можно посмотреть на вкладке Источники экземпляра модуля IPN в первом столбце таблицы.

Возможно использование коллектора в автономном режиме, при этом он сам будет сохранять логи в файлы и производить их обработку ежечасно или чаще (опция generate.minutes). Также коллектор выполняет задания на переобработку логов добавленные пользователем в менеджере источников вручную.

Либо коллектор может работать в связке с flow-tools или иными сторонними коллекторами, при этом он При работе в связке с flow-tools коллектор перестаёт выполнять функции коллектора и остаётся лишь обработчиком.

Далее идёт описание запуска коллектора в автономном режиме и связке с flow-tools.

8.1. Настройка коллектора в автономном режиме

IPN collector поддерживает NetFlow версий 1, 5 и 7 (9-ая версия не поддерживается), sFlow версии 5, SNMP версий 1 и 2с.

Добавьте в netflow_ipn.properties:

# Загружать логи
load=1

Для приема NetFlow/sFlow-потока добавьте для каждого прослушиваемого порта. Коллектор может принимать данные на несколько портов, при этом на один порт может принимать данные только одного типа (NetFlow или sFlow).

#
collector.capture.flow.port.<listener_id>=<port>
collector.capture.flow.port.<listener_id>.type=<type>
collector.capture.flow.port.<listener_id>.sources=<codes>
collector.capture.flow.port.<listener_id>.thread.count=<count>
#

Где:

<listener_id> - уникальный числовой идентификатор слушателя в пределах properties-файла, начинать нумерацию следует с 1, далее последовательно;
<port> - прослушиваемый номер порта;
<type> - тип потока netflow, либо sflow;
<codes> - числовые коды источников через запятую, поток с которых приходит на этого слушателя;
<count> - количество потоков-обработчиков на данном порту.

Дополнительно могут быть указаны настройки:

# Размер блока файла/буфера приема для NetFlow/sFlow
datalog.flow.chunk.size=524288
# Сжатие для NetFlow/sFlow логов: 0 - отключено, 1 - zlib
datalog.flow.compression.type=0

Для каждого порта указывается количество потоков, работающих на порту (collector.capture.flow.port.x.thread.count). Эти потоки будут существовать все время работы коллектора, обрабатывая приходящие на порт потоки. Каждый поток хранит буферы приема для каждого источника, пакет которого хотя бы раз обрабатывался источником. Размер буфера равен или почти равен размеру блока буфера приема (datalog.flow.chunk.size).

Таким образом на порт необходимо памяти collector.capture.flow.port.x.thread.count * кол-во источников * datalog.flow.chunk.size. Здесь используется direct buffer memory, а не обычный java heap, по умолчанию максимум 64МБ. Чтобы при необходимости увеличить максимальный объем нужно указать в скрипте запуска -XX:MaxDirectMemorySize=256M. При настройках по умолчанию и 2-х источниках на порт необходимо 10 МБ памяти.

Возможно создать два и более источников с одинаковым IP-адресом и разнести их по разным портам, указав на каждом порту свой источник.

Ниже приведен пример настройки портов коллектора для получения логов источника с кодом 244, высылающим NetFlow-поток на порт 2001 коллектора и источника с кодом 255, высылающего sFlow-поток на порт 2002. Компрессия логов отключена.

# Порт для приема NetFlow-потока
#номер порта
collector.capture.flow.port.1=2001
# Тип потока - NetFlow/sFlow
collector.capture.flow.port.1.type=netflow
# Коды источников, данные с которых будут приниматься на этот порт
collector.capture.flow.port.1.sources=244
# Количество потоков-обработчиков
collector.capture.flow.port.1.thread.count=10
#
# Еще один порт
collector.capture.flow.port.2=2002
collector.capture.flow.port.2.type=sflow
collector.capture.flow.port.2.sources=255
collector.capture.flow.port.2.thread.count=10
#
# Размер блока файла/буфера приема для NetFlow/sFlow
datalog.flow.chunk.size=524288
# Сжатие для NetFlow/sFlow-логов: 0 - отключено, 1 - zlib
datalog.flow.compression.type=0

Коллектор также может опрашивать источник по SNMP на количество трафика на интерфейсах. Для этого необходимо установить опцию collector.capture.snmp=1 и указать обслуживаемые источники. Тип обслуживающих источников должен быть SNMP.

collector.capture.snmp.period=n - период опроса в секундах, т.е. каждые n секунд коллектор будет опрашивать источники. Пример настройки опроса SNMP источников, опрашивается источник с кодом 1:

# Опрашивать SNMP-источники
#collector.capture.snmp=1
# Источники, которые будут опрашиваться
#collector.capture.snmp.sources=1
# Период опроса в секундах
#collector.capture.snmp.period=60

При опросе через SNMP известны только сетевые интерфейсы, ip-адреса, породившие и принявшие трафик, неизвестны. Это необходимо учитывать при составлении привязок услуг. Т.е. все привязки услуг, используемые для классификации трафика, полученного путём съема SNMP-статистики, должны быть с пустым (0.0.0.0-255.255.255.255) фильтром по IP-адресу. Счетчики CNT_IN и CNT_OUT, полученные с интерфейса IF источника преобразуются в две записи о прошедшем трафике:

с интерфейса -1 адреса 0 на интерфейс IF адрес 0 прошло CNT_IN байт;
с интерфейса IF адреса 0 на интерфейс -1 адрес 0 прошло CNT_OUT байт.

Эти фиктивные записи о трафике далее обрабатываются по обычному алгоритму, они могут быть получены при выгрузке исходного лога в текстовой файл коллектором.

Сбор и сохранение логов происходит в блоки (chunk), которые при заполнении сбрасываются в файл. Размер блока datalog.chunk.size. При обсчете/переходе часа блоки также сбрасываются в файл, при этом пустое пространство заполнено нулями.

При частом обсчете и малом потоке может возникнуть много незаполненного пространства, например: 4 рабочих потока по 524288 собирали логи за 5 минут. Минимальный размер файла будет 2МБ, а нужных данных может быть гораздо меньше. Для оптимизации в таком случае необходимо уменьшить параметр datalog.chunk.size (по умолчанию 512 * 1024 для NetFlow/sFlow и 2 * 1024 для SNMP) или же просто использовать сжатие. Если необходимо указать размер отдельно для NetFlow/sFlow и для SNMP, то можно использовать параметры datalog.flow.chunk.size и datalog.snmp.buffer.size соответсвенно.

Сжатие логов используется для уменьшения потребления дискового пространства. По умолчанию сжатие выключено. Для включения необходимо указать параметр datalog.compression.type=1 (datalog.flow.compression.type отдельно для NetFlow/sFlow и datalog.snmp.compression.type для SNMP).

8.2. Настройка коллектора в связке с flow-tools

Построение связки возможно только на UNIX-системах.

В конфигурации необходимо установить опцию load в 0.

# Загружать логи
load=0

Теперь коллектор не будет слушать порты для приема NetFlow/sFlow-потоков и опрашивать SNMP-источники, а только обрабатывать логи источников.

Далее необходимо настроить связку с flow-tools. Коллектор поддерживает формат логов flow-tools, с логами NetFlow версий 5 и 7, поэтому будет достаточно настроить сбор логов flow-tools в директорию логов источника. nesting_level должен быть -3 для совместимости с системой хранения логов коллектора.

Пример: создаем perl файл rotate_1.pl, он будет обрабатывать появление нового лог-файла flow-tools c источника с кодом 1

#!/usr/bin/perl

my $name = $ARGV[0];
my $loader='/usr/local/BGIPNNetflowCollector/netflow.sh';

if ( $name =~ /.*\.(\d\d\d\d)-(\d\d)-(\d\d)\.(\d\d)/ )
{
    my $logYY = $1;
    my $logMM = $2;
    my $logDD = $3;
    my $logHH = $4;

    `$loader isload 1 $logYY-$logMM-$logDD-$logHH`;
} 
else
{
    die "unknown format $name";
}

Далее устанавливаем в автозапуск:

flow-capture -N -3 -w /usr/local/log/source_1 -n 95 -R rotate_1.pl 0/0/2003

8.3. Запуск коллектора

Для старта коллектора в UNIX-системах вызовите файл netflow_start.sh. Остановка - netflow_stop.sh. Для MS-систем запуск осуществляется через оснастку Службы.

После запуска проверьте файлы log/collector.out и log/collector.log на предмет ошибок.

Теперь коллектор подключится к БД, выберет из указанного модуля IPN список источников с кодами из параметра sources и будет собирать их логи, сохраняя в бинарные файлы, и обрабатывать их.

При запуске команды netflow.sh (.bat) отображается справка по командам коллектора:

[bill@flow BGIPNNetflowCollector]$ ./netflow.sh

Usage: [start|stop|status|save|help]
Parameters:
         help                                      - show this help
         start                                     - starting NetFlow collector
         stop                                      - stopping NetFlow collector
         status                                    - current status
         isload <source_id> <yyyy-MM-dd-HH>        - mark source is load
         save <source_id> <yyyy-MM-dd-HH> <path>   - save binary log to text on path
         sourcelist                                - get ip and source id list for external loader

Для вызова команды запустите: netflow.sh (.bat) <команда>

Команды start, stop вызываются скриптами netflow_start.sh netflow_stop.sh для запуска и остановки коллектора. Рассмотрим остальные команды коллектора:

status - отображение текущего статуса работающего коллектора.

[bill@flow BGIPNNetflowCollector]$ ./netflow.sh status
Traffic collector for IPN v 4.6 build 113 from 03.04.2009 14:47:16
Started: 03.04.2009 18:07:37 Uptime: 0 d 00:00:11
Memory total: 92 995 584; max: 1 379 467 264; free: 85 600 872
FlowListener: queue_size: 0; threads_active: 0; largest: 2; core: 4; pool_size: 2; recv_socket_buf_size: 131 071; recv_buf_size: 524 288; packets: 3
FlowListener: queue_size: 0; threads_active: 0; largest: 0; core: 4; pool_size: 0; recv_socket_buf_size: 131 071; recv_buf_size: 524 288; packets: 0
Flow loader: ru.bitel.bgbilling.server.util.ip.datalog.hourly.IPHourlyDataLogger@554d7745 [files: 1]

В первой строке отображается версия, номер и время билда коллектора. Во второй - время старта и прошедшее от старта время. На третьей - выделенная память Java-машине, максимально доступная для неё память и свободная в выделенном heap память.

save <source_id> <yyyy-MM-dd-HH> <path> - выгрузка часового лога по источнику с кодом <source_id> за час, определённый в формате <yyyy-MM-dd-HH> в текстовый файл, путь к которому указан в <path>, например:

./netflow.sh save 1 2008-01-01-00 /tmp/log

Сохранение лога по источнику с кодом 1 за 0 часов 1-го января 2008 года в файл /tmp/log

Команды isload и sourcelist используются для связки IPN коллектора с внешними коллекторами в режиме просто обработчика.

8.4. Наладка приёма данных коллектором в автономном режиме

Если коллектор запустился и поток приходит с одного из обслуживаемых источников в каталоге, указанным в переменной log.dir, должны появится подкаталоги source_<код источника>, а в них каталоги с годом, месяцем и бинарные файлы с трафиком.

В случае если этого не произошло:

1. Сделайте сброс кэша коллектора командой ./netflow.sh flush для UNIX, netflow.bat flush для MS;

2. Установите уровень логирования в файле log4j.xml из INFO в DEBUG (атрибут /log4j:configuration/root/priority/@value);

3. Проверьте файл collector.log на наличие строки: Starting FlowListener on port 2001. Если строки нет - значит опция load в netflow_ipn.properties не установлена в 1 или не указаны порты приема данных;

4. Посмотрите файл loader.log на наличие ошибок, проверьте опции экспорта NetFlow-потока на источнике, номер порта;

5. Посмотрите файл loader.log, если в нем присутствуют строки "Ignore packet from ...", это значит, что код источника с данным адресом не присутствует в переменной sources файла netflow_ipn.properties. Список обслуживаемых источников перечислен в логе collector.log в виде:

Reload source list
IP: X.X.X.X => Y

Добившись приёма файлов в лог следует перейти к следующей стадии - обработке первичных логов коллектором.

8.5. Настройка обработки данных

При установке опции process=1 в файле netflow_ipn.properties коллектор начинает принимать задания на обработку часовых логов для "своих" источников. Команды передаются в следующих случаях:

  1. При переходе часа генерируются задания на обработку логов прошедшего часа;

  2. Если количество минут текущего часа кратно параметру generate.minutes в файле netflow_ipn.properties генерируются задания на обработку логов текущего часа;

  3. При передаче сторонним ПО команды isload коллектор помечает логи загруженными и запускает их обработку;

  4. Обработка, либо переобработка логов может быть запущена администратором системы в Менеджере источников модуля.

При повторной переобработке логов за какой-либо час данные не суммируются, переобрабатывать логи можно неограниченное количество раз. Весь контроль за обработкой данных осуществляется через вкладку Менеджер источников.

Для просмотра состояния логов по источнику выберите месяц и источник в списке слева. Загруженные и обработанные логи выглядят как на приведённом выше снимке экрана.

Чтобы переобработать логи за какой-либо час - выберите мышью требуемые часы, затем вызовите меню нажатием правой кнопкой мыши. В появившемся меню добавьте в обработку логи, либо для выбранного источника, либо для всех источников модуля. Нажимая кнопку Обновить по изменению цвета можно отслеживать обработку логов коллектором.

Если по какой-либо причине необходимо полное перечитывание лог-файла с последующей переобработкой (например, произошла подмена ошибочных лог-файлов на исправленные), то можно добавить логи в загрузку. Аналогично, необходимо выбрать требуемые часы, вызвать контекстное меню нажатием правой кнопки мыши и далее Добавить в загрузку. Данная опция есть в наличии только в случае, если у источника установлен флаг use.load=1 в конфигурации.

Если логи для какого-либо источника за какой-либо час принимаются коллектором, либо переданы командой isload извне, а файл пуст, либо его объем минимален, то квадрат лога помечается красной точкой в центре, что означает Нулевой объем.

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

Отчет может быть просмотрен за день, месяц и год, в байтах, Мб и Гб. Если вопреки ожиданиям трафик договора не отобразился, выполните следующие шаги:

1. Проверьте наличие трафика по адресам абонента в бинарных логах за час. Для этого используйте команду ./netflow.sh save для UNIX-систем, netflow.bat save для MS-систем. В параметрах команды передаются код источника, час лога и файл, в который лог будет экспортирован в виде текста. Для уточнения синтаксиса запустите netflow.sh(.bat) без параметров;

2. Попробуйте для начала сделать правила в привязках, в которые попадёт весь трафик, любой входящий и любой исходящий. Если вам не получается отфильтровать требуемый вам вид трафика - также обратитесь к первичному логу.

Ошибки обработки трафика фиксируются в Сервис=>Журналы=>Журнал ошибок. Там отображаются пакеты, для которых не была определена услуга. Для просмотра журнала выберите модуль в выпадающем списке и дату.

9. Подсистема аудита

Модуль может осуществлять простейшую проверку на предмет нецелевого использования адресной ёмкости. Неучтённые адреса обнаруживаются по признаку отсутствия начисления по этому адресу какому-либо клиенту биллинга.

Пример 18.1. Пример настройки система аудита

Есть некий интернет провайдер, обладающий следующими диапазонами адресов: 8.8.8.1-8.8.8.241 и 9.9.9.4-.9.9.9.200. Большая часть этих адресов роздана клиентам. Для контроля за неиспользованием оставшимися в конфигурации модуля IPN указывается следующее:

# Включение системы аудита
audit=1
# Адрес, куда отправлять "сигналы" о нарушении режима
audit.email=admin@prov.com
audit.range.1=8.8.8.1-8.8.8.241
audit.range.2=9.9.9.4-.9.9.9.200

В результате обработки часового лога источника, если были нарушения аудита, будет сброшено письмо с темой: "Отчет аудита IPN". Содержимое письма будет примерно таким.

БЦ Космос@21.07.2006 14
Диапазон: 8.8.8.1-8.8.8.241 => 115740/634314674

В первой строке - название источника и время лога. Далее диапазоны, количество строк лога с нарушением и количество байт. Выборка записей лога с нарушениями - задача в данный момент в биллинге не реализованная.

10. Тарификация

В тарифном плане должна быть определена цена каждой услуги, потребляемой клиентом. Тарификация - отдельный процесс, использующий данные обработки логов и никак с ней не связан. О редактировании тарифных планов и их отнесении к договору вы можете почитать в документации к основной части программы. Там же описана логика работы тарифных деревьев и поведения стандартных узлов тарифных деревьев, общих для всех модулей.

Для тарификации на верхнем уровне в тарифе может находится либо услуга либо мультиуслуга и ничто другое. В тарифах так же кроме цены могут задаваться Типы правила для шлюза . Они описаны в следущей главе.

На один день в договоре может быть активно несколько тарифных планов с поддеревьями модуля, определяющих цены на разные услуги. Однако описание стоимости для каждой услуги должно быть только в одном из них. Не допускается описание цены одной услуги в нескольких тарифах, которые могут быть установлены в одном договоре параллельно. Логика поиска тарифа соответствует Алгоритму 2.

Если у вас не было тарифного плана, создайте его, создайте для него поддерево, либо расширьте от другого тарифа. После того, как вы откроете дерево, в нем должен отобразится узел со значком графика и названием экземпляра модуля IPN.

10.1. Создание тарифных планов

В тарифном запросе модуля IPN передаются следующие параметры:

код потребляемой услуги;
время момента потребления.

В ответе возвращаются:

стоимость услуги (обязательно);
параметры доступа (опционально);
категория трафика (опционально).

Дополнительные примеры тарифных планов модуля IPN доступны на нашем WiKi.

10.1.1. Простейший тариф

Следующий пример тарифа устанавливает фиксированные платы 1 и 2 рубля за МБ за входящий и исходящий трафики.

10.1.2. Тариф с зависимостью стоимости от объема

100 МБ бесплатного Внешнего входящего трафика, следующие 50 МБ по цене 1 руб. за МБ, а далее тарификация производится по 2 рубля за МБ. Квота не зависит от того, сколько проработал клиент в данном месяце.

Предположим, что до 31 марта цена мегабайта превышения была 1.0 рубля, а с 1 апреля стала 1.5 рубля. Возможно заранее скорректировать тариф подобным образом:

В случае, если наработка по Внешнему входящему трафику до 100 МБ, он тарифицируется по 1.5 руб/МБ, от 100 до 200 - по 1.2 руб/МБ, свыше 200 - по 1 руб/МБ. Т.е. в зависимости от объёма меняется цена мегабайта на весь объем.

Как можно понять из примеров 0 означает бесконечность в узлах типа Ограничение по объёму и Диапазон. Узлы Диапазон и Ограничение по объёму могут работать в режимах: безусловно, пропорционально периоду разрешённой услуги, пропорционально периоду действия тарифа. При этом количество постоянно, вычисляется пропорционально периоду действия разрешённой услуги в договоре, либо периоду действия тарифного плана соответственно.

Например, если при режиме пропорционально периоду разрешённой услуги месяц содержит 30 дней, а услуга добавлена в разрешенные с 15 го числа, то все объемы автоматически поделятся пополам. Если разрешенная услуга не добавлена, узел отработает в безусловном режиме.

10.1.3. Использование узла "Мультиуслуга"

Вместо нескольких узлов Услуга возможно создание узлов типа Мультиуслуга. Данный узел аналогичен по функциям узлу Услуга, но пропускает в себя запросы цены для нескольких указанных в нем услуг. Использование данного узла целесообразно для:

  • указания в одном узле цен для нескольких услуг с одинаковой стоимостью;

  • создания тарифов с квотами трафика, в которых начальная квота общая для нескольких услуг.

Рассмотрим оба этих случая в едином примере:

В данном примере стоимость услуг исходящих трафиков равна 0. На услуги входящего локального и внешнего трафиков выделена общая бесплатная квота 1000МБ, при превышении которой входящий внешний трафик тарифицируется по 1 руб/МБ, а локальный по 0.05 руб/МБ.

10.1.4. Детализация по тарифу

Детализация по тарифу позволяет в счетах модуля бухгалтерии разделить наработку по какой-либо из услуг, посчитанных по различным ценам или условиям. Например, можно вынести в отдельные строки счета бесплатный входящий трафик и платный трафик. Суть метода состоит в определении категорий услуги в конфигурации модуля и указании их в выпадающем списке узла Стоимость услуги. В результате каждая протарифицированная единица услуги относится к той или иной категории.

О детализации по тарифу написано подробно в документации по настройки позиций модуля бухгалтерии.

10.1.5. Комбинированный тариф

Для того, чтобы показать всю возможную сложность создаваемых тарифных планов, создадим следующий тариф.

Таблица 18.1. Описание тарифа

УслугаПравила
внешний исходящийдо 100 МБ в месяц бесплатно, далее - по 0.5 руб за 1 МБ
внешний входящийтрафик делится на ночной с 0 до 8 часов, дневной с 9 до 23 часов. ночной трафик - если до 10 МБ в месяц, то бесплатно, иначе все по (в т.ч. первые 10 МБ ) по 1 руб за 1 МБ, дневной трафик - по 0.8 руб за 1 МБ
локальный входящийс 8 утра до 8 вечера по 1.3 руб за 1 МБ, с 9 вечера до 23 часов по 1.1 руб за 1 МБ, с 0 часов до 7 утра - бесплатно
локальный исходящийбесплатно

Тарифный план настраивается следующим образом.

В реальности тарифы могут быть и сложнее. С помощью элемента Набор ограничений вы можете добавлять тарифы выходного дня, тарифы праздничных дней.

Следующий пример тарифа: клиент получает предоплаченные 500 000 000 байт бесплатно, стоимость остального трафика различается в зависимости от суммарной наработки:

до 1 500 000 000 - по 0.11 за 1 000 000 байт;
до 2 500 000 000 - по 0.95 за 1 000 000 байт;
если выше - по 0.08 за 1 000 000 байт.

Дерево в данном случае будет выглядеть так:

10.1.6. Тарифные опции

В зависимости от активированных опций можно менять логику тарифа. Ветка Тарифная опции отрабатывает, если в момент обсчета одна из указанных в ветке опций активна. В случае срабатывания одной из веток, последующие этого же уровня не отработают, даже если указаны те же опции. Отсутствие указанных опций означает, что ветка отработает в том случае, если не было срабатывания ветки Тарифная опция выше.

Для того, чтобы сделать понижение стоимости трафика на период, можно создать такой тариф:

При отсуствии активированных опций запрос попадет во вторую ветку и цена будет 2.0 . При активации опции Дешевый трафик, запрос попадет в первую ветку и цена будет 1.0.

Замечание

При работе тарифных опций в этом модуле есть такая особенность - тарифные опции при обсчете округляются до часа. Это связано с тем, что наработка в модуле IPN хранится одной цифрой за весь час и точности предоставляемых данных не хватает для более точного реагирования на тарифные опции.

10.2. Запуск начисления

Начисление производится планировщиком заданий, он должен быть запущен.

Асинхронное начисление производится на вкладке модуля Начисление. В выпадающем списке должны быть выбраны трафики для обсчёта. Если в фильтре договоров не выбраны договоры, производится тарификация всех договоров за выбранный месяц.

По окончанию начисления будет выслано письмо на указанный ящик. Если письмо не пришло, проверьте логи scheduler.out, scheduler.log на наличие ошибок. Возможная причина - неверные опции настройки почты в конфигурации сервера биллинга.

Ручной режим начисления используется в период наладки модуля, либо при необходимости перетарификации трафика абонента (абонентов) в связи с ошибками в тарифах, либо с ошибками в привязках услуг и, как следствие, неверной наработки по услугам в договоре. При каждом обсчёте происходит перетарификация всего месяца.

Автоматический режим реализуется добавлением задания Обсчёт логов IPN в планировщик.

Обратите внимание на строку mid=7 в параметрах задачи. Вместо 7 поставьте код вашего модуля IPN (можно посмотреть в Модули=>Редактор модулей и услуг).

При выполнении задачи начисления задача берет предыдущий минуте выполнения час и обсчитывает логи за этот месяц. Сделано это для того, чтобы можно было реализовать "Последний обсчёт" трафика за месяц, после обработки логов за последний час месяца. Кроме задачи периодического обсчёта логов добавьте точно такую же задачу, запускающуюся в 0 часов 50 минут 1 го дня любого месяца.

Если используете детализацию по тарифу в модуле бухгатерия, то для автоматического переобсчета детализации, в задачу "Последнего обсчета" добавьте параметр tariff_detail=1, в таком случае после последнего обсчета, будет произведен переобсчет с вычислением детализации по тарифу.

После выполнения тарификации в балансе договора должна появиться денежная наработка по обсчитываемым трафикам.

10.3. Начисление наработки за максимальные трафики

Начисление наработки за максимальные трафики осуществляется дополнительно к основной тарификации модуля периодически в ручном режиме, либо используя планировщик. В конфигурации модуля должны быть определены зависимости услуг, представляющих собой максимальные трафики, например:

max.traffic.74=39,40

В данном случае услуга с кодом 74 представляет собой максимум между услугами с кодами 39 и 40.

Начисление осуществляется по следующему алгоритму:

  1. выбираются все договоры с разрешённой услугой типа "Максимальный трафик" за обсчитываемый месяц;

  2. выбираются действующие у клиента тарифные планы в период действия услуги, получая наборы: договор - услуга - тариф - период;

  3. для каждого пункта набора осуществляется тарификация, причём дата в тарифном запросе передаётся равной последнему дню набора.

Пример 18.2. Пример логики работы

Предположим, что у нас есть договор Х, у которого с 3 сентября по 20 сентября разрешена услуга Макс. трафик 1. Предположим также, что в течении сентября у договора был Тариф1 с 1 по 10 и Тариф2 с 11 по 30.

В данном случае будут обсчитаны две позиции:

  1. услуга Макс. трафик 1, вычисленная на период с 1 по 10 по тарифу Тариф1;

  2. услуга Макс. трафик 1, вычисленная на период с 11 по 30 по тарифу Тариф2.

Для начисления максимальных трафиков можно использовать ручной режим, используя вкладку Начисление модуля.

Для автоматического начисления необходимо настроить задачу Максимальные трафики IPN в планировщике задач. В конфигурации задачи должно быть установлено:

mid=<код модуля>

Как и обсчёт логов DialUp задача берет месяц, отнимая час от текущего времени. Это позволит вам обсчитать все трафики по окончанию месяца, если запуск задачи будет установлен на 0 часов 55 минут последующего месяца. При этом необходимо настроить сброс сессий пользователей на границе месяца.

11. Установка типа правила в тарифе.

В тарифном плане можно изменять правило Тип правила шлюза с помощью узла Тип правила. Типы правил, их смена поддерживаются не всеми типами шлюзов. Описаны тут.

В тарифном плане алгоритм работы узла Тип правила похож на алгоритм работы узла Стоимость услуги. Основное отличие типа правила от стоимости услуги в том, что тип правила может быть определен не только внутри узла Услуга - он может быть на любом уровне в тарифе.

Это 2 разных запроса: получить стоимость, получить тип правила . Минимально в тарифе должна быть определена стоимость для тарификации. Наличие типа правила в тарифе не является необходимым. Для того, чтобы показать простейший тариф с типом правила, возьмем простейший тариф со стоимостью и добавим туда тип правила:

В данном тарифе , сам тариф определяет сразу тип правила .

Можно усложнить этот тариф условиями. Например так :

Тут мы установили разные тарифные опции в зависимости от времени суток. Можно сделать аналогичный тариф с узлами Период , Фильтр по времени и т.п .

Также можно делать тарифные планы, зависящие от наработки в конретной услуге . Например вот:

В данном случае добавлены 2 типа правил - 128 кбит/с для первых 400 МБ и 256 кбит/с для остального трафика. Добавлять тип правила в более, чем одну услугу не имеет смысла, т.к может отработать любая из этих веток, если есть трафик по обеим услугам.

Саму процедуру смены правил по тарифу делает задача Обсчета логов IPN. Но эта возможность явлется опциональной и включается с помощью настройки в конфигурации задачи:

set.rules=1

также есть дополнительный параметр

rule.error=1

Если его поставить в 1, то если в тарифе не будет найден тип правила, то сообщение об ошибке появится в логах коллектора (и вышлется на почту) по аналогии с ситуацией, когда цена в траифе не найдена. По умолчанию эти ошибки не логируются.

12. Настройка шлюзов

Шлюз - устройство, ограничивающее доступ абонента к интернету. В зависимости от статуса, установленного на вкладке Шлюз в договоре, биллинг передаёт управляющие воздействия на добавленные договору шлюзу с целью ограничить или открыть доступ в сеть.

Команды шлюзу передаются либо асинхронно, при смене статуса шлюза администратором, либо периодически по выполнению задания Проверка шлюзов IPN. Второй режим нужен в случае, когда статус шлюза изменяется самим модулем по состоянию баланса абонента.

Состояние шлюзов может быть следующим:

Открыт - шлюзы открыты;
Закрыт - шлюз закрыт, но может быть открыт пользователем через страницу статистики (например, абонент уехал на несколько дней);
Заблокирован - шлюз закрыт за задолженность на балансе;
Жёсткая блокировка - шлюз закрыт и может быть открыт только администратором;
Удалён - информация о пользователе удаляется из шлюзов (актуально для шлюзов, которым передаётся информация даже о закрытых абонентах, например, привязка маков к порту коммутатора);

Задача Проверка шлюзов IPN должна запускаться периодически, примерно раз в 15 минут. Работа задачи разделена на две стадии: смена статуса должников, синхронизация правил. В параметрах запуска задачи должно быть установлено:

mid=<код модуля IPN>

И опционально:

email=<адрес отправки отчёта о заблокированных клиентах>
thread.count=<Максимальное количество потоков при обработке шлюзов, по умолчанию 100>

В первой фазе задача изменяет статусы на Заблокирован открытым должникам. Должником считается договор, остаток баланса которого менее допустимого Лимита. Эту функцию можно отключить, если поставить в конфигурации задачи :

lock.status=0

Открытие должника происходит по событию прихода платежа на его счёт, при этом абонент может быть переведён в статус Открыт, либо Закрыт - это регламентируется переменной status.after.unlock конфигурации модуля. Если абонент переводится в статус Закрыт, он должен сам открыть шлюз через страницу статистики. По платежу открываются шлюзы договоров только с текущим активным статусом.

При смене статуса договора изменяется состояние его шлюзов. При всех, кроме активного, статусах, если состояние шлюзов открыт, они переходят в состояние заблокирован, при изменении статуса договора на активный, если состояние шлюза заблокирован, то он переходит в состояние, указанное переменной status.after.unlock.

Даже если абонент будет открыт, модуль лишь меняет статус шлюза, реальное открытие будет произведено при следующем срабатывании задачи Проверка шлюзов IPN, во второй её фазе.

Во второй фазе задача сверяет состояние на шлюзе с состоянием в БД и актуализирует состояние шлюза. При этом абоненты могут как блокироваться, так и открываться.

Состояние шлюза изменяется вслед за статусом.

Для добавления шлюза договору выберите вкладку Шлюзы в свойствах модуля для данного договора, далее на расположенной чуть выше панели инструментов выберите Новый элемент. Выберите шлюз в открывшемся списке.

В зависимости от типа шлюза меняются параметры и приёмы работы с ними, далее подробнее описан процесс работы со всеми поддерживаемыми биллингом типами шлюзов.

12.1. Настройка типов шлюзов

Типы шлюзов настраиваются на вкладке Типы шлюзов модуля IPN. Если добавить новый шлюз или редактировать уже добавленный, то откроется редактор типа шлюза. В этом редакторе конфигурация шлюза настраивается на вкладке Конфигурация :

Команды шлюза задаются на вкладке Команды:

Команды должны иметь следующий формат:

[DEFAULT]

[/DEFAULT]

[RULE ID="12,20"]
[/RULE]

То, что заключено в теги [DEFAULT] [/DEFAULT] - это команды шлюза по умолчанию. В тегах [RULE ID=""] [/RULE] - команды для конкретных правил , id которых перечислены через запятую в ID. Количество тегов [RULE ID=""] [/RULE] не ограничено. Эти теги остались для перехода с версии 4.4 на версию 4.5 и не рекомендованы к использованию.

12.2. Настройка шлюза

Сами шлюзы настраиваются на вкладке шлюзы модуля IPN:

Для того, чтобы добавить шлюз, нужно нажать кнопку "Добавить" на панели инстурментов . Откроется такой редактор:

Для каждого шлюза указывается ip-адрес, порт, ключевое слово, тип шлюза. Шлюз можно добавить как потомок другого шлюза. Шлюзы можно объединять в папки для структуризации. На отдельной вкладке можно задать адрес Шлюза. На вкладке конфигурация располагаются настройки шлюза . Как настраивать конкретные шлюзы (шлюз типа Manad и т.п) описано в соответствующих главах.

Также при нажатии правой кнопкой на шлюз в всплывающем меню доступны следующие пункты:

1) "вырезать" и "вставить" . Это позволяет копировать шлюз из одного места в другое (все потомки шлюза также копируются);

2) "Договоры " - выводит список договров, на которых добавлен данный шлюз;

3) "Мониторинг портов " - какие порты заняты на данном шлюзе .

Для поиска нужного шлюза по заданным параметрам нужно открыть фильтр шлюза нажатимем кнопки " Фильтр":

Здесь можно фильтровать шлюзы по хосту, типу, коментарию и адресу .

12.3. Типы правил

Типы правил шлюза глобальные, жёстко не привязаны к шлюзам и поддерживаются не всеми типами шлюзов. Они заполняются на вкладке Типы правил. Если добавить новое правило, то откроется редактор правила:

Вот пример кода типа правил :

speed=128

Правила можно воспринимать как параметры, которые потом подставляются в команды шлюзов. Пример команд шлюза :

[DEFAULT]
ipfw pipe {P0} config bw ${speed}
[/DEFAULT]

Все конструкции вида ${param} заменятся на соответствующие значение из правил.

Для каждого типа шлюза можно задать конкретные типы правил на вкладке Правила :

Этот список шлюзов показывается при добавлении шлюза в договор . Не все шлюзы поддерживают типы правил, более подробно смотрите в главах по конретным типам шлюзов.

В данном случае в выпадающем списке мы видим те типы правил, которые добавлены для данного типа шлюза . Но если отключить галочку фильтр, то мы увидим все типы правил в этом списке. Также тут есть история смены типов правил для данного договора на данном шлюзе :

Можно настроить смену типа правил в тарифе. Пример тарифа со сменой типа правил - тут. Тип правила на шлюзе меняет задача "Обсчёт логов IPN". При этом команды на оборудование реально посылаются в задаче "Проверка шлюзов IPN". Смена правил шлюза не поддерживается стандартными встроенными шлюзами, т.к., в общем случае, это задача специфическая . Для того, чтобы воспользоваться этой возможностью, нужно делать аналогичные скриптовые шлюзы.

12.4. Добавление шлюза в договор.

Для добавления шлюза в договор выбираем модуль IPN в договоре. Затем вкладку Свойства. Потом вкладку Шлюзы.

Там нажимаем кнопку добавления шлюза и видим список шлюзов.

Выбираем нужный шлюз. Если нужна дополнтиельная фильтрация, то нажимаем на кнопку "Фильтр", откроется дополнительный фильтр, который в точности повторяет фильтр настройки шлюзов . После выбора открывается диалог редактирования шлюза (зависит от типа выбранного шлюза), в нем нажимаем OK. Шлюз добавлен.

12.5. Выделение ресурса VLAN на шлюз.

Можно выделять ресурс VLAN на договор. Некоторые типы шлюзы могут использовать VLAN. Для этого в конфигурации шлюза прописываем строку :

range=2-10;15;20-4096

Это диапазоны, из которых генерируются свободные VLAN . В данном случае VLAN может быть между 2 и 10, может равняться 15, и быть между 20-4096.

Для выделения VLAN на договор выбираем модуль IPN в договоре ->Свойства->Шлюзы->Ресурсы vlan.

Тут? если нажать на кнопку добавить, то откроется список шлюзов и в нем можно выбрать шлюз, для которого выделяется VLAN для данного договора.

Тут выбитраем нужный нам шлюз . Если нужна дополнтиельная фильтрация, то нажимаем на кнопку "Фильтр", откроется дополнительный фильтр, который в точности повторяет фильтр настройки шлюзов .

Можно задать VLAN вручную, а можно заполнить его автоматически первым свободным VLAN на данном шлюзе (галочка авто). Свободный VLAN выделяется по умолчанию из диапазона : 2-4096 . Для того, чтобы это изменить нужно в конфигурации шлюза поставить :

vlan.range=2-1000;1010;2000-4096

В этом примере выделяются диапазоны: со 2-го по 1000 и с 2000-го по 4096-ой и отдельно 1010.

12.6. Настройка портов шлюза.

Псоле добавления в договор шлюза, можно указать на отдельной вкладке его порты.

При нажатии на кнопку добавить (или при редактировании уже добавленных позиций) появляется редактор:

Тут есть 2 варианта: либо выделить порты автоматически (галочка авто), либо вручную перечислить через запятую в поле "порты". В случае автоматического выделения по умолчанию порты выделяются из диапазаона 1-24. Этот диапазон можно поменять, указав в конфигурации шлюза опцию :

port.range=1-10;12;16-24

В данном примере порты могут быть c 1-го 10-ый , 12-ый, и с 16-го по 24-ый.

Данные порты не используются в стандартных типах шлюзов, и, если необходимы для управления, то их можно использовать только в шлюзах, реализованных на BeanShell.

Также можно вести учет занятых портов на шлюзе. Для этого в редакторе шлюзов(Модули->IPN>Шлюзы) , нужно вызвать правой кнопкой контекстное меню на конретном шлюзе и в нем выбрать "Мониторинг портов".

12.7. Настройка шлюзов типа Manad

Данный тип шлюза позволяет управлять файрволом на PC-роутерах. Мы предлагаем 2 варианта: для роутеров FreeBSD (файрвол ipfw) и Linux (файрвол iptables +iproute2).

На вкладке модуля IPN Типы шлюзов добавляется тип шлюза Manad со следующей конфигурацией:

user_rule.editor.class=bitel.billing.module.services.ipn.editor.ManadContractRuleEditor
gate_manager.class=bitel.billing.server.ipn.ManadGateWorker

На роутере должен быть запущен manad - менеджер файрвола. Это программа написана на Perl. Её задача висеть на порту и слушать команды биллинга по закрытию или открытию договора.

12.7.1. Спецификация Manad

Если вы не хотите реализовывать Manad собственными силами, либо изменять один из предлагаемых вариантов, то вы можете пропустить этот раздел и перейти сразу к описанию того варианта (FreeBSD или Linux ), который вас устраивает.

Manad принимает от BGBilling-сервера следующие строки:

1. add num rules;

2. remove num rules;

3. test.

В качестве разделителя используется символ табуляции. num - это id договора клиента, rules - это строка с набором команд, внутри которой команды разделяются символом "|". Подразумевается, что команда add добавляет правила, команда remove - удаляет. В ответ на команду test Manad шлёт список id договоров (разделённых символом пробела), открытых на данном шлюзе.

12.7.2. Обработка команд Manad.

На стороне сервера типы правил проходят следующую обработку : для всех тегов <LOOP> </LOOP> все их содержимое дублируется для каждого ip-адреса. При этом:

1. Макрос вида {A} заменяются на ip-адреса клиента из выбранного диапазона;

2. Подстановки вида {XN}, где X - латинская буква, а N - цифра также обрабатываются для каждого ip-адреса. Начинать нумеровать эти последовательности нужно обязательно с нуля. Для каждого ip-адреса по каждой букве увеличивается индекс. Т.е., например, подстановки {A0}, {A1}, {B0} для 1-го ip-адреса преобразуется в {A0}, {A1}, {B0} ; для второго ip-адреса в {A1}, {A2}, {B1} и т.п.

Т.е. например строки :

<LOOP>
pipe {P0} config bw 128000
pipe {P1} config bw 128000
add {N0} pipe {P0} ip from any to {A} out
add {N0} pipe {P1} ip from {A} to any in
</LOOP>

для ip-адресов 192.168.184.10, 192.168.184.11 и 192.168.184.12 преобразуются в :

pipe {P0} config bw 128000
pipe {P1} config bw 128000
add {N0} pipe {P0} ip from any to 192.168.184.10 out
add {N0} pipe {P1} ip from 192.168.184.10 to any in
pipe {P2} config bw 128000
pipe {P3} config bw 128000
add {N1} pipe {P2} ip from any to 192.168.184.11 out
add {N1} pipe {P3} ip from 192.168.184.11 to any in
pipe {P4} config bw 128000
pipe {P5} config bw 128000
add {N2} pipe {P4} ip from any to 192.168.184.12 out
add {N2} pipe {P5} ip from 192.168.184.12 to any in

3. Аналогичным образом происходит обработка тега <LOOP_NET > для сетей. Строки дублируются для каждой сети. Тут доступны следующие макросы: {IP} - первый адрес сети, {MASK} - маска сети вида xx.xx.xx.xx, {MASK_WILD} - инвертированная маска сети, {MASK_BIT} - битовая маска сети вида xx.

Напрмер строки вида :

<LOOP_NET>
permit {IP}/{MASK_BIT}
</LOOP_NET>

Для сетей 192.169.185.0/24, 192.169.186.0/24 преобразуется в:

permit 192.169.185.0/24
permit 192.169.186.0/24

12.7.3. Настройка шлюзов типа Manad под FreeBSD

В настоящее время реализован manad для шлюзов под управлением FreeBSD. Скачать его можно здесь. Необходимо установить его на вашем шлюзе (предварительно потребуется установить Perl) и добавьте в автозапуск.

На вкладке Типы правил добавим два типа правила для данного типа шлюза. Допустим, мы предоставляем доступ двух типов: 10-мегабитный и 128-килобитный. Добавляем в типах правил две записи.

speed=10000000

и

speed=128000

На вкладке Команды в типе шлюза пишем :

[DEFAULT]
<LOOP>
pipe {P0} config bw ${speed}
pipe {P1} config bw ${speed}
add {N0} pipe {P0} ip from any to {A} out
add {N0} pipe {P1} ip from {A} to any in
</LOOP>
[/DEFAULT]

На вкладке Правила в типе шлюза добавляем оба новых правила:

Как видно из примера команды Manad включает в себя подстановки адреса вида {A}, а также другие виды подстановок вида {XN}, где X - латинская буква, а N - цифра. Подстановка адреса осуществляется биллингом перед отсылкой команд, либо при сохранении правила для договора, в зависимости от используемого вида правила (пользовательское/типизированное). Подстановки вида {XN} отправляются на manad вместе с командами для определения номеров пайпов и правил.

Подстановки вида {NET} и {NET_MASK} заменяются на выбранные сети для тегов <LOOP_NET> и <LOOP_NET_MASK>. О том, как это происходит читайте обработку правил Manad.

После создания типа шлюза Manad, типов правил и команд для него необходимо определить конкретные адреса шлюзов на вкладке Шлюзы.

На вкладке Конфигурация шлюзов типа Manad ничего указывать не нужно.

Для добавления пользователя на шлюз откройте договор на вкладке модуля IPN - Шлюзы.

Затем нажмите кнопку Добавить и произведите выбор шлюза. При этом отобразятся только те шлюзы, на которые клиент ещё не был заведён.

Если выбранный шлюз был типа Manad, то откроется редактор правил договора Manad.

Слева в выпадающем списке можно выбрать тип правила, в дереве справа - адреса и сети, на которые оно применяется. В области Команды отображается текст команд, которые будут отправлены на шлюз. При этом, если выбран тип "Пользовательский", то область Команды редактируемая и правило сохраняется в точно таком же виде в БД. Т.е. в этом случае вы можете установить клиенту любые команды, не завязываясь на типе.

Если же выбран тип правила и список адресов, то в базе сохраняется только это сочетание, а текст команд вычисляется динамически в момент отправки на шлюз. При этом выглядит оно так, как отображено в области Команды. Использование типов позволяет более просто менять команды для многих пользователей, просто поправив шаблон в типе.

Для создания пользовательского правила на основании шаблонного выбирается тип правила, адреса, после чего тип правила переключается в "Пользовательский". После чего текст правила может быть изменён.

После настройки биллинга необходимо произвести настройку самого ipfw и установку manad на шлюз.

Доступ клиентам разрешается путём добавления динамических правил файрвола с номером менее 20000.

Предварительно в файле /etc/rc.firewall добавьте правило, запрещающее всем пакетам проход через шлюз. Кроме того, в нашем случае нужно добавить адрес NAT-сервера для того, чтобы мы сами могли выходить в сеть.

Другим решением является изменение структуры сети с установкой шлюза между клиентами и магистралью провайдера.

Ниже приведена конфигурация, подходящая для нашей сети:

fw="/sbin/ipfw -q"

# flush out the list before we begin.
${fw} -f flush

# localhost spoofprotect
${fw} add 10 pass all from any to any via lo0
${fw} add 10 deny all from any to 127.0.0.0/8
${fw} add 10 deny all from 127.0.0.0/8 to any

# deny netbios stuff
${fw} add 20 deny tcp from any to any 135-139,445,593
${fw} add 20 deny udp from any to any 135-139,445

#ssh,telnet, ftp только с адреса NAT сервера
${fw} add 30 pass tcp from 14.3.3.8 to me 20-23
${fw} add 30 pass tcp from me 20-23 to 14.3.3.8

# manad - доступ к манаду сервера биллинга
${fw} add 40 pass tcp from 14.3.3.8 to me 4567
${fw} add 40 pass tcp from me 4567 to 14.3.3.8

###############################################
# Запрет на всякий трафик из нашей сети 14.3.3.0
###############################################
${fw} add 20000 deny all from any to 14.3.3.8/24
${fw} add 20000 deny all from 14.3.3.8/24 to any

## Здесь manad будет добавлять свои правила, открывающие доступ клиентам

${fw} add 30000 pass all from any to any

12.7.4. Настройка шлюза типа Manad под Linux

Здесь предлагается пример manad'а для шлюзов под управлением Linux. Скачать его можно здесь. Необходимо установить его на вашем шлюзе (предварительно потребуется установить Perl) и добавить в автозапуск. В данном примере происходит управление службой iptables и ограничение трафика с помощью iproute2. Архив состоит из 3 частей:

1.manad_linux.pl - сам manad (написан на perl);

2.init_shaping.sh - инициализация правил ограничения трафика в системе (описано ниже);

3. start_manad.sh - скрипт запуска (вызывает вначале init_shaping.sh, а потом manad_linux.pl);

4. stop_manad.sh - скрипт остановки.

На вкладке Команды в типе шлюза добавим команды для данного типа шлюза. Пусть мы хотим для всех ip-адресов клиента (т.е. все они поделят между собой канал) ограничивать входящий трафик значением в 256 кбит/с, а исходящий трафик значением 128 кбит/с. Для этого создадим 2 класса, отдельно для входящего и исходящего трафика .

[DEFAULT]

[OPEN]

<LOOP>
iptables -A FORWARD -t filter -s {A} -j ACCEPT
</LOOP>

/sbin/tc class add dev eth0 parent 1:0 classid 1:[N1] htb rate 256kbit burst 4k prio 1
/sbin/tc qdisc add dev eth0 parent 1:[N1] handle [N1]: sfq perturb 10 quantum 1500

/sbin/tc class add dev eth0 parent 1:0 classid 1:[N2] htb rate 128kbit burst 4k prio 1
/sbin/tc qdisc add dev eth0 parent 1:[N2] handle [N2]: sfq perturb 10 quantum 1500

<LOOP>
/sbin/tc filter add dev eth0 parent 1:0 protocol ip prio [N1] u32 match ip dst {A}  flowid 1:[N1]
</LOOP>

<LOOP>
/sbin/tc filter add dev eth0 parent 1:0 protocol ip prio [N2] u32 match ip src {A} flowid 1:[N2]
</LOOP>

[/OPEN]
[CLOSE]
<LOOP>
/sbin/iptables -D FORWARD -t filter -s {A} -j ACCEPT
</LOOP>
/sbin/tc filter del dev eth0 parent 1:0 protocol ip prio [N1]
/sbin/tc filter del dev eth0 parent 1:0 protocol ip prio [N2]

/sbin/tc class del dev eth0 parent 1:0 classid 1:[N1] htb rate 256kbit burst 4k prio 1
/sbin/tc class del dev eth0 parent 1:0 classid 1:[N2] htb rate 128kbit burst 4k prio 1

[/CLOSE]

[/DEFAULT]

Здесь теги [OPEN][/OPEN] и [CLOSE] [/CLOSE] - это теги, которые обрабатывает данный конкретный тип manad'а и означают они, соответственно, набор открывающих правил и набор закрывающих правил . Аналогично тег [NX] - тоже обрабатывается самим manad'ом , туда просто вставляется свободный индекс, который увеличивается с каждым новой командой на открытие manad'а. В данном случае отличие от {NX} в том, что это комбинации не обрабатывается га стороне сервера(сервер увеличивает N для каждого ip), а обрабатывается самим manad'ом Т.е. в данном случае на стороне сервера данный набор правил преобразится в:

[OPEN]

iptables -A FORWARD -t filter -s 192.168.184.10 -j ACCEPT
iptables -A FORWARD -t filter -s 192.168.184.11 -j ACCEPT

/sbin/tc class add dev eth0 parent 1:0 classid 1:[N1] htb rate 256kbit burst 4k prio 1
/sbin/tc qdisc add dev eth0 parent 1:[N1] handle [N1]: sfq perturb 10 quantum 1500

/sbin/tc class add dev eth0 parent 1:0 classid 1:[N2] htb rate 128kbit burst 4k prio 1
/sbin/tc qdisc add dev eth0 parent 1:[N2] handle [N2]: sfq perturb 10 quantum 1500

/sbin/tc filter add dev eth0 parent 1:0 protocol ip prio [N1] u32 match ip dst 192.168.184.10  flowid 1:[N1]
/sbin/tc filter add dev eth0 parent 1:0 protocol ip prio [N1] u32 match ip dst 192.168.184.11  flowid 1:[N1]

/sbin/tc filter add dev eth0 parent 1:0 protocol ip prio [N2] u32 match ip src 192.168.184.10 flowid 1:[N2]
/sbin/tc filter add dev eth0 parent 1:0 protocol ip prio [N2] u32 match ip src 192.168.184.11 flowid 1:[N2]

[/OPEN]

[CLOSE]

/sbin/iptables -D FORWARD -t filter -s 192.168.184.10 -j ACCEPT
/sbin/iptables -D FORWARD -t filter -s 192.168.184.11 -j ACCEPT

/sbin/tc filter del dev eth0 parent 1:0 protocol ip prio [N1]
/sbin/tc filter del dev eth0 parent 1:0 protocol ip prio [N2]

/sbin/tc class del dev eth0 parent 1:0 classid 1:[N1] htb rate 256kbit burst 4k prio 1
/sbin/tc class del dev eth0 parent 1:0 classid 1:[N2] htb rate 128kbit burst 4k prio 1

[/CLOSE]

Это то, что получит сам manad. Как видим, сервер вырезал теги <LOOP>и {A} Аналогично, подстановки вида {NET} и {NET_MASK} заменяются на выбранные сети для тегов <LOOP_NET> и <LOOP_NET_MASK>. О том, как это происходит, читайте обработку правил Manad.

Manad работает следующим образом . Он получает правила, заменяет в них [NX] на число (в данном случае свободный номер класса по ограничению трафика ), далее делит правила на 2 части: открывающие и закрывающие. Открывающие применяются , а закрывающие запоминаются и применяются при получении команды на закрытие для данного договора.

Для инициализации правил iproute2 в системе используется скрипт init_shaping.sh :

INDEV="eth0"

/sbin/tc qdisc del dev $INDEV root 2> /dev/null

##### speed server->client(downstream) 

/sbin/tc qdisc add dev $INDEV root handle 1: htb default ffff r2q 1

#default  
/sbin/tc class add dev $INDEV parent 1:0 classid 1:ffff htb rate 100mbit burst 4k prio 3
/sbin/tc qdisc add dev $INDEV parent 1:ffff handle ffff: sfq perturb 10 quantum 1500

Инициализацию правил iptables вы может проводить в зависимости от вашей настройки сети. В данным примере надо, как минимум, установить запрет на цепочку FORWARD таблицы filter, т.к. туда добавляются разрешающие правила. Это можно установкой политики по умолчанию:

/sbin/iptables -P FORWARD REJECT

12.8. Настройка шлюзов типа Switch

Шлюзом типа Switch может выступать любой управляемый коммутатор с поддержкой SNMP и MIB-IFACES. Предполагается, что SNMP на коммутаторе уже настроен и заведено community с r-w правами, например billing.

Для начала необходимо установить номера интерфейсов, которые есть на вашем коммутаторе. Очень удобно для этого под Windows использовать утилиту GetIf, которую вы можете скачать по адресу: http://www.wtcs.org/snmp4tpc/FILES/Tools/SNMP/getif/getif-2.3.1.zip

Определения существующих интерфейсов установите в первой вкладке имя community и адрес хоста, соединитесь.

В данном случае соединение шло с SNMP-агентом MS WIN машины. Далее на вкладке MBrowser выберите ветку .1.3.6.1.2.1.2.2.1.2 и нажмите Start.

Далее необходимо составить карту-код интерфейса - его понятное администратору обозначение.

Например в нашем случае интерфейс 1 - это LO, 65539 - ETH1. К сожалению getif некорректно отображает значение поля ifDescr, поэтому приходится ориентироваться по другим полям, например ifType.

В случае, если вы предпочитаете работать с UNIX-системами, воспользуетесь утилитой snmpwalk из пакета (bbb - это имя community):

snmpwalk -Os -c bbb -v 1 192.168.184.2 .1.3.6.1.2.1.2.2.1.2

Вывод будет примерно следующий:

[root@gate ~]# snmpwalk -Os -c bbb -v 1 192.168.184.2 .1.3.6.1.2.1.2.2.1.2
ifDescr.1 = STRING: MS TCP Loopback interface
ifDescr.65539 = STRING: 3Com Gigabit LOM (3C940)

Таким образом мы получаем карту интерфейсов.

Следующий шаг - создание типа шлюза. Допустим, мы хотим создать тип шлюза CISCO XXX с определённым набором фиксированных интерфейсов (портов), причём на каждом из шлюзов этого типа могут быть дополнительные интерфейсы типа VLAN.

В конфигурации должно быть указано следующее:

user_rule.editor.class=bitel.billing.module.services.ipn.editor.SwitchContractRuleEditor
gate_manager.class=bitel.billing.server.ipn.SwitchGateWorker
#версия snmp 1 или 2c
snmp.version=1

При указании snmp.version=0 биллинг не будет выполнять действий по управлению устройством при смене статуса шлюза, в этом случае шлюз может быть использован только для учёта.

Далее указываются номера интерфейсов

iface.65539=ETH1

Типы правил для Switch-шлюзов создавать не нужно, можно сразу создавать шлюз. В шлюзе можно добавить специфичные для него интерфейсы.

Теперь при добавлении шлюза в договор после выбора шлюза 127.0.0.1 отобразится следующий редактор.

Программа отобразит только свободные на данном шлюзе порты. Выбрав порт вы укажете программе, что его нужно блокировать в случае перевода статуса договора в IPN модуле в закрыт или заблокировано.

Также в конфигурации шлюза можно поставить опцию

#Интервалы в миллисекундах между неудачными попытками связаться по snmp. 500,1000,2000,5000,5000 - значения по умолчанию.
#retry.intervals=500,1000,2000,5000,5000

12.9. Настройка шлюза BGRadiusIPN

Данный тип шлюза позволяет предоставлять доступ к виртуальным частным сетям на оборудовании CISCO с авторизацией по логину/паролю. В свойствах шлюза могут быть указаны логин и пароль авторизации, выдаваемый фиктивному интерфейсу адрес и маршрутизируемые через него сети.

Установите и настройте BGRadiusIPN

processor.class=bitel.billing.server.processor.ipn.IPNProcessor
processor.mid=0
# Порт запроса аутентификации
auth.port=
# Порт управления (должен быть доступен только серверу биллинга)
admin.port=

auth.thread.count=10
netflow.thread.count=10

Создайте тип шлюза RadiusPPPoE с параметрами

user_rule.editor.class=bitel.billing.module.services.ipn.editor.RadiusPPPoEContractRuleEditor
gate_manager.class=bitel.billing.server.ipn.PPPoEGateWorker
# Адрес/порт управления сервера радиуса BGRadiusIPN
radius.host=
radius.port=
# Добавьте список VRF, которые будут привязываться к реалму 
# (при соединении будет передаваться атрибут cisco-avpair=lcp:interface-config=ip vrf forwarding ${vrf})
vrf.1=Internet

На вкладке Типы правил создайте типы правил. Тип правила для данного типа шлюза понимается как реалм . Вот пример текста типа правила:

realm=default
attributes=Service-Type=2;Framed-Protocol=1;Framed-MTU=1492;Port-Limit=1;Auth-Type=accept;Acct-Interim-Interval=60;Cisco-AVPair=multilink:max-links=6;Cisco-AVPair=multilink:min-links=1;Cisco-AVPair=lcp:interface-config=ip unnumbered Loopback135

Необходимо указать реалм (realm) и список атрибутов по умолчанию, которые будут присваиваться пользователю при аутентификации им через данный реалм (attributes) в формате атрибут=значение;атрибут=значение без использования синонимов для числовых типов значений (т.е не Framed-Protocol=PPP, а Framed-Protocol=1). Создадим для примера 2 реалма - default и local. Сами типы правил пусть называются PPPoE-default и PPPoE-local. Оба правила нужно добавить для данного типа шлюза (при редактировании типа шлюза - вкладка Типы правил).

Создайте шлюз на вкладке Шлюзы, указав тип шлюза, NAS ip в качестве параметра хоста, 0 в качестве параметра порт и секрет наса - Ключевое слово.

C версии 4.4 возможен сброс существующих сессий при закрытии шлюза. Для этого в конфигурации шлюза необходимо указать класс инспектора сессий и его параметры, аналогично модулю DialUp (см. Настройка NASов).

Пример конфига:

snmp.version=2
#
nas.inspector.class=bitel.billing.server.processor.SNMPNASConnectionInspectorType3
nas.inspector.snmp.port=161
nas.inspector.snmp.community=XXXXX
nas.inspector.snmp.kill.oid=1.3.6.1.4.1.9.9.150.1.1.3.1.5
nas.inspector.snmp.check.oid=1.3.6.1.4.1.9.9.150.1.1.3.1.5

Далее для клиента в параметрах договора на вкладке модуля добавьте созданный шлюз, в настройках укажите используемые правила (реалмы), ip-адрес, маршрутизируемые сети, VRF.

IP-адреса берутся из одиночных диапазонов (81.30.224.1-81.30.224.1), список маршрутизируемых сетей ("Сети") - из обычных диапозонов (вкладка Адреса)

После добавления/изменения параметров шлюза необходимо закрыть и снова открыть шлюз для обновления параметров на самом шлюзе.

Клиент привязывается к данному шлюзу и сможет авторизироваться только на нем. Шлюз определяется по NAS IP.

12.10. Настройка шлюза CISCO

Данный тип шлюза используется для управления ACL-записями на CISCO маршрутизаторах посредством SSH-соединения. При этом сама ACL-запись должна быть создана администратором вручную и в неё должны быть добавлены правила, разрешающие доступ к DNS и Биллинг-сервера в начале списка и правило запрета всего в конце списка. Биллинг работает только с extended ACL-списками.

Между ними биллинг помещает правила, открывающие конкретные адреса клиентов.

На вкладке Типы правил добавьте тип правила "Пустое правило" и оставьте текст этого правила пустым.

На вкладке Типы шлюзов создайте тип шлюза CISCO и установите в нем следующую конфигурацию:

user_rule.editor.class=bitel.billing.module.services.ipn.editor.CiscoContractRuleEditor
gate_manager.class=bitel.billing.server.ipn.CiscoGateWorker

В командах этого типа шлюза установите, например:

[DEFAULT]
<LOOP>
permit ip host {A} any
</LOOP>
[/DEFAULT]

Шаблон может быть многострочным, вместо {A} будет подставлен адрес клиента. К каждому адресу будут применены все строки шаблона. Обработка команд cisco происходит аналогичным образом, как и обработка команд Manad. Т.е макросы вида {A} заменяются на адрес из выбранных диапазонов для тегов <LOOP>, а макросы {NET} и {NET_MASK} заменяются на выбранные сети для тегов <LOOP_NET> и <LOOP_NET_MASK> соответственно.

На вкладке Правила данного типа шлюза добавьте "Пустое правило".

На вкладке Шлюзы заведите шлюз типа CISCO.

Необходимо указать хост и порт SSH-соединения, SSH-пароль указывается в поле Ключевое слово. В конфигурации шлюза указывается SSH-логин (userbill на снимке) и список ACL-записей.

acl.<id>.name=<имя ACL-записи>
acl.<id>.from.pos=<с какой позиции биллинг будет вставлять правила>
acl.<id>.to.pos=<до какой позиции биллинг будет вставлять правила>
acl.<id>.on.contract=<количество правил на договор>

Так же можно указать время ожидания ответа, по истечению которого, шлюз сбрасывает соединение и выдаёт ошибку :

timeout=2000

Параметр id - уникальный номер ACL-записи в биллинге должен быть уникальным и не меняться после создание ACL в конфигурации, если необходимо добавить ещё ACL, увеличьте его.

Пользователь на CISCO должен быть создан с привилегией 15 следующим образом:

aaa new-model 
! 
! 
aaa authentication login default local enable 
aaa authorization exec default local 
! 
username xxx password yyy 
username xxx privilege 15

Внимание

Для корректной работы шлюза на cisco символ приглашения должен быть - #.

Биллинг разделяет область правил от from.pos до to.pos на зоны, принадлежащие договорам размером on.contract (этот параметр желательно ставить с запасом, например 1000 так, чтобы договору точно хватило размера зоны). Далее при процедуре управления шлюзами правила либо добавляются в соответствующую договору зону, либо удаляются из неё.

При добавлении клиенту шлюза CISCO открывается редактор следующего вида. В верхнем поле необходимо выбрать правило, в списке снизу ACL, в котором открывается клиент, в дереве справа - адреса клиента на данном шлюзе.

Поле С позиции пусто при добавлении шлюза клиенту, при редактировании в нем отразится с какой позиции выделена клиенту свободная зона правил ACL. На вкладке Команды можно видеть какие команды будут добавлены для открытия клиента.

После добавления шлюза клиенту переключение выпадающего списка управления в Открыть должно добавить правила на выбранный ACL.

12.11. Настройка шлюза DLINK 35xx, 38xx

Данный тип шлюза используется для управления ACL-записями данного коммутатора посредством SNMP-управления. Необходимо настроить коммутатор для приёма SNMP-запросов с сервера биллинга и создать RW community. Шлюз рассчитан на подключение одного IP-адреса на порт коммутатора с авторизацией DHCP OPTIONS 82 по порту коммутатора.

Создайте в биллинге тип шлюза DLINK со следующими настройками:

user_rule.editor.class=bitel.billing.module.services.ipn.editor.DlinkContractRuleEditor
gate_manager.class=bitel.billing.server.ipn.DlinkGateWorker
#версия snmp 1 или 2c
snmp.version=1
#1 - для 35xx, 2 - для 38xx
model=1

На вкладке Шлюзы создайте шлюз типа DLINK.

В адрес и порт шлюза внесите адрес управления и SNMP-порт, ключевое слово - SNMP community. В конфигурации укажите следующее:

# Маска открытых серверов
open.mask=255.255.255.255
# Адрес открытого сервера
open.address=85.95.148.88
# Количество портов
ports=50
# Номера uplink портов (связь с другими коммутаторами)
uplink=49,50
# Занимаемые профили
profile.4=4
profile.8=8
profile.12=12
profile.16=16
profile.20=20
profile.24=24
profile.28=28

# Интервалы в миллисекундах между неудачными попытками связаться по snmp. 500,1000,2000,5000,5000 - значения по умолчанию.
#retry.intervals=500,1000,2000,5000,5000

Открытые сервера - статистика, DNS и все, те которые должны быть открыты даже для заблокированного клиента. Открыты будут все адреса наложение указанной маски, на которые даст указанный адрес.

В свойствах шлюза в договоре необходимо указать какой адрес занимает какой порт коммутатора.

12.11.1. Настройка в связке с DHCP шлюзом.

О том, как настроить DHCP - сервер/шлюз читайте тут. Если DHCP будет работать в связке со шлюзами DLink, то необходимо добавить такие настройки для сервера DHCP.

processor.class=bitel.billing.server.ext.dhcp.DHCPRelayProcessor

# Номер субопции в Option 82, в которой  хранится VLAN клиента (нумерация с 1)
dhcp.82.key.option.code=1
# Позиция (номер байта) внутри субопции, в которой  хранится порт клиента (нумерация с 0).
dhcp.82.key.position=5

После синхронизации клиента на шлюзе DLINK будет вызвана синхронизация клиента на BGDhcpIPN, а именно порт коммутатора: IP-адрес.

При подключении клиента, он отправит запрос на получение IP-адреса, коммутатор, при включённом и настроенном DHCP Relay, добавив данные RelayAgent Options, перенаправит запрос на DHCP-сервер BGDhcpIPN, который по ip шлюза и порту клиента, указанному в RelayAgent Options, выдаст IP-адрес.

12.12. Настройка сервера/шлюза DHCP

Данный тип шлюза используется для автоматической выдачи IP адресов клиентам, заведённым через шлюз DLINK и Cisco2. На коммутаторе включается режим и указывается DHCP relay server - сервер, на который коммутатор будет перенаправлять запросы DHCP. В данном случае сервер, где будет стоять BGDhcpIPN.

Распакуйте BGDhcpIPN и установите как службу. В dhcp.properties:

# Порт управления/синхронизации
admin.port=1855

# Порт, на котором поднимается BGDhcpIPN. По умолчанию (и по станадарту тоже ) - 67 .
#dhcp.port = 67
# Интерфейс, на котором будет поднят BGDhcpIPN. Если не указан, то на всех интерфейсах. 
#dhcp.host=

# Максимальное кол-во потоков, обрабатывающих запросы
dhcp.thread.count=10

# Задержка после запуска перед сохранением данных коммутатор/порт:ip в файл
dhcp.data.save.delay=3600
# Ожидание перед периодическим сохранением данных в файл
dhcp.data.save.period=3600
# Каталог, в котором будет сохраняться файл
dhcp.data.save.path=<some_path>
# При нормальном Stop, перед завершением работы, сервер запишет данные снова
# эти данные загружаются при старте сервера

# Идентификатор сервера. Должен быть ip-адресом интерфейса, на который будут приходить запросы
dhcp.server.identifier=10.0.0.2

Специфические настройки для работы c DLink и Cisco2 читайте в главах, описывающиx соответствующие шлюзы.

Запускать BGDhcpIPN необходимо от root, иначе сервер не сможет открыть DHCP-порт.

Добавьте тип шлюза DHCP с конфигурацией

user_rule.editor.class=bitel.billing.module.services.ipn.editor.EmptyContractRuleEditor
gate_manager.class=bitel.billing.server.ipn.DHCPGateWorker

Добавьте шлюз DHCP, указав адрес и порт управления/синхронизации, а шлюзы (DLink или Cisco2), которые будут пересылать DHCP-запросы на BGDhcpIPN сделайте дочерними по отношению к этому шлюзу.

Таким образом, после синхронизации клиента на шлюзе DLINK или Cisco2 будет вызвана синхронизация клиента на BGDhcpIPN.

При подключении клиента он отправит запрос на получение IP-адреса, коммутатор, при включенном и настроенном DHCP Relay, добавив данные RelayAgent Options, перенаправит запрос на DHCP-сервер BGDhcpIPN, который по данным в RelayAgent Options, выдаст IP-адрес. По каким правилам выдавать адрес зависит от конкретного шлюза и описывается в описании этих шлюзов.

Параметры, выдающиеся клиенту кроме ip-адреса, могут задаться 2-мя способами.

Первый способ.

Параметры настраиваются в конфигурации шлюзов, причём родительские параметры наследуются потомками. Т.е если указать параметры только в конфигурации шлюза DHCP, то для всех шлюзов-потомков будут выдаваться такие параметры, если же в каком-либо из потомков параметр должен отличаться, можно указать только его.

# Time Offset в секундах
dhcp.timeOffset=-18000
# Pоутер(ы), если несколько - через запятую
dhcp.router=Cg
# Домен
#dhcp.domain=
# DNS-сервер(а), если несколько - через запятую
dhcp.dns=
#М аска подсети
#dhcp.subnetMask=255.0.0.0
dhcp.subnetMask=

# Время аренды ip-адресов, в секундах, по умолчанию 43200
#dhcp.ipAddressLeaseTime
#
# Также можно выдавать все остальные опции dhcp, в виде dhcp.option.x=ffffffff
# где x - код dhcp опции, ffffffff - байты в 16ричном виде
# Например, сервер NTP по адресу 127.0.0.1, в конфиге нужно указать:
#dhcp.option.42=7F000001
# Коды других опций можно узнать в rfc2132

Второй способ.

Этот способ перетирает опции, установленные первым сопсобом .

Параметры настраиваются в dhcp.properties. Они задаются с привзязкой к сети, из которой будет выдаваться ip.

# Первый ip сети 1 
net.1.ip=1.1.33.0
# Маска сети (количество неизменяемых бит)
net.1.bits=24
# Роутер(ы), если несколько - через запятую
net.1.dhcp.router=10.10.10.10
# Маска подсети
net.1.dhcp.subnetMask=255.255.255.0 

# Первый ip сети 2 
net.2.ip=1.1.34.0
# Маска сети 2 (количество неизменяемых бит)
net.2.bits=24
# Роутер(ы), если несколько - через запятую
net.2.dhcp.router=10.10.10.10
# Маска подсети
net.2.dhcp.subnetMask=255.255.255.0

Синтаксис задания параметров такой же, как для шлюзов, за исключением приставки net.X., где X - порядковый номер сети. Эти параметры перетирают параметры, установленные в конфигурации шлюзов.

Специфические настройки для работы c DLink и Cisco2 читайте в главах, описывающих соответствующие шлюзы.

12.13. Настройка шлюза Mikrotik RouterOS

Данный тип шлюза используется для управления маршрутизаторами Mikrotik посредством SSH или Telnet-соединения. Биллинг помещает правила, открывающие конкретные адреса клиентов.

На вкладке Типы шлюзов создайте тип шлюза Mikrotik и установите в нем следующую конфигурацию:

user_rule.editor.class=bitel.billing.module.services.ipn.editor.MikrotikContractRuleEditor
gate_manager.class=bitel.billing.server.ipn.MikrotikTelnetGateWorker

Приведенная выше конфигурация для telnet-соединения. Для ssh-соединения поменяйте gate_manager.class=bitel.billing.server.ipn.MikrotikGateWorker. Но мы не рекомендуем его использовать для больших нагрузок.

На вкладке Команды при редактировании данного типа шлюза задайте:

[DEFAULT]
[OPEN]
<LOOP>
ip firewall address-list add address={A} list=ACCESS_LIST comment=!!{CID}!!
</LOOP>
[/OPEN]

[CLOSE]
<LOOP>
ip  firewall address-list remove "!!{CID}!!"
</LOOP>
[/CLOSE]

[DELETE]
<LOOP>
ip  firewall address-list remove "!!{CID}!!"
</LOOP>
[/DELETE]
[/DEFAULT]

Здесь команды разделяются на 3 блока: открывающие команды (между тегами [OPEN][/OPEN]), закрывающие команды (между тегами [CLOSE][/CLOSE]) и удаляющие команды (между тегами [DELETE][/DELETE]). В данном примере закрывающие и удаляющие команды одинаковые. Сюда можно помещать любые команды, которые поддерживаются ssh-консолью Mikrotik. При этом команды проходят предобработку на стороне сервера Биллинга. Обработка команд происходит аналогичным образом, как и обработка команд Manad. Т.е макросы вида {A} заменяются на адрес из выбранных диапазонов для тегов <LOOP>, а макросы {NET} и {NET_MASK} заменяются на выбранные сети для тегов <LOOP_NET> и <LOOP_NET_MASK> соответственно.

Ещё для шлюза Mikrotik производятся дополнительные преобразования: макрос {CID} - преобразуются в код договора, независимо от того, где встретится (внутри цикла LOOP или нет ).

Т.е. например правила:

<LOOP>
ip firewall address-list add address={A} list=ACCESS_LIST comment=!!{CID}!!
</LOOP>

Преобразуется в :

ip firewall address-list add address={192.168.184.10} list=ACCESS_LIST comment=!!12345!!
ip firewall address-list add address={192.168.184.11} list=ACCESS_LIST comment=!!12345!!

если выбраны адреса 192.168.184.10 и 192.168.184.11 и код договора - 12345.

На вкладке Типы правил можете завести (если у вас ещё нет ) - "Пустое правило " и добавить его для данного типа шлюза .

На вкладке Шлюзы создайте новый шлюз типа Mikrotik и установите в нем следующую конфигурацию:

Здесь login - это логин, а ключевое слово - пароль для ssh-соединения Mikrotik.

Также можно указать время ожидания ответа, по истечению которого шлюз сбрасывает соединение и выдаёт ошибку :

timeout=2000

Далее в договоре выбираем модуль IPN, в нем на вкладке Шлюзы добавляем наш новый шлюз и для него указываем наш тип правил test:

Для инициализации правил в системе Mikrotik запускаем следующие команды:

[admin@MikroTik] > ip firewall filter add chain=forward action=accept dst-address-list=ACCESS_LIST
[admin@MikroTik] > ip firewall filter add chain=forward action=accept src-address-list=ACCESS_LIST   
[admin@MikroTik] > ip firewall filter add chain=forward action=drop

В данном примере происходит управление с помощью добавления и удаления ip-адреса в ACCESS_LIST. Все правила добавляются с комментарием "!! код договора !!", чтобы можно было их удалять по этому комментарию. Вы можете менять правила для управления шлюзом Mikrotik произвольным образом (добавлять ширину каналов и т.п.), но есть ограничение: должно быть хотя бы одно правило, добавляющее ip-адрес в address-list, т.к. проверка при синхронизации шлюза ищет с помощью команды "ip firewall address-list print" строку c комментарием "!!код договора!!". Присутствие этой строки означает, что шлюз открыт для данного договора.

12.14. Настройка шлюза Cisco2 c коммутаторами

Данный шлюз предназначен для комплексного управления CISCO и коммутатором Zyxel( ES-2108-G/ES-2024A/GS-3012F и совместимые с ними). На каждого клиента есть возможность выделения отдельного VLAN.

12.14.1. Настройка шлюза Cisco2

Шлюз Cisco является родительским шлюзом для коммутатора . Данный шлюз управляется по telnet.

Создайте тип шлюза со следующей конфигурацией:

user_rule.editor.class=bitel.billing.module.services.ipn.editor.vlan.CiscoVlanContactRuleEditor
gate_manager.class=bitel.billing.server.ipn.vlan.CiscoVlanGateWorker

В командах этого типа шлюза задайте:

[DEFAULT]

[REMOVE]
    no vlan {VID}
    no interface Vlan {VID}
[/REMOVE]

[OPEN]
    vlan {VID}
    interface Vlan {VID}
    no shutdown
    ip unnumbered Loopback1
    ip helper-address 172.17.0.7
    exit
[/OPEN]

[CLOSE]
    interface Vlan {VID}
    shutdown
    exit
[/CLOSE]
[/DEFAULT]

[OPEN][/OPEN] - это команды, которые посылаются на cisco при открытии шлюза. [CLOSE][/CLOSE] - команды, которые посылаются на cisco при закрытии шлюза. [REMOVE][REMOVE] - команды, которые посылаются при удалении шлюза из договора.

Команды проходят предобработку на стороне сервера Биллинга. Обработка команд происходит аналогичным образом , как и обработка команд Manad. Т.е макросы вида {A} заменяются на адрес из выбранных диапазонов для тегов <LOOP>, а макросы {NET} и {NET_MASK} заменяются на выбранные сети для тегов <LOOP_NET> и <LOOP_NET_MASK> соответственно.

Ещё для шлюза Cisco2 производятся дополнительные преобразования: макрос {VID} заменяется на номер VLAN, которой выделен на данный договор и шлюз (как задаётся выделение vlan описано тут ), независимо от того, где встретится (внутри цикла LOOP или нет ).

В типах правил для этого скрипта можете добавить пустое правило.

Создайте шлюз данного типа. В конфигурацию данного шлюза добавьте :

# Пароль шлюза который задаётся для enable 
cfg.pswd=12345
# Диапазон выделения VLAN
range=2-4096
# Время ожидания ответа, по истечению которого шлюз сбрасывает соединение и выдаёт ошибку
timeout=2000

Задайте ip-адрес шлюза, в качестве ключевого слова - забейте пароль к cisco, порт - 23.

Данный шлюз можно использовать автономно и в связке с дочерним коммутатором (в стандартной поставке это zyxel, но его можно подменить любым другим , например DLink, с помощью реализации собственного шлюза на языке beanShell. В договор этот шлюз добавляется только, если он используется автономно (Это важно!!). При редактировании в договоре этот шлюз выглядит так

Логика работы шлюза :

password:xxxxx
xxxx>terminal length 0
xxxx>terminal width 0
xxxxx>enable
password:xxxxx 
xxxx# далее пошли команды управления
xxxx#permit 1.1.1.1
xxxx#no permit 1.1.1.2
....
xxxx#exit

Имеет большое значение настойка и завершаемые символы приглашения. Вначале в конце выводимой cisco информации ожидается ":" ( пользователь вводит пароль, который забит в ключевом слове шлюза) , потом ожидается ">" и шлются 2 команды размеры терминала, посылается команды enable, затем ожидается ":"(пользователь вводит пароль), после этого уже ужидается "#" и посылаются команды управления. Настройки вашей cisco должны соответсвовать этому алгоритму. Если этого сделать не получается (например, вы хотите пропустить процедуру авторизации или у вас иной завершающйй символ приглашения и не хотите его менять), то вы можете использовать аналог этого шлюза на BeanShell из документации Wiki. О том как создавать собственные шлюзы читайте тут.

12.14.2. Настройка шлюза коммутатора Zyxel

Этот шлюз работает только в связке со шлюзом Cisco2, описанным в предыдущей главе . Если вы хотите его запустить автономно, то все равно должен быть родительский шлюз Cisco2, логику которого можно подменить пустым скриптом BeanShell. В текущий момент поддерживаются Zyxel ES 2024A, Zyxel ES 2108G, Zyxel GS 3012F и совместимые с ними.

Для родительского типа шлюза Cisco2 в этом случае надо прописать вот такую конфигурацию :

gate_manager.class=bitel.billing.server.ipn.vlan.CiscoVlanParentGateWorker

Типовая схема - каждый клиент помещается в отдельный VLAN. Клиент может быть подключён к cisco через цепочку управляемых шлюзов, поддерживающих протокол GVRP. VLAN прописывается на шлюзе cisco и на конечном шлюзе, к порту которого подключён абонент. Остальные шлюзы могут получать информацию о VLAN по протоколу GVRP.

Данный шлюз управляется по ssh.

Создайте тип шлюза со следующей конфигурацией:

user_rule.editor.class=bitel.billing.module.services.ipn.editor.vlan.CiscoSSHSwitchRuleEditor
gate_manager.class=bitel.billing.server.ipn.vlan.CiscoSSHSwitchGateWorker

В командах данного типа шлюза пропишите :

[DEFAULT]
[OPEN]
  <LOOP_PORT>
    interface port-channel {PORT}
    pvid {VID} 
    exit 
 </LOOP_PORT>

  vlan  {VID}
  name "abonent  {VID}" 
  normal "" 
  <LOOP_PORT>
    fixed  {PORT}
  </LOOP_PORT>  
  untagged 1-8 
   exit 	
[/OPEN]

[CLOSE]
no vlan  {VID}
[/CLOSE]

[/DEFAULT]

Обработка команд происходит аналогичным образом , как и обработка команд Manad. Т.е макросы вида {A} заменяются на адрес из выбранных диапазонов для тегов <LOOP>, а макросы {NET} и {NET_MASK} заменяются на выбранные сети для тегов <LOOP_NET> и <LOOP_NET_MASK> соответственно.

Ещё для шлюза Zyxel производятся дополнительные преобразования:

1. Макрос {VID} заменяется на номер VLAN, который выделен на данный договор и шлюз (как задаётся выделение VLAN описано тут ) , независимо от того, где встретится (внутри цикла LOOP или нет ).

2. Для каждого тега <LOOP_PORT> вместо макроса {PORT} подставляются порты клиента.

В правилах данного типа шлюза добавляется пустое правило.

Создайте шлюз данного типа как шлюз потомок для Cisco2. В конфигурацию данного шлюза добавьте :

# Логин пользователя
login=admin
# Время ожидания ответа, по истечению которого шлюз сбрасывает соединение и выдаёт ошибку
timeout=20000

Задайте хост и порт (22) шлюза, в качестве ключевого слова забейте пароль.

Добавьте данный шлюз в договор пользователя. Вы увидите следующую картину :

На вкладке Cisco показаны команды, которые будут вызываться на шлюзе Cisco.

На вкладке Switch - команды, которые будут вызываться на коммутаторе.

На вкладке привязка вы можете задавать привязку ip-адресов к портам и mac адресу .

Порты подставляются в команды коммутатора вместо макроса {PORT} . Также эта таблица используется шлюзом DHCP для выдачи ip по mac.

Выбор адресов и сетей влияет на команды (вкладки) Cisco и Switch.

12.14.3. Настройка шлюза DHCP в связке с Cisco2.

О том, как настроить DHCP-сервер/шлюз читайте тут. Если DHCP будет работать в связке со шлюзом Cisco2, то необходимо добавить такие настройки для сервера DHCP. Причём эта схема работает только при наличии коммутатора , т.е должна быть связка 3-х шлюзов : DHCP, Cisco2 и Zyxel.

processor.class=bitel.billing.server.ext.dhcp.DHCPVlanRelayProcessor

# Номер субопции в Option 82, в которой  хранится VLAN клиента (нумерация с 1)
dhcp.82.key.option.code=1
# Позиция (номер байта) внутри субопции, в которой  хранится VLAN клиента (нумерация с 0).
dhcp.82.key.position=2

После синхронизации клиента на коммутаторе Zyxel, будет вызываться синхронизация с родительским шлюзом Cisco2, а потом будет вызываться синхронизация со шлюзом DHCP, который является родительским для Cisco2. Шлюз DHCP, в свою очередь, вызовет синхронизацию клиента на BGDhcpIPN. А именно порт коммутатора: IP-адрес:MAC-адрес.

При подключении клиента, он отправит запрос на получение IP-адреса, коммутатор при включенном и настроенном DHCP Relay, добавив данные RelayAgent Options, перенаправит запрос на DHCP-сервер BGDhcpIPN, который по данным в RelayAgent Options, выдаст IP-адрес. При этом возможны 2 варианта:

1. Выдать ip-адрес по VLAN;

2.Выдать ip-адрес VALN и MAC-адресу клиента, указанному в привязке шлюза;

Для оптимизации работы скомпилированных шлюзов нужно поставить в конфигурацию модуля IPN:

gate.cache.script=1

Это опиция кешерования скомпилированных шлюзов, чтобы они каждыйц раз не компилировались при запуске синхронизаии шлюза.

12.15. Реализация шлюза на языке BeanShell

В версии 4.5 помимо стандартных шлюзов, возможно создание своего собственного шлюза с помощью встроенного языка BeanShell.

В этом случае в конфигурации типов шлюзов вы можете указывать например :

user_rule.editor.class=bitel.billing.module.services.ipn.editor.ManadContractRuleEditor
gate_manager.class=bitel.billing.server.ipn.ManadGateWorker
use.script=1

Здесь user_rule.editor.class - это класс, который отображает редактор шлюза в клиенте биллинга и сохраняет данные шлюза .Вы можете поставить один из стандартных классов (указаны в документации в соответствующих главах), либо поставить user_rule.editor.class.EmptyContractRuleEditor, если редактировать шлюз не нужно в договоре. gate_manager.class - это класс, осуществляющий взаимодействие со шлюзом на стороне сервера биллинга. Именно логику этого класса мы и подменяем своим скриптовым шлюзом. Вы можете указать user_rule.editor.class=bitel.billing.server.ipn.EmptyGateWorker. Но если вы подменяете логику работы одного из стандартных шлюзов, то желательно указывать класс этого шлюза, т.к. логика его работы будет подменена, но есть ещё другие правила, например, в случае сложных иерархических шлюзов производится синхронизация с родительским шлюзом и она пока не может быть реализована скриптовым шлюзом. use.script=1 — это параметр, задающий, что вместо стандартной логики шлюза будет выполняться скрипт

Сам код шлюза заносится на вкладку "Скрипт" при редактировании типа шлюза:

Должна быть обязательно реализована функция doSync() - именно она и отвечает за взаимодействие со шлюзом. Вот минимальный код шлюза:

protected void doSync()
{
 
}

Также дополнительно может быть определена дополнительная функция синхронизации со шлюзом предком. Она определяется у шлюза предка и вызывается потомком перед вызовом doSync().

protected void parentSync( Gate child, GateWorker childWorker)
{
}

где child - объект типа bitel.billing.server.ipn.bean.Gate, представляющий шлюз, который вызывал этот метод.

childWorker - объект типа bitel.billing.server.ipn.GateWorker, представляющий шлюз, который вызывал этот метод.

В скрипт передаются такие переменные:

con — объект java.sql.Connection для соединения с БД;

gate — объект bitel.billing.server.ipn.bean.Gate;

ruleTypeMap — объект java.util.Map<Integer, bitel.billing.server.ipn.bean.RuleType>. В нем содержаться все типы правил из БД. Ключ — id правила;

gateTypeMap — объект java.util.Map<Integer, bitel.billing.server.ipn.bean.GateType> gateTypeMap. В нем содержаться все типы шлюзов из БД. Ключ — id типа шлюза;

Log — объект org.apache.log4j.Logger. Для вывода сообщений, ошибок шлюза;

StatusList — объект List<bitel.billing.server.ipn.UserStatus> statusList. В нем содержаться статусы пользователей, которые синхронизируются на данном шлюзе. Ключ — id статуса. ;

GateErrors — объект java.lang.StringBuilder, содержащий ошибки выполнения шлюза;

mid — int, код модуля;

worker - объект типа GateWorker, обработчтик логики работы со шлюзом, который вызвал этот скрипт.

Примеры шлюзов и реализация большинства стандартных шлюзов есть на WiKi.

13. Отчёты модуля, детализация

Модуль предоставляет единственный отчёт по трафику. При выборе года отображается отчёт по месяцам, при выборе года и месяца - по дням месяца. При выборе дня месяца - по часам.

Возможно задание режима отображения: байты, Кб, Мб, Гб. На вкладке Печать доступна печатная форма отчёта. В фильтре по адресам существует возможность выбрать интересующие диапазоны для вывода их трафика в отчёта. Для выбора доступны только те адреса, период которых пересекается с выбранным периодом просмотра. При неустановленном фильтре по адресам отображается отчёт по всем адресам договора. Для вывода отчёта нажмите на кнопку Вывести.

Для получения детализации по трафику используется область под отчётом Запросить детализацию.

13.1. Детализация трафика за час

Для получения отчёта введите в область под отчётом на вкладке За час диапазон адресов, дату, час и E-Mail для высылки отчёта. Задание на детализацию исполняет BGIPNNetFlowCollector. Выбирая детализацию из бинарных файлов, он отправляет письмо с отчётом по указанному адресу.

Стандартная детализация за час представляет из себя одно или несколько писем с приложенным архивом detail.zip. Архив содержит CSV-файл с частью детализации. Размер максимального возможного detail.zip в одном письме задается переменной ipn.collector.detail.max.attach.size в файле netflow_ipn.properties. По умолчанию значение переменной составляет 4000000 байт. Каждое письмо сопровождается темой IPN traffic detail [N], где N - увеличивающийся порядковый номер. Последнее письмо данной детализации снабжено темой IPN traffic detail [LAST] и содержит простейшую аналитику на какие и с каких адресов был максимальный трафик.

Можно заменить стандартную детализацию, для этого необходимо указать в netflow_ipn.properties

ipn.collector.detail.class=bitel.billing.server.netflow.ipn.detail.AnalyzedFlowDetailMaker

Данный класс создания детализации кроме стандартного csv добавляет в архив detail.zip html файл с графиком и анализом.

Детализация в этом случае будет приходить одним письмом, разбиения в данный момент не предусмотрено.

13.2. Детализация трафика за период

Детализация за период сохраняется в файл. Выберите диапазон адресов, период и имя файла. Каталог, куда будет выкладываться детализация на сервере прописывается в настройках коллектора в файле netflow_ipn.properties. Названия каталогов на разных коллекторах могут отличаться, но все коллекторы должны ссылаться на один каталог.

ipn.collector.detail.folder=/home/billing/detail

14. Web-интерфейс модуля

В меню IP-статистика (IPN) пользователь имеет возможность просмотра отчёта по трафику. Возможен просмотр отчёта за день, месяц и год, по одному или всем диапазонам адресов клиентов.

Для запроса детализации по трафику необходимо выбрать дневной режим просмотра, затем выбрать интересующий час, адрес и ввести E-Mail, на который будет отправлена детализация. Через Web-интерфейс возможен заказ только детализации за час.

В меню Управление шлюзом (IPN) пользователь может временно закрыть свой шлюз, либо посмотреть текущее состояние, если он заблокирован.

В меню Управление правилами шлюзов(IPN) пользоватиель может менять типы правил на своих шлюзах.

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

customer.control=1

Глава 19. Модуль MOBI.Деньги

1. Назначение модуля

Платежный модуль MOBI.Деньги предназначен для проведения платежей посредством мобильного телефона с использованием сервиса мобильных платежей MOBI.Деньги.

2. Настройка модуля

Установите модуль на сервер, обновите клиент. Затем создайте экземпляр модуля. Создайте в редакторе конфигурации модуля новую конфигурацию.

# Название пункта меню в Web-кабинете
web.menuItem1=Оплата через MOBI.Деньги
# Комментарий платежа
mobi.payment.comment=Оплата с помощью сервиса MOBI.Деньги
# Код платежа из справочника "Типы платежей"
mobi.payment.type=
# Идентификатор провайдера в системе MOBI.Деньги
mobi.provider.id=
# Режим работы (demo|work) 
mobi.mode=demo

Замечания:

  1. Прежде, чем задавать mobi.payment.type, необходимо создать соответствующий тип платежа в Справочнике ( Справочники->Другие->Типы платежей);

  2. Для работы модуля необходимо передать адрес Web-сервиса на стороне биллинга, который будет осуществлять авторизацию и проведение платежа. URL выглядит следующим образом:

    http(s)://<адрес_машины_биллинга>/bgbilling/mobiexecuter/ru.bitel.bgbilling.modules.mobimoney/<mid>/MobiMoneyWS

    где

    • <адрес_машины_биллинга> - адрес сервера, на котором установлен биллинг;

    • <mid> - код модуля mobi (можно посмотреть в редакторе модулей и услуг).

    Например, если у вас биллинг находится по адресу http://billing.example.com/bgbilling/ и модуль Mobi имеет mid=16, то результирующий URL, который нужно передать в сервис MOBI.Деньги, выглядит следующим образом: http(s)://billing.example.com/bgbilling/mobiexecuter/ru.bitel.bgbilling.modules.mobimoney/16/MobiMoneyWS.

  3. Для работы с системой Mobi необходимо установить сертификаты для этого необходимо сгенерировать запрос на подпись сертификата и отправить его в MOBI (процедура генерации описана на сайте mobi ).

    Полученный от MOBI файл с подписанным сертификатом cert.crt скопируйте в каталог сервера биллинга cert/mobimoney/ (если каталогов не существует, создайте их вручную), туда же скопируйте файл с закрытым ключом cert.key и корневой сертификат от MobiMoney (ca.crt, файл нужно загрузить с сайта MobiMoney).

    Если биллинг работает в связки в nginx, то файлы с ключом и сертификаты необходимо подключить к nginx (как это сделать смотрите в документации к nginx)

    Настройте биллинг на работу по HTTPS протоколу. Как это сделать описано здесь.

3. Проведение платежей

Платежи осуществляются абонентом через личный кабинет Web-статистики путем выбора соответствующего пункта меню.

4. Мониторинг платежей

Существует глобальный монитор всех платежей в системе. Он вызывается с помощью меню Модули=>Модуль MOBI.Деньги. Здесь можно отфильтровать платежи по дате, статусу, номеру договора.

Также в системе есть локальный монитор платежей для каждого договора. Посмотреть платежи договора можно на вкладке модуля MOBI.Деньги в дереве договора. Здесь также доступен фильтр по дате платежа, статусу.

Глава 20. Модуль MPS

1. Назначение модуля

Модуль предназначен для интеграции с платёжными системами. В настоящее время поддерживается приём платежей из систем CyberPlat(cp), ОСМП(osmp), XPlat(xplat), E-port(eport), Empay(empay), Rapida(rapida), Pegas(pegas), Comepay(comepay), Юникасса(unikassa), Quickpay(quickpay), Сбербанк(sbrf).

2. Настройка модуля

Создайте нередактируемые типы платежей для систем платежей. id типов платежей можно узнать также в справочнике, выделив нужный тип платежа и нажав Ctrl+i. id нужно будет указать в конфигурации.

Проинсталируйте модуль на сервер, обновите клиент биллинга. Затем создайте экземпляр модуля. Cоздайте в редакторе конфигурации модуля новую конфигурацию по нижеприведённому примеру и сделайте ее активной.

Для всех систем платежей рекомендуется использовать только https-порт.

Здесь и далее "пс" - платёжная система.

Возможные параметры конфигурации модуля:

# Системы платежей добавляются как mps.<mpsId>.параметры, где <mpsId> - порядковый номер
# Вкл/выкл - 1/0 - принимать или нет платежи для этой пс
mps.<mpsId>.mode=1
# Название
mps.<mpsId>.title=CyberPlat
# Используемый протокол для общения пс с биллингом
mps.<mpsId>.protocol=cp
# Логин/пароль пс. Должен различаться для различных систем
mps.<mpsId>.login=
mps.<mpsId>.passw=
# id типа платежа, с которым добавляется платёж в договор, при проведении с этой пс
mps.<mpsId>.pid=
#
# Комментарий, возвращающийся в ответе на проверку статуса/проведение платежа
# (если в протоколе есть комментарий ответа)
#mps.comment=$CONTRACT ($COMMENT)
#
# Сертификаты
# Проверять клиентский сертификат (рекомендуется, если позволяет протокол пс)
mps.<mpsId>.cert=1
# Клиентский сертификат (открытый ключ)
# (для протокола eport открытый ключ указывается здесь же, а mps.1.cert=0)
# возможно указать через modulus и exponent:
#mps.<mpsId>.cert.mod=
#mps.<mpsId>.cert.exp=
# или в encoded(байты в 16-ричном представлении)
#mps.<mpsId>.cert.encoded=
# или в pem (base64), без header/footer (-----*** PUBLIC KEY-----) и переносов строк
mps.<mpsId>.cert.pem=
#
# Поиск договора для проведения платежа.
# В некоторых системах возможны типы поиска - дополнительное поле.
# Если их больше 1, то с дополнительным индексом. Если он отсутствует, используется тип поиска 0, 
# т.е. используются параметры поиска из mps.1.search.xxx (для mps.1.search.mode).
# Если присутствует то, например, параметры поиска будут из mps.1.search.1.xxx (для mps.1.search.1.mode)
# Обратите внимание, что если если задано без индекса (...search.mode=), то и остальные параметры должны
# соответствовать (...search.pattern=) и для остальных индексов аналогично.
#
# Поддержка передачи типа поиска через префикс
# (т.е. если ищется договор x0000 c типом поиска 1, то в поле account протокола osmp передаётся 1_x0000)
#mps.<mpsId>.protocol.ext=osmpPrefix
# Отключение Base-аутентификации
#mps.<mpsId>.protocol.ext=noBaseAuth
# Если используется несколько расширений, их нужно прописать через запятую:
#mps.<mpsId>.protocol.ext=noBaseAuth, osmpPrefix
#
# Тип поиска (mps_login|contract|login|voice|email|phone|parameter|inet_login|custom) 
mps.<mpsId>.search.mode=
# Код модуля для поиска (необходим для типов поиска login, phone)
#mps.<mpsId>.search.mid=
# Включение "множественного поиска", то есть проверка всего списка regex
#mps.1.search.multi=1
# Шаблон преобразования - pattern:::result, если пришедшее значение подходит под regexp, то 
# оно преобразуется перед поиском, если нет - остаётся без изменений, по умолчанию - без изменений.
# Например, \A((?:\d{5})|(?:\d{6})|(?:\d{7}))(\d{2})\z:::NK$1-$2
# если пришедший номер для поиска представляет собой 12345608, то он будет преобразован в NK123456-08,
# и уже по нему будет произведён поиск договора
#mps.<mpsId>.search.pattern=
# regexp названий договоров, для которых возможен поиск. Если название договора не совпадает с regexp, 
# то он не будет найден для системы платежей для этого типа поиска
# пользовательский класс для поиска, должен реализовывать интерфейс ru.bitel.bgbilling.modules.mps.server.bean.FindContract
#mps.<mpsId>.search.custom=
#mps.<mpsId>.search.allow.contract.regexp=NK-.*
# Группы договоров, для которых возможен поиск для этого типа поиска
#mps.<mpsId>.search.allow.contract.groups=4,2,5,3
#
# Ограничения на пополняемую сумму
# минимальная. По умолчанию - 0.
mps.<mpsId>.min.summ=
# максимальная. По умолчанию - 1000000
mps.<mpsId>.max.summ=
#
# Разница во времени в минутах между сервером биллинга и системой платежей (например система работает по московскому времени, биллинг
# по уфимскому +2 часа - 180)
#mps.<mpsId>.timeoffset=
# промежуток времени между временем платежа и реальным временем, с поправкой на timeoffset. 
# если задано и промежуток оказался больше то платёж не пройдёт
#mps.<mpsId>.paytime=
#
# Параметры логина mps (может использоваться для поиска договора при проведении платежа)
# Формат вывода значения числового логина mps (на web-статистике)
#mps.mps_login.format=
# regexp проверки введённого значения
#mps.mps_login.regexp=
# Ошибка, выводимая в web-статистике при несовпадении введённого логина mps с regexp
#mps.mps_login.regexp.error=

В поле mps.1.protocol.ext можно указать расширения, если их несколько - через запятую:

osmpPrefix - означает, что тип поиска может быть передан как префикс в поле account. Расширение работает для протоколов ОСМП, Empay, Pegas, Rapida, Comepay.

noBaseAuth - означает, что в запросе не проверяется Base-аутентификация, т.е. параметры конфига mps.1.login и mps.1.passw не нужны.

payOnCheck - означает, что платеж проводится сразу при запросе на проверку.

addBalanceInfo - в ответ добавляется текущий баланс в поле account_balance (ОСМП, Empay, Pegas, Rapida, Comepay).

URL для систем платежей формируется из шаблона https://сервер/контекст/mpsexecuter/<mid>/<mpsid>, где <mid> - id модуля, <mpsid> - код системы платежей, т.е для вышеописанной конфигурации у CyberPlat mpsid=1.

Например, https://server:8443/bgbilling/mpsexecuter/10/1

Типы поиска :

- login - поиск по логину модулей DialUp или Voip (необходимо указать id модуля (mid)):

mps.1.search.mode=login

mps.1.search.mid=3

- contract - поиск по названию договора (например NK-0012; Здесь можно указать шаблон преобразования):

mps.1.search.mode=contract

mps.1.search.pattern=NK-$NUMBER - для поиска клиенту нужно будет ввести только 0012

или

mps.1.search.pattern=\A((?:\d\d\d\d\d\d)|(?:\d\d\d\d\d\d\d)|(?:\d\d\d\d\d))(\d\d)\z:::КФ$1-$2

(в последнем случае, если пришли 7, 8 или 9 цифр преобразовываем их к виду КФ$1-$2, т.е значения КФ12345-12 и 12345612 будут эквивалентны)

- phone - поиск по номеру телефона модуля phone (необходимо указать id модуля (mid));

- parameter - поиск по параметру договора (необходимо указать код типа параметра (pid)):

mps.1.search.mode=parameter

mps.1.search.pid=9

- mps_login - логин модуля MPS. Его выбирает себе клиент на странице статистики. Один для всех систем платежей.

Для протоколов, не поддерживающих передачу типа поиска, реализована передача типа поиска через префикс x_идентификаторклиента (например, для ОСМП в поле account для поиска по search.1 логина 13 в запросе должно приходить: account=1_13). Для поддержки этого режима нужно установить mps.x.protocol.ext=1.

В комментарии ответа (если такой поддерживатся протоколом) можно передать номер, комментарий, параметр и/или баланс договора

mps.1.comment=$contract_title ($contract_comment) [$contract_param(4)] $contract_balance

2.1. ОСМП, Empay, Pegas, Rapida, Comepay

В протоколе ОСМП (Empay, Pegas, Rapida, Comepay) по умолчанию отсутствует параметр типа поиска, которым можно было бы разделить разные типы платежей. Однако его можно передавать в запросе дополнительным полем pay_type или же вложить префиксом в поле account, например 1_x0000, где

1 - это тип поиска, x0000 - это значение, по которому происходит поиск.

Параметр mps.x.numberPattern - регулярное выражение, которому должно удовлетворять значение поля account, иначе модуль возвращает ошибку 4 (не соответствие формата идентификатора абонента).

Аутентификация происходит по логину/паролю через BASE-AUTH протокола http и, если указана, по клиентскому сертификату, переданному при взаимодействии через протокол https.

В зависимости от типа протокола, необходимо указать соответствующий в конфигурации:

#ОСМП
mps.<mpsId>.protocol=osmp
#Empay
mps.<mpsId>.protocol=empay
#Pegas
mps.<mpsId>.protocol=pegas
#Rapida
mps.<mpsId>.protocol=rapida
#Comepay
mps.<mpsId>.protocol=comepay

Пример конфигурации:

mps.<mpsId>.mode=1
mps.<mpsId>.title=ОСМП
mps.<mpsId>.protocol=osmp
#Поддержка передачи типа поиска через префикс
mps.<mpsId>.protocol.ext=1
mps.<mpsId>.login=
mps.<mpsId>.passw=
mps.<mpsId>.pid=
#Тип поиска 0 (по умолчанию)
mps.<mpsId>.search.mode=contract
#Тип поиска 1 (1_12345608)
mps.<mpsId>.search.1.mode=contract 
#Шаблон преобразования перед поиском - pattern:::result
mps.1.search.1.pattern=\A((?:\d{5})|(?:\d{6})|(?:\d{7}))(\d{2})\z:::NK$1-$2
#Будут находиться только договора входящие в группу с id=12
mps.1.search.1.allow.contract.groups=12
#Регулярное выражение проверки значения поля account
mps.1.numberPattern=\A\d{7,9}\z
#
mps.1.cert=1
mps.1.cert.pem=3bab58c...
# Ограничения на пополняемую сумму
# минимальная. По умолчанию - 0.
mps.1.min.summ=0
# максимальная. По умолчанию - 1000000
mps.1.max.summ=15000

2.2. CyberPlat

Типы поиска встроены в протокол.

Аутентификация происходит по логину/паролю через BASE-AUTH протокола http и, если указана, по клиентскому сертификату, переданному при взаимодействии через протокол https.

Для получения клиентского сертификата CyberPlat посылает Certificate Signing Request, при его подписи будет создан сертификат с данными и открытым ключом CyberPlat, подписанный серверным сертификатом. Сертификат следует генерировать версии 1 (V1).

Пример конфигурации:

mps.<mpsId>.mode=1
mps.<mpsId>.title=КиберПлат
mps.<mpsId>.protocol=cp
mps.<mpsId>.login=
mps.<mpsId>.passw=
mps.<mpsId>.pid=
#Тип поиска 0 (по умолчанию)
mps.<mpsId>.search.mode=contract
#Тип поиска 1 (1_12345608)
mps.<mpsId>.search.1.mode=contract 
#Шаблон преобразования перед поиском - pattern:::result
mps.<mpsId>.search.1.pattern=\A((?:\d{5})|(?:\d{6})|(?:\d{7}))(\d{2})\z:::NK$1-$2
mps.<mpsId>.search.2.mode=login
mps.<mpsId>.search.2.mid=5
mps.<mpsId>.search.3.mode=login
mps.<mpsId>.search.4.mid=8
#
mps.<mpsId>.cert=1
mps.<mpsId>.cert.pem=3bab58c...

2.3. XPlat

Для XPlat необходимо назначить дополнительный параметр запроса account, в котором передаётся номер договора, логин или номер телефона, а также можно добавить необязательный параметр type, в котором будет передаваться тип поиска (аналогично CyberPlat). В случае, если используется параметр type, то при формировании md5 системой XPlat параметры должны идти в порядке: account, type.

Аутентификация происходит по подписи. Проверку сертификата следует отключить (mps.<x>.cert=0).

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

Пример конфигурации:

mps.<mpsId>.mode=1
mps.<mpsId>.title=XPlat
mps.<mpsId>.protocol=xplat
mps.<mpsId>.pid=
mps.<mpsId>.search.mode=contract
mps.<mpsId>.search.mid=
#512 символьный секрет xplat
mps.<mpsId>.secret=
#Секрет для вычисления md5 при ответе
mps.<mpsId>.secret.response=

2.4. Eport

Аутентификация EPort происходит по подписи закрытого ключа. Открытый ключ eport необходимо указать в mps.<x>.cert. Им будет производиться проверка запросов. Сервер подписывает ответы своим закрытым ключом, поэтому необходимо передать открытый ключ (сертификат с открытым ключом) пс.

mps.<mpsId>.mode=1
mps.<mpsId>.title=E-port
mps.<mpsId>.protocol=eport
#Поддержка передачи типа поиска (search.x) через префикс
#mps.<mpsId>.protocol.ext=0
mps.<mpsId>.pid=
mps.<mpsId>.search.mode=
mps.<mpsId>.cert=1
#Клиентский сертификат для проверки подписи
mps.<mpsId>.cert.pem=

2.5. SFOUR PayBox Alternative

Аутентификация запросов/ответов происходит по подписи, основанной на секретном слове.

Также как и в других системах рекомендуется использование транспорта https.

Для передачи номера договора/логина/номера телефона в запросе на проведение платежа необходимо назначить в системе дополнительное поле AccountNumber. Также возможно назначить поле AccountType, в котором будет передаваться тип поиска.

При ответе на проверку, если договор найден, в ответе идёт поле AccountComment, в котором содержится комментарий (см. опцию mps.comment в конфигурации). Подпись ответа сервера: SHA-1(<SessionID>, <ErrorCode>, <ClearingNumber>, <AccountNumber>, <MachineSecret>)

При запросе на проведение платежа сумма должна быть передана в параметре Amount.

Поле AccountComment должно быть возвращено в запросе на проведение платежа, подпись при этом: SHA-1(<SessionID>, <MachineMark>, <ClearingNumber>, <AccountNumber>, <AccountComment>, <Amount>, <MachineSecret>)

URL типов запросов различаются, т.е, например, запрос на проверку

https://server:8443/bgbilling/mpsexecuter/10/1/Check

проведение платежа - https://server:8443/bgbilling/mpsexecuter/10/1/Pay

статус - https://server:8443/bgbilling/mpsexecuter/10/1/Status

Здесь 10 - это код модуля, 1 - код системы платежей (аналогично с другими типами систем).

mps.<mpsId>.mode=1 
mps.<mpsId>.title=SFour
mps.<mpsId>.protocol=sfoura
mps.<mpsId>.pid=
mps.<mpsId>.search.mode=
#Секрет для составления и проверки подписи
mps.<mpsId>.secret=

2.6. ОПТИМА plus

Аутентификация происходит по подписи закрытого ключа. Открытый ключ ПС необходимо указать в mps.<x>.pem. Им будет производиться проверка запросов. Сервер подписывает ответы своим закрытым ключом, поэтому необходимо передать открытый ключ (сертификат с открытым ключом) пс.

mps.<mpsId>.mode=1
mps.<mpsId>.title=OptimaPlus
mps.<mpsId>.protocol=optimaplus
mps.<mpsId>.pid=
mps.<mpsId>.search.mode=
mps.<mpsId>.cert=1
#Клиентский сертификат для проверки подписи без header/footer (-----*** PUBLIC KEY-----) 
mps.<mpsId>.cert.pem=

2.7. Elecsnet

Аутентификация происходит по ЭЦП закрытого ключа. Открытый ключ ПС необходимо указать в mps.<x>.pem. Этим ключом будет производиться проверка запросов с сервера ПС. Сервер биллинга подписывает ответы своим закрытым ключом, поэтому необходимо передать свой открытый ключ ПС. В ответном запросе серверу ПС можно указать параметры поля протокола ansid для вывода их на терминале клиенту.

#1-работает платежная система
#0-не работает платежная система
mps.<mpsId>.mode=1
mps.<mpsId>.title=Elecsnet
mps.<mpsId>.protocol=elecsnet
#Номер платежа из справочника типы платежей
mps.<mpsId>.pid=<pid>
mps.<mpsId>.cert=0
mps.<mpsId>.cert.pem=
# Поиск договора. конкретно здесь описан пример с поиском по параметру договора. Также доступны остальные виды поиска договоров
mps.<mpsId>.search.mode=parameter
# Номер параметра договора
mps.<mpsId>.search.pid=<pid>
# Разница во времени в минутах между сервером биллинга и системой платежей (например система работает по московскому времени, биллинг
# по уфимскому +2 часа - 180)
mps.<mpsId>.timeoffset=180
# Промежуток времени между временем платежа и реальным временем, с поправкой на timeoffset. 
# Если задано и промежуток оказался больше, то платёж не пройдёт
mps.<mpsId>.paytime=1440
# Далее идут необязательные параметры, значения которых могут включаться или нет в ответ серверу ПС.
# Эти параметры собираются воедино и указываются в поле ansid  при ответе серверу elecsnet.
# Параметры могут указываться частично.
# Параметр summ - этот параметр описан в протоколе elecsnet
mps.<mpsId>.response.attribute.summ=@sumin@3000
# Параметр фио. Чтобы клиент понял, что он себе деньги закидывает. Могут быть либо $title, либо $comment, либо $pid=32, где 32 - это id параметра.
mps.<mpsId>.response.attribute.fio=$title
# regexp для предыдущего парамтера фио, который позволяет из фио Иванов Иван Ивановчи сделать, к примеру, И.И.И. 
# Записывать регексп так: что заменять:::на что заменять.
mps.<mpsId>.response.attribute.fio_regexp=[а-я]+:::\.
# Дополнительный комментарий для инициалов И.И.И.
mps.<mpsId>.response.attribute.comment=комментарий

2.8. Юникасса

Аутентификация производится по логину/паролю. Используются SSL динамические ключи, не требующие подтверждения в центрах сертификации.

Запросы от сервера Ekassir приходят с IP-адресов: 195.96.80.186, 195.96.80.187, 195.96.80.188 и 195.96.80.182 и 2-х сетей: 195.239.136.160/27 и 217.148.219.32/28. Не забудьте добавить их в список исключений, если вы собираетесь фильтровать входящий трафик.

mps.<mpsId>.mode=1
mps.<mpsId>.title=Unikassa
mps.<mpsId>.protocol=unikassa
mps.<mpsId>.pid=
mps.<mpsId>.search.mode=
mps.<mpsId>.cert=0
mps.<mpsId>.login=
mps.<mpsId>.passw=

Используется один тип поиска (с индексом 0), т.к. заявляется, что в сторонней системе менять соответствующий параметр (sid) нельзя, потому его значение в данный момент игнорируется.

2.9. Quickpay

Аутентификация производится сертификату.

#1-работает платежная система
#0-не работает платежная система
mps.<mpsId>.mode=1
mps.<mpsId>.title=Quickpay
mps.<mpsId>.protocol=quickpay
mps.<mpsId>.secret=<secret>
# код типа платежей из справочника 
mps.<mpsId>.pid=<payment_id>
mps.<mpsId>.search.mode=login
mps.<mpsId>.search.mid=<module_id>
mps.<mpsId>.search.1.mode=contract
#mps.<mpsId>.search.1.mid=<module_id>
mps.<mpsId>.cert=
mps.<mpsId>.cert.pem=
mps.<mpsId>.protocol.ext=noBaseAuth

2.10. Sberbank

Аутентификация производится по сертификату.

#Включение (1) / Выключение (0) протокола
mps.<mpsId>.mode=1
#Название для протокола
mps.<mpsId>.title=Сбербанк
mps.<mpsId>.protocol=sberbank
mps.<mpsId>.protocol.ext=noBaseAuth
# Разблокировать в случае необходимости Base-авторизации. 
# Также нужно будет убрать расширение noBaseAuth для протокола
#mps.<mpsId>.login=sber 
#mps.<mpsId>.passw=rgnko7fh
# Настройка сертификата
mps.<mpsId>.cert=0
mps.<mpsId>.cert.pem=sdfDdfs1.....
# Код типа платежа из справочника типов платежей
mps.<mpsId>.pid=<payment_type_id>
# Режим поиска договова - по его номеру
mps.<mpsId>.search.mode=contract
# Минимальная и максимальная сумма для пополнения
mps.<mpsId>.min.summ=100
mps.<mpsId>.max.summ=15000
# Если указано это поле, то в ответе сбербанку добавится доп. поле add, куда пропишется адрес абонента.
# <address_param_id> - код параметра типа адрес из справочника параметров договора
#mps.<mpsId>.comment=$contract_param(<address_param_id>)

Адрес для приема реестров платежей: http(s)://<bgbilling_url>/mpsexecuter/<mid>/<mpsId>/register

2.11. Сбербанк (sbrf)

Аутентификация производится по сертификату.

#Вкл/выкл - 1/0 - принимать или нет платежи для этой пс
mps.<mpsId>.mode=1
mps.<mpsId>.title=Сбербанк
mps.<mpsId>.protocol=sbrf
mps.<mpsId>.protocol.ext=noBaseAuth
#mps.<mpsId>.login=sber //разблокировать в случае необходимости Base-авторизации
#mps.<mpsId>.passw=
mps.<mpsId>.cert=
mps.<mpsId>.cert.pem=
mps.<mpsId>.pid=
mps.<mpsId>.search.mode=contract
mps.<mpsId>.min.summ=10
mps.<mpsId>.param.keys=fio,address
mps.<mpsId>.fio=<textParamId1>[,<textParamId2>[,<textParamId3>...]]
mps.<mpsId>.address=<addressParamId1>[,<addressParamId2>[,<addressParamId3>...]]

2.12. Bisys

Протокол для платежного сервиса от компании ООО "Биллинговые системы". Аутентификация в данном протоколе осуществляется по подписи запросов с помощью секрета. Настройки протокола:

mps.<mpsId>.mode=1
mps.<mpsId>.title=Билинговые Системы
mps.<mpsId>.protocol=bisys
mps.<mpsId>.secret=<secret>
# код типа платежей из справочника 
mps.<mpsId>.pid=<payment_id>
mps.<mpsId>.search.mode=login
mps.<mpsId>.search.mid=<dialup_module_id>
mps.<mpsId>.comment=[$contract_title] [$contract_comment] [$contract_param(4)]
mps.<mpsId>.protocol.ext=noBaseAuth, needClientInfo

Расширение needClientInfo позволяет опционально добавлять информацию о клиенте (ФИО) в ответ на запрос платежной системы о возможности совершения платежа. Содержимое информации о клиенте определяется параметром конфигурации mps.<mpsId>.comment.

3. Сертификаты

ОСМП, Empay, Pegas, Rapida, Comepay, CyberPlat используют метод аутентификации по сертификатам. Для работы необходим серверный сертификат и использование https.

Необходимо экспортировать серверный сертификат, чтобы удаленная сторона могла добавить его в доверенные:

keytool -keystore .keystore -alias bgbilling -exportcert -file bgbilling.cer

Сконвертировать сертификат в x509 base64 можно командой:

openssl x509 -inform der -in bgbilling.cer -out bgbilling.pem

Работа с клиентским сертификатом может пройти несколькими вариантами:

1. Платежная система присылает сертификат, который нужно добавить в доверенные:

keytool -keystore .keystore -alias pegas -importcert -file pegas.cer

2. Подпись запроса на сертификат или создание подписанного сертификата:

Сначала создаем главный сертификат для модуля, им будут подписаны клиентские сертификаты, а сам он будет добавлен в доверенные сертификаты в .keystore.

Генерируем ключ, который будет зашифрован паролем:

[amir@ts01 keys]$ openssl genrsa -des3 -out mps.key 1024
Generating RSA private key, 1024 bit long modulus
e is 65537 (0x10001)
Enter pass phrase for mps.key:
Verifying - Enter pass phrase for mps.key:

Создаем на основе ключа сертификат, здесь понадобится ввести описание сертификата, точка ('.') означает пустое поле:

[amir@ts01 keys]$ openssl req -new -x509 -days 1001 -key mps.key -out mps.pem
Enter pass phrase for mps.key:
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [GB]:RU
State or Province Name (full name) [Berkshire]:.
Locality Name (eg, city) [Newbury]:.
Organization Name (eg, company) [My Company Ltd]:Provider
Organizational Unit Name (eg, section) []:Provider BGBilling MPS
Common Name (eg, your name or your server's hostname) []:Provider BGBilling MPS
Email Address []:support@provider.ru

Добавляем сертификат в доверенные:

keytool -keystore .keystore -alias mps -importcert -file mps.pem

2.1 Если нам нужно самим создать сертификат:

Генерируем ключ, osmp.key - в данном случае имя файла, здесь уже нужно использовать другой пароль, потому что его необходимо будет также переслать удаленной стороне:

[amir@ts01 keys]$ openssl genrsa -des3 -out osmp.key 1024
Generating RSA private key, 1024 bit long modulus
e is 65537 (0x10001)
Enter pass phrase for osmp.key:
Verifying - Enter pass phrase for osmp.key:

И создаем запрос на подпись:

[amir@ts01 keys]$ openssl req -new -key osmp.key -out osmp.csr
Enter pass phrase for osmp.key:
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [GB]:RU
State or Province Name (full name) [Berkshire]:.
Locality Name (eg, city) [Newbury]:.
Organization Name (eg, company) [My Company Ltd]:OSMP
Organizational Unit Name (eg, section) []:OSMP-BGBilling
Common Name (eg, your name or your server's hostname) []:www.osmp.ru
Email Address []:support@osmp.ru

Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:

2.2 Если нам прислали CSR-запрос на подпись или мы только что сами создали новый, создаем подписанный сертификат из запроса:

[amir@ts01 keys]$ openssl x509 -req -in osmp.csr -CA mps.pem -CAkey mps.key -out osmp.pem -days 1001 -CAcreateserial -CAserial mps.seq
Signature ok
subject=/C=RU/O=OSMP/OU=OSMP-BGBilling/CN=www.osmp.ru/emailAddress=support@osmp.ru
Getting CA Private Key
Enter pass phrase for mps.key:

Если к нам приходил только CSR-запрос, то нужно послать только osmp.pem.

Если мы сами генерировали клиентский закрытый ключ, то необходимо передать как osmp.pem, так и osmp.key, т.е. сертификат и приватный ключ.

Связку закрытый ключ и сертификат можно сконвертировать в PKCS12 формат.

[amir@ts01 keys]$ openssl pkcs12 -export -in osmp.pem -inkey osmp.key -out osmp.p12

Сначала необходимо будет ввести пароль на закрытый ключ, который указали при генерации osmp.key, затем два раза - новый (можно тот же самый) уже для нового PKCS файла.

Открытый ключ добавленного в доверенные/созданного/подписанного клиентского сертификата необходимо указать в конфиге. Для этого необходимо скопировать содержание открытого ключа одной строкой, без заголовка и окончания '-----BEGIN PUBLIC KEY-----'/'-----END PUBLIC KEY-----'

Например:

mps.1.cert.pem=MIGfMA0GCSqGSIb3DQE.....EmO5Phqo2FG52KwIDAQAB

Извлечь открытый ключ из сертификата можно так:

[amir@ts01 keys]$ openssl x509 -inform der -in osmp.cer -pubkey
#или
[amir@ts01 keys]$ openssl x509 -inform pem -in osmp.pem -pubkey

4. Менеджер платежей

Позволяет просматривать платежи за период.

Внизу показываются количество платежей и сумма только с учётом проведённых платежей

5. Сверка платежей

Позволяет сверить реестр системы платежей с данными сервера биллинга и при необходимости добавить, отменить или восстановить платежи. Не все протоколы поддерживают сверку. Если Вы загружаете файл реестра, но все платежи попадают в лишние - это может означать, что файл реестра парсится неверно. По умолчанию парсинг реестра включен в поддержку протокола модуля.

Для изменения параметров парсинга реестра можно задать параметры в конфигурации платежной системы:

#regexp записи
mps.1.register.pattern=^(.+)[;\t](\d+)[;\t]([\d+: -TZ]+)[;\t](\d+\.*\d*)[;\t](\d+)$
#Порядок значений в regexp
mps.1.register.patternOrder=account:1, time:3, sum:4, transId:5
#Формат времени
mps.1.register.timeFormat=yyyy-MM-dd'T'HH:mm:ss'Z'

6. Web-интерфейс

Web-интерфейс пользователя позволяет просмотреть платежи за месяц и установить/сменить номер для поиска:

Глава 21. Модуль MTSBank (шлюз МТСБанк)

1. Назначение модуля

Модуль MTSBank предназначен для оплаты картами через процессинг МТСБанка.

Модуль работает по защищенному протоколу https с использованием шифрования SSL, что исключает возможность перехвата информации и нарушения целостности данных третьими лицами.

2. Настройка модуля

Установите модуль на сервер, обновите клиент. Затем создайте экземпляр модуля. Создайте в редакторе конфигурации модуля новую конфигурацию, пропишите необходимые параметры. После этого сохраните конфигурацию и сделайте её активной.

Для банка нужно будет предоставить URL на который будут перенаправлять клиента после оплаты. URL формируется следующим образом:

http[s]://host[:port]/bgbilling/webexecuter?action=DoTransaction&mid=<код_модуля>&module=mtsbank&operation=check

ВНИМАНИЕ! В связи с "особенностями" прококола шлюза, возможны ситуации с не получением биллингом информации о проведение платежа. В таких случаях требуется ручная проверка статуса платежа из интерфейса биллинга.

Глава 22. Модуль NPay

1. Назначение модуля

Модуль предназначен для начисления наработки за периодические услуги.

2. Настройка модуля

Установите модуль на сервер, используя утилиту bg_installer, обновите клиент биллинга. Затем создайте экземпляр модуля, назвав его произвольным образом (например, Мои абонплаты).

Определите в редакторе модулей и услуг услуги, связанные с этим модулем. Каждая абонентская плата - отдельная услуга. Для начала можете определить несколько тестовых услуг, скорректировав список впоследствии. Создайте конфигурацию модуля:

# Статусы договора, в которых не начисляется абонентская плата
contract.status.suspend.codes=3,4
#
# Автоматическое переначисление абонентских плат договора при изменении их периода, количества и т.п.
# 0 - выключить переначисление, 1 - включить переначисление, 2 - включить переначисление, но выполнять только для текущего месяца
recalculate.on.service.change=1
# E-Mail для отправки уведомлений об автоматическом переначислении при изменении абонплаты, если не указан - уведомление не высылается
#auto.recalculate.email=
# Набор услуг для переобсчета при автоматическом переначислении при изменении абонплаты, если не указан - все услуги
#auto.recalculate.email.service.set=
# Количество выводимых ошибок в периодических процессах
max.periodic.errors=30
# Подмена абонплаты другой услугой на период определённого статуса
#wrap.service=
#
#----------------------------------------
# Выборочное отключение проверки закрытого периода
# перенести абонплату на другой договор
#closed.date.disabled.ActionMovePay=1
# Начисление абонплат
#closed.date.disabled.ActionRecalculatePay=1
# Удаление абонплаты
#closed.date.disabled.ActionServiceObjectDelete=1
# Изменение абонплаты
#closed.date.disabled.ActionServiceObjectUpdate=1
# Перенести абонплату на другой договор с даты
#closed.date.disabled.ActionWrapPay=1
#----------------------------------------

Для исключения приостановки некоторых абонентских плат по статусу договора укажите в конфигурации:

# Абонплаты, на которые не влияет приостановка договора
service.no.suspend.<status_list>=<service_codes>

, где:

<status_list> - код статусов договора через запятую;
<service_codes> - коды услуг договора через запятую.

Например, не приостанавливать в статусе 3 абонпалаты 9 и 36, по всем другим начисления не будет. В статусе 4 не приостанавливать только абонплату 9.

# абонплаты, на которые не влияет приостановка договора
service.no.suspend.3=9,39
service.no.suspend.4=9

Если в статусе 3 и 4 не нужно приостанавливать только абонплату 9, можно было бы записать так:

#абонплаты, на которые не влияет приостановка договора
service.no.suspend.3,4=9

На один статус договора не должно быть несколько записей.

C помощью опции wrap.service возможно указание абонплат, замещающих другие абонплаты на период определённого статуса.

wrap.service.<status_list>=<service_codes>

где:

<status_list> - код статусов договора через запятую;
<service_codes> - пары кодов услуг договора через запятую.

Услуги указываются парами. В каждой паре первой указывается закрываемая услуга, далее двоеточие и услуга, её заменяющая. Замещающая услуга должна быть указанна как не останавливаемая с помощью опций, перечисленных в предыдущем абзаце. Ниже приведён пример замены в статусе 3 79 услуги на 120 а 81 на 123.

wrap.service.3=79:120;81:123
service.no.suspend.3=120,123

Стоимость услуги-заместителя в тарифном плане должна располагаться ниже стоимости замещаемой услуги. Функционал имеет смысл только для месячного пропорционального и подневного режимов снятия замещаемой услуги и необходим для разделения наработки, начисляемой клиентам с активным статусом и закрытым статусом по различным услугам.

Первоначально модуль не требует дополнительной настройки и способен производить начисления простых видов абонентских плат. Дополнительные настройки устанавливаются в конфигурации модуля и указаны в контексте решаемой задачи далее.

3. Привязка абонплат к клиентам

Подключение модуля к договору осуществляется выбором узла Модули дерева договора с последующим выбором модуля Npay из списка установленных модулей в системе. Выбрав экземпляр модуля в дереве договора, можно просмотреть список всех подключенных к договору абонплат с возможностью их фильтрации на выбранную дату.

Для подключения абонплаты к договору необходимо нажать кнопку Новый элемент на стандартной панели инструментов. При этом откроется окно редактора абонплат, в котором необходимо выбрать необходимую абонплату из списка услуг модуля, а также период действия данной абонплаты.

При этом сразу можно указывать объекты, к которым относятся абонплаты. Если установлена галочка Показать все объекты, то в списке объектов будут выведены все объекты, в противном случае - объекты с активным периодом. Количество абонплаты указывает множитель цены - во сколько раз больше вычисленной по тарифу стоимости будет взята абонплата.

Для договоров с несколькими точками подключения, телефонами и т.п., для каждого из которых устанавливаются свои абонплаты, возможна установка абонплат непосредственно для объектов.

Возможно перенесение абонплаты со всей наработкой с текущего договора на другой открытый. Для этого выбирается строка с услугой, правой кнопкой мыши вызывается меню и активируется пункт Перенести на другой договор. После переноса услуги система активирует переначисление по выбранным договорам за месяцы, когда была активна данная услуга. Задачу переначисления выполняет планировщик биллинга, он должен быть запущен.

4. Алгоритм начисления, примеры тарифов

Модуль определяет потребление договором абонплаты по наличию услуги из модуля в договоре. Алгоритм работы следующий. Начисление производится за определённый месяц.

1) производится выборка потребителей услуг данного модуля, получая набор сочетаний: договоры - услуга - период - количество;

2) для каждого сочетания производится разбивка по действующим на период тарифные планы, получая тарифицируемые сочетания: договор - услуга - тариф - период - количество;

Пример 22.1. Пример получения

В договоре определены:

  • Абонплата 1 - с 1 по 10 число;

  • Абонплата 2 - с 9 по 31 число;

  • Тариф 1 - с 2 по 31 число.

Получаем два тарифицируемых сочетания:

  • Абонплата 1 - Тариф 1 - с 2 по 10 число;

  • Абонплата 2 - Тариф 1 - с 9 по 31 число;

Каждое сочетание тарифицируется по тарифу.

1) При помесячном режиме начисления цена в тарифе запрашивается один раз, используя дату окончания периода для передачи в тарифный запрос. При стоимости пропорционально периоду цена определяется пропорционально отношению количество дней, когда абонплата в месяце была открыта и статус активен к общему числу дней месяца. Количества для помесячного режима также всегда рассчитываются на дату окончания периода. Помесячный режим всегда рассчитывается до конца расчётного месяца.

2) При подневном режиме передаётся запрос в тариф на каждый день, входящий в период сочетания. Для каждого дня оценивается стоимость и количества, анализируется статус договора. Снятие может быть произведено как до текущего дня, так и до конца месяца, в зависимости от настройки узла.

Исходя из этого, помесячный режим начислений оптимальнее в плане тарификации, однако цена и количество сущностей, которым пропорциональна абонплата в нем может изменятся только один раз в месяц. В этом её отличие от подневного режима с начислением до конца месяца. При погодовом режиме начисления цена в тарифе формируется аналогично помесячному режиму, но снятие средств происходит один раз в год только в месяц добавления услуги.

3) При погодовом режиме начисление производится только в том месяце, в который была добавлена абонплата. Стоимость абонплаты определяется на конец месяца.

4) При авансовом режиме начисления:

Если период абонплаты закрыт, то цена запрашивается на день начала периода и абонплата снимается только за месяц начала согласно стоимости дня или месяца. При указании цены за месяц дневная цена получается делением месячной на количество дней в месяце начала абонплаты. Соответственно при начислении за месяц авансовые абонплаты с закрытым периодом, открытые не в месяце начисления игнорируются.

Если период абонплаты открыт, то цена запрашивается на ДАТУ_НАЧАЛА=МАКСИМУМ(День начала периода; День начала месяца). Стоимость дня умножается на количество дней от ДАТЫ_НАЧАЛА до конца месяца. При указании цены за месяц дневная цена получается делением месячной на количество дней в месяце начисления.

Рассмотрим несколько примеров. Для начала, простейшие абонплаты, не зависящие от наработок в других модулях.

4.1. Абонплаты, не зависящие от других модулей

Пропорциональная абонплата 40 рублей за месяц.

При этом, если человек подключён в середине месяца, то за первый месяц должно сняться только 20 рублей (половина). Название услуги - Абонплата.

Простая абонплата - 100 рублей в месяц независимо от даты подключения услуги.

Начисление 1 го рубля за каждый день до текущей даты

Погодовой режим снятия - начисление только в месяц добавление абонплаты договору (раз в год).

Авансовый режим снятия - начисление ежемесячно (открытый период), либо единоразово в месяц открытия (закрытый период).

4.2. Абонплаты, зависящие от наработки по объёму в других модулях

Модуль абонплат может производить начисление в зависимости от объёмов наработок в других модулях.

Замечание

Зависимости можно выставить только для подневного и помесячного режима начислений.

Все используемые при тарификации объёмы должны быть описаны в конфигурации экземпляра модуля. Объём наработки описывается в конфигурации экземпляра модуля абонплат следующим образом.

module.amount.<id>.title=<title>
module.amount.<id>.mid=<mid> 
module.amount.<id>.class=<class_name>
module.amount.<id>.sids=<sids>

Где:

<id> - уникальный числовой идентификатор объёма, нумерация должна быть последовательной и непреревной, число не должно меняться впоследствии, при изменении нумерации необходима правка всех тарифов, где используются данные объёмы;
<title> - название объёма;
<mid> - код экземпляра модуля, в котором рассчитывается объём;
<class_name> - класс, рассчитывающий объём;
<sids> - коды услуг через запятую.

В данный момент поддерживаются следующие классы, которые могут быть указаны в <class_name> для расчёта объёма услуги (байт, либо секунд):

bitel.billing.server.npay.bean.DialUpModuleAmount - количество байт или секунд в экземпляре модуля DialUp;
bitel.billing.server.npay.bean.IPNModuleAmount - количествто байт в экземпляре модуля IPN;
ru.bitel.bgbilling.modules.inet.npay.InetModuleAmount - количествто байт в экземпляре модуля Inet;
bitel.billing.server.npay.bean.PhoneModuleAmount - количество секунд округлённой длительности в экземляре модуля Phone.

Указанный в конфигурации объём можно использовать в узле тарифного плана типа Условие по объёму услуги. При размещении данного узла в узле типа Дневной режим снятия объем будет вычисляться за каждый день для использования в условиях по объёму. При размещении в узле типа Месячный режим снятия объем будет вычисляться за рассчитываемый период (период сочетания, см. алгоритм).

Рассмотрим пример конфигурации экземпляра модуля для начисления несколько типов абонплат и использующую при начислении значения входящих трафиков модуля DialUP, IPN и голосового трафика модуля Телефонии. Если необходимо учитывать суммарную наработку по нескольким услугам, они перечисляются через запятую.

module.amount.1.title=Входящий DialUP трафик 
module.amount.1.mid=21 
module.amount.1.class=bitel.billing.server.npay.bean.DialUpModuleAmount 
module.amount.1.sids=23 
# 
module.amount.2.title=Входящий внешний IPN трафик 
module.amount.2.mid=33 
module.amount.2.class=bitel.billing.server.npay.bean.IPNModuleAmount 
module.amount.2.sids=40
#
module.amount.3.title=Объем трафика телефонии 
module.amount.3.mid=73
module.amount.3.class=bitel.billing.server.npay.bean.PhoneModuleAmount 
module.amount.3.sids=83,84,85,86
#
module.amount.4.title=Входящий трафик INET
module.amount.4.mid=179
module.amount.4.class=ru.bitel.bgbilling.modules.inet.npay.InetModuleAmount 
module.amount.4.sids=203
#
module.amount.5.title=Входящий Voiceip трафик 
module.amount.5.mid=79 
module.amount.5.class=bitel.billing.server.npay.bean.VoipModuleAmount
module.amount.5.sids=122

Приведённая выше конфигурация используется в следующих примерах тарифов:

Начисление 1 го рубля только за те дни, когда была наработка в модуле DialUP

Начисление за дни, когда у клиента не было достаточной наработки по IPN, "штрафа" в 10 рублей, стимулирующий тариф.

Все приведённые выше примеры могут быть совмещены с узлами типа: Фильтр по времени и Период.

Тариф, снимающий абонплату за предоплаченные 100 МБ в месяц, если клиент наработал меньше, то снятие происходит пропорционально реально потреблённому объёму.

Тот же тариф, но снимающий в случае, если объем менее 100, как выгоднее: т.е. анализируется доля потреблённых дней в месяце и доля потреблённого объёма, большая доля умножается на цену за месяц.

Необходимо учитывать, что в узле типа "Условие" нижняя граница включена в диапазон, а верхняя - нет. 0 в верхней границе диапазона означает неограниченный объем.

4.3. Абонплаты, зависящие от денежной наработки в других модулях

Модуль абонплат может производить начисление в зависимости от денежной наработки за услуги других модулей. Все используемые при тарификации денежные наработки должны быть описаны в конфигурации экземпляра модуля абонплат следующим образом.

module.account.<id>.title=<title>
module.account.<id>.mid=<mid>
module.account.<id>.class=<class_name>
#module.account.<id>.sids=<sids>

Где:

<id> - уникальный числовой идентификатор денежной наработки, нумерация должна быть последовательной и непреревной, число не должно меняться впоследствии, при изменении нумерации необходима правка всех тарифов, где используются данные денежные наработки;
<title> - название денежной наработки;
<mid> - код экземпляра модуля, в котором рассчитывается объём, 0 для класса KernelAccount;
<class_name> - класс, рассчитывающий объём;
<sids> - коды услуг через запятую (необязательный параметр).

В данный момент поддерживаются следующие классы, которые могут быть указаны в <class_name> для расчёта денежной наработки:

bitel.billing.server.npay.bean.DialUpModuleAccount - денежная наработка в экземпляре модуля DialUp;
bitel.billing.server.npay.bean.PhoneModuleAccount - денежная наработка в экземпляре модуля Phone;
ru.bitel.bgbilling.modules.inet.npay.InetModuleAccount - денежная наработка в экземпляре модуля Inet;
bitel.billing.server.npay.bean.KernelAccount - денежная наработка в ядре, возможен расчёт только целиком за месяц.
bitel.billing.server.npay.bean.VoipModuleAccount - денежная наработка в экземпляре модуля Voiceip;

Указанную в конфигурации денежную наработку использовать в узле тарифного плана типа Условие денежной наработке. Данный узел может быть размещён только в узле типа Месячный режим снятия, денежная наработка будет вычисляться за рассчитываемый период (период сочетания, см. алгоритм) за исключением случая использования класса KernelAccount, который может вычислить только сумму за весь месяц, зато подходит для вычисления наработки любого модуля.

Рассмотрим пример конфигурации экземпляра модуля абонплат для начисления несколько типов абонплат и использующую при начислении значения денежной наработки экземпляра модуля DialUp с кодом 21.

module.account.1.title=Наработка в DialUp
module.account.1.mid=21
module.account.1.class=bitel.billing.server.npay.bean.DialUpModuleAccount
module.account.1.sids=<если нужно, уточнение услуг модуля>
#
module.account.1.title=Наработка в модуле Inet
module.account.1.mid=179
module.account.1.class=ru.bitel.bgbilling.modules.inet.npay.InetModuleAccount

Приведённая выше конфигурация используется в следующих примерах тарифов:

Тариф начисляет дополнительную наработку в случае, если клиент недостаточно наработал по услугам DialUP модуля.

В данном случае Догнать до 600 - это название услуги модуля абонплаты. Пропорциональный периоду режим обозначает, что 600 будет преобразовано в 300, если клиент подключён в середине месяца и период абонплаты в услугах договора также будет открыт серединой месяца. При этом наработка DialUP модуля также анализируется за этот период. Возможен и безусловный режим снятия, когда "доводимая" сумма не изменяется в зависимости от периода действия абонплаты. Режим как выгоднее оценивает сумму снятия при безусловном и пропорциональном режимах и выбирает максимальную из них.

Тариф начисляет клиенту абонплату в 100 рублей в том случае, если его наработка DialUP была менее 400 рублей и 60 рублей в противном случае. Абонплата называется 60 в месяц.

4.4. Абонплаты, пропорциональные количеству телефонов, логинов и сервисов

В модуле возможно создание абонплат, начисляемых пропорционально количеству поинтов (телефонов) в модуле Phone, либо логинов в модулях VoiceIP, DialUP или количеству сервисов в модуле Inet. Предположим, существует абонплата с кодом 103, в тарифном плане для него установлена обычная месячная стоимость, 73 - код модуля телефонии.

Замечание

Зависимость поддерживается только для помесячного и подневного режимов начисления абонплат.

Предположим что абонплата с кодом 103 - это абонплата за аренду телефонного модуля, в тарифном плане для него установлена обычная месячная стоимость, 73 - код модуля телефонии.

Добавление подобной конструкции в конфигурацию модуля умножит сумму абонплаты на количество телефонов в договоре.

module.quantity.1.mid=73
module.quantity.1.class=bitel.billing.server.npay.bean.PhoneModuleQuantity
module.quantity.1.sids=103

Аналогично для модулей VoiceIP, DialUP возможно использования класса (вместо <mid> - код модуля DialUP, VoiceIP):

module.quantity.1.mid=<mid>
module.quantity.1.class=bitel.billing.server.npay.bean.CallModuleQuantity
module.quantity.1.sids=103

Для модуля Inet используйте (<mid> - код модуля Inet)

module.quantity.1.mid=<mid>
module.quantity.1.class=ru.bitel.bgbilling.modules.inet.npay.InetModuleQuantity
module.quantity.1.sids=103

В параметре sids могут быть указаны несколько кодов услуг через запятую.

При помесячном режиме начисления количество высчитывается для даты окончания периода сочетания абонплата-тариф (см. алгоритм). При подневном количество вычисляется для каждых суток.

Замечание

Данный коэффициент используется совместно с количеством услуги, указываемым в свойствах абонплаты. При указании в свойствах абонплаты количества A и вычисленном количестве B по конфигурации, абонплата составит СУММА * A * B.

4.5. Абонплаты, зависящие от тарифных опций

На активированную тарифную опцию можно делать начисление. Начисление по тарифной опции работает как для подневного режима снятия, так и для помесячного, при этом учитывается период (день/месяц).

Для этого в услуге добавьте ветку Опция и выберите нужную опцию в редакторе ветки. "+" или "=" означает соответственно добавить цену к текущей или установить цену принудительно.

Параметры начисления для опции:

безусловно - если опция была активирована один или более раз за месяц (для помесячного режима снятия) или день (для подневного режима снятия), то добавить (установить) цену, расчитанную из потомков ветки.

пропорционально - пропорционально периоду активации. Для помесячного режима снятия период - месяц, подневного - день. Если опция была активирована несколько раз за период, то периоды складываются. Расчитывается с точностью до секунды.

пропорционально количеству - пропорционально количеству активаций. Цена умножается на количество активаций опции за период.

Цена в зависимости от параметров начисления расчитывается после прохождения подветок.

Подветки Опции работают также, как описано выше для тарифов без использования ветки Опции, т.е. установка в подветке Стоимость режима пропорц. периоду будет означать, что цена зависит от периода услуги.

Для большей наглядности наработки для отдельных опций или для групп опций можно создавать отдельные услуги.

5. Методики построения тарифных планов

Особенностью модуля абонплат является то, что он почти всегда используется в связке с другими модулями. При этом можно выделить абонплаты, логически связанные с услугами в каком-либо из модулей и логически отдельные.

Например, если в модуле DialUP есть тариф с включённым трафиком за абонплату, то абонплата логически связана с тарифом DialUP. Примером логически не связанной абонплатой может являться абонплата за предоставление фиксированного IP-адреса.

Тарифы логически связанных абонплат удобнее всего объединять в одно дерево с тарифами за услуги. Например, есть линейка тарифов DialUP с предоплаченным трафиком: 100 МБ - 100 руб, 200 МБ - 200 руб. Указаны через тире включённый трафик и абонплата за него. Создаётся услуга Абонплата за трафик, одна должна присутствовать во всех договорах, использующих данный тариф. Вид тарифных планов будет следующим:

Применение такой схемы гарантирует изменение размера абонплаты при переходе абонента на другой DialUP тариф.

Логически не связанные абонплаты можно вынести в один тариф и указывать этот тариф дополнительно всем договорам. Пример такого тарифа:

Если необходимо в тарфином плане организовать перевод абонплаты с одного режима снятия на другой, то необходимо построить тарифный план следующим образом: на верхнем уровне добавить узлы типа Период для первого и второго режимов снятия, а затем внутри этих узлов создать дочерние узлы для абонплат первого и второго типа соответственно.

6. Начисление

Использование наборов услуг позволяет группировать абонплаты по времени снятия. Например, если необходимо чтобы фиксированные абонплаты с кодами 3,4 и 5 снимались в начале месяца, а Доводящая абонплата с кодом 18 снималась в конце месяца, то создаются 2 набора услуг в конфигурации модуля.

service.set.1.title=Абонплаты конца месяца
service.set.1.sids=18
service.set.2.title=Абонплаты начала месяца
service.set.2.sids=3,4,5

Набор услуг может быть также задан как полный перечень услуг модуля за исключением некоторых наборов услуг. Например:

service.set.3.title=Абонплаты, за исключением абонплат начала и конца месяца.
service.set.3.sids=-{2,3}

В модуле всегда определён набор услуг Полный набор услуг, содержащий в себе все услуги модуля. Он используется, если все абонплаты снимаются единовременно.

Начисление может быть произведено в автоматическом и ручном режиме. В ручном режиме необходимо на вкладке Начисление модуля выбрать обсчитываемый месяц и запустить обсчёт. При этом возможно выбрать набор услуг модуля, на которые производятся начисления. В случае, если начисление было произведено ошибочно, возможно очистить наработку, при этом также используется набор услуг.

Задачу начисления выполняет процесс планировщика, он должен быть запущен.

В автоматическом - в планировщике заданий необходимо добавить задачу Начисление Npay абонплат.

Периодичность запуска задачи определяется требуемой частотой обновления объёма абонплаты. В конфигурации задачи должно быть указано:

mid=<код модуля npay>

При необходимости в конфигурации может быть явно указан набор услуг:

service.set=<код набора услуг>

Если он не указан, используется Полный набор услуг. С использованием наборов услуг возможна настройка снятия различных абонплат в разное время. Необходимо учитывать, что при отработке задачи начисления берётся час, предшествующий текущему. Это даёт возможность снимать абонплату в конце месяца, установив запуск задачи на 0 часов последующего месяца. Данная особенность может мешать произвести съём абонплат при подневном режиме снятия ранее, чем первый час новых суток. При запуске задачи в 0 часов абонплаты будут начислены лишь по предыдущие сутки. Для отключения перевода часа назад добавьте в конфигурации задачи опцию:

hour.minus=0

7. Дебетовые абонплаты

Режим дебетовых абонплат позволяет изменять статус дебетовых договоров в случае, если начисление им абонентской платы может привести к опусканию остатка меньше лимита. Режим применяется только к договорам с режимом Дебет. Режим включается в конфигурации экземпляра модуля следующим образом.

debet.npay.status.manage=1
#Код активного статуса договора
debet.npay.active.status=0
#Код заблокированного статуса договора
debet.npay.locked.status=3
#Коды групп, для которых применяется режим; через запятую
#debet.npay.status.manage.groups=
#Коды тарифных планов; через запятую.
#При указании параметра блокировка осуществляется только, если на дату блокировки в договоре стоит один из указанных тарифов
#debet.npay.status.manage.tariff.ids=
#Учитываемый в дебетовых абонплатах набор услуг (если не указан, считается, что после разблокировки будут начислены все услуги из полного набора)
#debet.npay.service.set=
#сумма на балансе, для которой возможна разблокировка
#debet.npay.unlock.balance.limit=0

Закрытие статусов договоров производится задачей планировщика Закрытие статуса NPay договоров по балансу, запуск которой должен осуществляться в начале суток до переобсчёта абонентских плат. В конфигурации задачи указывается:

mid=<mid>

Где <mid> - код экземпляра модуля NPay.

Для каждого активного договора оценивается сумма начислений абонентских плат при тарификации до текущих суток. Оценивается уже начисленная договору наработка за абонентские платы. В случае, если уже начисленная наработка более или равна планируемой к начислению, не выполняется никаких действий. В случае, если планируемая к начислению наработка больше уже начисленной и её начисление приведёт к понижению баланса договора ниже лимита, то статус договора меняется на определённый в переменной конфигурации debet.npay.locked.status.

При подневном начислении абонентских плат до текущего дня блокировка будет производится с начала любых суток. При подневном начислении до конца месяца, либо помесячном режиме начисления блокировка возможна только в начале месяца перед первым начислением. Для супердоговоров оценивается их совместная наработка со всеми зависимыми субдоговорами.

Перевод договора в активный статус, указанный в переменной debet.npay.active.status, происходит по платежу тогда, когда остаток баланса позволяет открыть договор от текущей даты, начислить ему абонентскую плату и баланс при этом не должен опуститься ниже лимита. Минимально необходимая для открытия сумма платежа должна отображаться в дереве карточки договора напротив экземпляра модуля NPay.

При приходе платежа и открытии договора производится переначисление абонентских плат до текущей даты с учётом нового статуса.

8. Групповые операции

На данный момент доступна только одна групповая операция: "Добавление/прерывание абонплат".

8.1. Групповая операция "Добавление/прерывание абонплат"

Данная групповая операция позволяет добавить или прервать (в частном случае - закрыть) абонплату у договоров.

При установленной опции Добавить выбранные абонплаты будут добавлены всем указаным договорам с заданным периодом и количеством. При установленной опции Прервать выбранные абонплаты будут прерваны на данный период. Если вторая граница периода будет открытой, то выбранные абонплаты будут закрыты датой, указанной в левой границе периода.

Глава 23. Модуль Paylinks

1. Назначение модуля

Модуль предназначен для предоставления пользователям личного кабинета способов оплаты через внешние платёжные системы с гибкой настройкой. Модуль похож на другие подобные модули, реализующие оплату через разные системы, но в отличие от них не предоставляет обработчика ответов от удалённой системы, помимо общих ответов, вроде "успешно", "неуспешно" и других. Остальное, например, некоторая отчётность по оплатам (общая и для договора) и пр. — присутствует.

Также модуль может предоставлять любое количество способов оплаты через любое количество платёжных систем. Обработка успешных оплат и, как следствие, занесение платежа в систему может проводиться либо существующим внешним обработчиком, либо вручную, либо через модуль mps, либо любым другим способом.

Модуль может также использоваться для любого договоро-зависимого предоставления ссылок web-пользователю, например, переходов в какой-то веб-магазин и пр.

2. Настройка модуля

Все методы конфигурируются в конфигурации модуля. Количество методов неограничено. Большинство из параметров метода параметризуются через макросы вида {$var}, количество которых, теоретически, неограничено.

В общем виде конфигурация модуля выглядит так (с подробными комментариями), используется реальный пример со шлюзом газпромбанка:

# Параметры для одного варианта оплаты.
# Во всех параметрах (кроме title) действуют макроподстановки:
# 1) {$sum} - сумма, которую юзер вводит в поле.
# В параметре description не действует.
# В параметрах url и confirm действует: подставляется из поля, в которое её ввёл юзер.
# В параметрах result.* действует: попадает при наличии в обратных url параметра "sum", а для этого она должа быть прописана в параметре url в обратных адресах.
# 2) {$contract.getTitle} - данные договора, действуют везде.
# Здесь getTitle - пример, допустим любой публичный get-тер объекта Contract (см. API), "contract." - префикс переменной.
# В данный момент поддерживаются префиксы:
# {$contract.*} - объект договора соответствующего текущего.
# Примеры: {$contract.getTitle} - заголовок договора, {$contract.getId} - ИД договора (cid).
# 3) {$action}, {$mid}, {$module} - данные доступа для обратных url, действуют только в параметре url.
# Можно прописывать и напрямую, если удобно (например, module=paylinks&mid=666&action=Paylinks).
#
# Метод оплаты 1
# Заголовок. 
method.1.title=Карты VISA, MasterCard
# url, на который отправляется пользователь.
# Если используются обратные url, то в них должно быть обязательно такое: http://webexecuter?mid=${mid}&module=${module}&action=${action}&operation=result&result=success
# При этом у параметра result могут быть разные значения, например, &result=success и т.д., на основании которых выберется дальше ответ.
# Если в ответе надо показать сумму (используется в шаблонах method.1.result.*), то она должна присутствовать как параметр "sum" в обратном url.
# Также в обратных url должен присутствовать  параметр methodId=1 (с соответствующим номером метода), чтобы при возврате знать по какому методу платили и отобразить нужное сообщение.
# Если не надо показывать сообщение и т.д., то можно просто подставить url одного из экшенов, например просмотра баланса, тогда вернётся прямо туда.
# Здесь у нас два url обратных - для успеха и для неуспеха.
back_url_s=http://127.0.0.1:8080/bgbilling/webexecuter?mid={$mid}%26module={$module}%26action={$action}%26operation=result%26result=success%26sum={$sum}%26methodId=1
back_url_f=http://127.0.0.1:8080/bgbilling/webexecuter?mid={$mid}%26module={$module}%26action={$action}%26operation=result%26result=failed%26sum={$sum}%26methodId=1
method.1.url=https://www.pps.gazprombank.ru:443/payment/start.wsm?merch_id=xxx&o.account={$contract.getTitle}&o.sum={$sum}&back_url_s={@back_url_s}&back_url_f={@back_url_f}
# Описание метода, выводится при выборе варианта оплаты и запросе суммы.
method.1.description=Оплата через gazprombank, на счёт {$contract.getTitle}. Тест код договора: {$contract.getId}.
# Текст подтверждения, после ввода суммы.
method.1.confirm=Вы действительно хотите оплатить через gazprombank на счёт {$contract.getTitle} на сумму {$sum}?
# Варианты возврата, может быть любое количество. Соответствующее сообщение будет выведено
# при наличии в обратном url (по которому вернулся пользователь) соответствующего
# параметра (&result=anything).
method.1.result.success=Хорошо, платёж на сумму {$sum} прошёл на счёт {$contract.getTitle}
method.1.result.failed=Плохо, платёж на сумму {$sum} не прошёл на счёт {$contract.getTitle}
#
# Второй вариант оплаты какой-то
method.2.title=Test Тест
...

Обратите внимание, для удобства вынесены url успеха и неуспеха в отдельные параметры, а затем вставлены в основной параметр method.1.url.

Также обратите внимание, что в случае необходимости (например, при передаче через url других адресов возврата) экранировать символы надо заранее, и прописывать в конфигурацию уже экранированное, как, например, здесь %26 вместо &.

В данный момент существует возможность перехода формы только с методом GET.

3. Использование модуля

При добавлении модуля на договор в web-интерфейсе статистики появляется пункт меню "Пополнить счёт", внутри которого перечислены основные типы оплаты, настроенные в данном модуле.

После выбора каждого из методов оплаты открывается страница с названием, описанием, а также приглашением ко вводу необходимой суммы. Все параметры гибко настраиваются в конфигурации модуля.

После этого последует переход на внешнюю платёжную систему по сформированному по шублону url. После возврата в личный кабинет выведется одно из настроеных сообщений об успехе или неуспехе.

Все успешные и неуспешные переходы логгируются в модуле, являясь по сути логом переходов по ссылкам, а не сколько-нибудь достоверной отчётностью по оплатам.

В договоре также можно посмотреть подобную статистику.

Глава 24. Модуль Paymaster

1. Назначение модуля

Модуль Paymaster предназначен для проведения платежей через платежную систему Paymaster c использованием пластиковых карт. Для проведения платежей Вашими клиентами у Вас должен быть заключен договор с системой.

Модуль работает по защищенному протоколу https с использованием шифрования SSL, что исключает возможность перехвата информации и нарушения целостности данных третьими лицами.

2. Настройка модуля

Установите модуль на сервер, обновите клиент. Затем создайте экземпляр модуля. Создайте в редакторе конфигурации модуля новую конфигурацию, введите требуемые параметры. После этого сохраните конфигурацию и сделайте её активной.

3. Оплата через систему Paymaster

Для предоставления возможности клиенту платить банковской картой через платежный шлюз Paymaster необходимо подключить данный модуль к договору клиента. В Web-интерфейсе клиента появится новый пункт в меню - Оплата через Paymaster (название по умолчанию).

4. Мониторинг платежей

В клиенте билинга есть возможность отслеживать историю платежей по каждому абоненту. Для этого необходимо выбрать модуль Paymaster в дереве параметров договора. Для просмотра ВСЕХ платежей, проведенных через систему Paymaster, существует глобальный монитор в параметрах модуля. В открывшейся вкладке Проведенные платежы модуля Paymaster у Вас есть возможность просмотреть платежи с учетом фильтра по периоду, совершенные вашими абонентами.

По двойному клику левой кнопкой мыши на строке в таблице открывается соответствующий договор.

Глава 25. Модуль PayOnline

1. Назначение модуля

Модуль PayOnline предназначен для проведения платежей через платежную систему PayOnline c использованием пластиковых карт. Для проведения платежей Вашими клиентами у Вас должен быть заключен договор с системой.

Модуль работает по защищенному протоколу https с использованием шифрования SSL, что исключает возможность перехвата информации и нарушения целостности данных третьими лицами.

2. Настройка модуля

Установите модуль на сервер, обновите клиент. Затем создайте экземпляр модуля. Создайте в редакторе конфигурации модуля новую конфигурацию, скопируйте туда приведённый ниже текст и введите требуемые параметры. После этого сохраните конфигурацию и сделайте её активной.

#Название пункта меню в Web-интерфейсе (по умолчанию "Пополнение счета кредитной картой")
web.menuItem1=Оплата пластиковой картой

#Перечень кодов статусов, которые считаются активными для модуля
contract.active.status.codes=

#Код продавца (выдается после заключения договора с PayOnline)
merchant.id=

#ваш секретный ключ (выдается после заключения договора с PayOnline)
private.security.key=

#URL, на который осуществляетя перевод для оплаты ("/" в конце не нужен)
pay.online.url=https://secure.payonlinesystem.com/ru/payment

#Код типа платежа, которыми будут зачисляться платежи
payment.type.id=
#Код типа расхода, при отмене платежа
refund.charge.typeid=
#Комментарий при отмене платежа
refund.charge.comment

#Нужно ли сохранять данные о карте (4 последние цифры карты) и rebillAnchor в БД.
#Возможные значения: true - нужно сохранять, false - не нужно сохранять.
payonline.store.data=false

#URL возврата, на который будет возвращать клиента после платежа
redirect.url=

#Минимальная разрешенная сумма платежа
min.summa=100

#Максимальная разрешенная сумма платежа
max.summa=3000

#Количество потоков очереди отправки платежей
#thread.count=20

#Данные организации выводимые на чеке (название, ИНН, адрес, телефон)
check.org.header=Название организации
check.org.inn=ИНН организации
check.org.address=Адрес организации
check.org.phone=Телефон организации

#Заголовок чека(может быть несколько таких связок)
pdf.check.title.1.regex=^Pech+$
pdf.check.title.1.title=Good

#Автоплатеж
#Включает данный функционал в web-кабинете
rebill=true
#URL, на который отправляются запросы автоплатежа
rebill.url=https://secure.payonlinesystem.com/payment/transaction/rebill

#Замена комментария по умолчанию к платежам
#Простой платеж
usual.comment="Простой платеж"
#Автоплатеж
rebill.comment="Автоплатеж"

#Дополнительная уникальность платежей. Необязательный параметр. 
rebillUnique=может принимать любое значение
#========Нстройка комиссии
#Комиссия. Возможные значения: 0 - нет комиссии; 1 - комиссия из суммы платежа; 2 - комиссия сверх суммы платежа
commission.type=0;
#Процент комиссии 0-100 %
commission.percent=2
#Коментарий к расходу по комиссии
commission.comment=Комиссия Payonline
#тип расхода для комиссии 
commission.charge.type.id=
#тип платежа для возврата комиссии при отмене платежа
refund.payment.typeid= 
#комментарий при возврате комиссии
refund.charge.comment=Возврат комиссии Payonline

Замечания:

  1. Прежде, чем задавать payment.type.id необходимо создать соответствующий платеж в Справочники->Другие->Типы платежей

  2. После заключения договора с системой PayOnline в их личном кабинете необходимо задать callback URL, который ждет результаты от платежной системы. URL будет выглядеть следующим образом: http://<адрес_машины_биллинга>/payonline/<mid>. Например, если у вас биллинг находится по адресу http://billing.example.com/bgbilling/ и модуль PayOnline имеет mid=16, то результирующий URL, который нужно дать компании PayOnline, выглядит следующим образом: http://billing.example.com/bgbilling/payonline/16.

  3. Чтобы использовать функционал автоплатежа необходимо заключить доп. соглашение с PayOnline. И в планировщик заданий добавить задачу Автоплатеж(Rebill). В параметрах запуска задачи нужно указать код модуля PayOnline и время запуска 1 раз в сутки.

3. Оплата через систему PayOnline

Для предоставления возможности клиенту платить банковской картой через платежный шлюз PayOnline необходимо подключить данный модуль к договору клиента. В Web-интерфейсе клиента появится новый пункт в меню - Оплата банковской картой (название по умолчанию).

3.1. Простой платеж

Для совершения простого платежа необходимо ввести необходимую сумму в поле Сумма и нажать кнопку Оплатить. Далее клиент попадает на страницу подтверждения оплаты. На данном этапе уже сформирован запрос на платежный шлюз и от клиента требуется подтвердить оплату, либо Отмена для отмены платежа.

В случае, если клиент подтверждает оплату, то он перенаправляется на платежный шлюз, где может ввести информацию о своей пластиковой карте. Правильно заполнив предложенную форму и нажав кнопку Оплатить, клиент будет уведомлен о результате платежа.

В случае положительного результата биллинговая система начислит клиенту указанную им сумму на счет.

3.2. Автоплатеж

Данный функционал позволяет выполнять повторные транзакции без непосредственного участия плательщика ежемесячно. Как и остальные программные интерфейсы, Автоплатеж работает по защищенному протоколу https с использованием шифрования SSL, что исключает возможность перехвата информации и нарушения целостности данных третьими лицами.

Для одного договора может быть активирован только 1 автоплатеж. Если необходимо изменить параметры автоплатежа после успешной активации, то нужно сначало удалить автоплатеж, а затем активировать новый.

Для того, чтобы активировать автоплатеж, необходимо ввести сумму автоплатежа в поле и указать число месяца автоплатежа. После заполнения всех полей необходимо нажать кнопку Активировать, после чего будет произведена стандартная процедура платежа.

Автоплатеж осуществляется периодической задачей планировщика Автоплатеж (Rebill). Для корректной работы задачи необходимо указать в конфигурации модуля параметр contract.status.active.codes=<перечень кодов через запятую>. Таким образом, не будут проводиться автоплатежи по закрытым договорам и договорам, имеющим неактивный статус.

Для того, чтобы удалить автоплатеж, необходимо нажать кнопку Отменить автоплатеж.

4. Мониторинг платежей

В клиенте билинга есть возможность отслеживать историю платежей по каждому абоненту. Для этого необходимо выбрать модуль PayOnline в дереве параметров договора. Здесь присутствует фильтр по типу платежа (все/только автоплатежи/только обычные) с указанием периода, когда производилась оплата. Также отображается состояние автоплатежа, если он активирован. Оператор биллинга может только удалить автоплатеж с договора, если клиент по каким-либо причинам не может это сделать самостоятельно, сняв соответсвующее выделение автоплатеж.

Для просмотра ВСЕХ платежей, проведенных через систему PayOnline, существует глобальный монитор в параметрах модуля. В открывшейся вкладке Проведенные платежы модуля PayOnline у Вас есть возможность просмотреть платежи с учетом фильтра по типу платежа и указанному периоду, совершенные вашими абонентами. На вкладке модуля Ошибки автоплатежей выводятся ошибки, которые были получены от системы Payonline по автоплатежу для каждого договора.

По двойному клику левой кнопкой мыши на строке в таблице открывается соответствующий договор.

5. Сверка платежей

Существует возможность произвести сверку платежей, используя выгружаемые из системы Payonline csv-файлы, сформированные за определенный период. Сверка осуществляется через меню Модули->Payonline->Сверка платежей.

После проведения сверки на вкладке Недостающие платежи появятся платежи, которые есть в csv-файле и отсутствуют в биллинге. На вкладке Лишние платежи - отсутствующие в csv-файле, но присутствующие в базе биллинга. Существует возможность добавить один и более недостающих платежей, используя контекстное меню на таблице недостающих платежей, либо удалить один и более лишних платежей на соответствующей вкладке.

Глава 26. Модуль Payture

1. Назначение модуля

Платежный модуль Payture предназначен для осуществления безопасного приема платежей от абонентов банковскими картами Visa/MasterCard. Более подробную информацию о сервисе, размере комиссии можно прочитать на сайте платежного сервиса Payture.

2. Настройка модуля

Скачайте модуль payture с нашего сервера, установите на сервере с помощью утилиты bg_installer.sh (.bat).

В редакторе модулей и услуг создайте экземпляр модуля payture.

Для дальнейшей работы модуля необходимо создать конфигурацию модуля и настроить под себя оции, представленные ниже:

# адрес платежного шлюза сервиса (для тестовых платежей используйте представленный ниже)
payture.server.url=http://sandbox.payture.com/
# идентификатор провайдера (выдается сервисом)
payture.key=
# пароль
payture.password=
# адрес, куда клиента направят после успешной оплаты
payture.success.url=http://www.bgbilling.ru
# комментарий платежа
payture.payment.comment=Оплата на счет
# код типа платежа
payture.payment.type=
# код типа расхода, которым будет произведен возврат денег
payture.charge.type=

Для получения статуса платежей необходимо передать в Payture адрес обработчика биллинга, который формируется следующим образом:

http://host[:port]/bgbilling/paytureexecuter/<mid>

3. Проведение платежей

Для совершения платежа необходимо перейти в личный кабинет, выбрать пункт меню, соответствующий платежной системе Payture. Перед абонентом появится окно следующего содержания:

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

4. Мониторинг платежей

Для просмотра общего списка платежей по всем договорам в системе существует Монитор транзакций, который доступен через меню Moдули->Экземпляр Payture->Монитор транзакций.

Платежи можно отфильтровать по названию договора, по статусу и периоду.

Также можно отслеживать платежи по каждому договору в отдельности. Для этого необходимо открыть карточку договора, в списке модулей выбрать экземпляр модуль Payture. Справа появится окно со списком платежей договора.

5. Возврат платежей

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

Глава 27. Модуль Phone

1. Назначение модуля

Модуль предназначен для обсчёта телефонных соединений обычной телефонии на основании текстовых логов, приведённых к определённому формату, и позволяет вести учёт в соответствии с последними требованиями законодательства РФ.

В модуле реализован учёт и обсчёт услуг, предоставляемых клиентам и учёт операторских взаиморасчётов.

2. Настройка модуля

После установки модуля, создайте его экземпляр и в Редакторе модулей и услуг создайте услуги, предоставляемые абонентам и операторам.

Услуги абонентов - это предоставление местной, зоновой, либо МГМН связи для абонента в режиме преселект или хотчойс через какого-либо оператора. Соответственно, количество услуг для абонента будет представлять из себя произведение количества операторов на количество типов связи и режимов, например:

  • Местная связь

  • Зоновая связь Оператор 1 преселект

  • Зоновая связь Оператор 1 хотчойс

  • МГМН связь Оператор 2 преселект

  • МГМН связь Оператор 2 хотчойс

  • МГМН связь Оператор 3 преселект

  • МГМН связь Оператор 4 хотчойс

Услуги операторов - это предоставление услуг завершения вызовов, либо инициации. Перечень услуг операторов можно ограничить названием предоставляемых услуг, например Инициация, Завершение.

На вкладке Конфигурация создайте и установите конфигурацию модуля.

# Активные статусы договора
contract.status.active.codes=0
# 
#-------------------------------------
# Проверки закрытого периода 
#-------------------------------------
# Редактирование поинта
#closed.date.disabled.ActionClientItemUpdate=1
# Установка баланса
#closed.date.disabled.ActionSetBalance=1
#
#-------------------------------------
# Параметры обработки и тарификации CDR
#-------------------------------------
# Количество знаков после запятой в поле "стоимость сессии" (cost) таблицы log_session
# используется только при создании новой таблицы log_session
session.call.cost.scale=2
# Количество знаков после запятой в поле "стоимость сессии для оператора" (oper_cost) таблицы log_session
# используется толькоп при создании новой таблицы log_session
session.oper.cost.scale=5
# Вести учет входящих сессий для поинтов
#store.incoming.calls=1
# Генерация ошибки обработки, когда для CDR-записи не найдено правила, 1 - включить
error.on.session.rule.notfound=0
# Генерация ошибки обработки, когда для CDR-записи найдено несколько правил, 1 - включить
error.on.session.rule.many=0
#
#--------------------------------------
# Поведение
#--------------------------------------
# 1 - разрешение добавить поинты, если для них нет подходящего ресурса
point.resource.strict.check=0
# Резервирование ресурсов телефонных номеров
phone.resource.reserve=1
#
#----------------------------------------
# Web-интерфейс клиента 
#----------------------------------------
# Названия пунктов меню
web.menuItem1=Просмотр сессий Телефонии
web.menuItem2=Наработка по Телефонии
web.menuItem3=Наработка по направлениям Телефонии
# Сессий в отчёте по сессиям на Web-странице
show.on.page.web=50 
# Макс. кол-во сессий на Web (при попытке отобразить все)
show.on.page.web.max=1000 
# Страниц в отчёте по сессиям в клиенте
show.on.page.session=50

#
#----------------------------------------
# Функционал черно-белых списков. 1- включен.
#----------------------------------------
web.menuItem.blackwhitelist.enable=0

3. Подготовка логов

Исходными данными для работы модуля являются CDR-записи, разделённые по АТС и предоставленные в следующем формате.

- дата и время начала звонка (dd.MM.yyyy HH:mm:ss)
- длительность звонка (секунды)
- # A
- # A (E.164), далее #A164
- # B
- # B (E.164), далее #B164
- port_from
- port_to
- категория звонка
- время соединения (секунды)
- стоимость вызова

Поле Категория в данный момент не используется биллингом, вместо него могут быть подставлены 0.

Время соединения используется для учёта межоператорских взаимозачётов правилами и всегда больше или равно длительности звонка. Это полное время от начала установки соединения с АТС оператора до окончания соединения. Поинты тарифицируются на основании длительности звонка - времени разговора абонента. Т.е. для тарификации сессии по правилу будет использована длительность соединения а для тарификации абонента - длительность звонка.

Стоимость вызова может задавать как цену всего звонка для абонента, так и минуты звонка, использование данного поля задаётся в тарифном плане.

Поля Время соединения и Стоимость вызова могут отсутствовать.

CDR-запись представляет собой строку в текстовом файле кодировке ASCI, в качестве разделителей полей используется знак табуляции. Например, фрагмент лога:

01.08.2006 10:55:18 57733 3517913292 73517913292 2479292 73512479292 3 62 5 57733 0
01.08.2006 14:08:33 75980 3517744152 73517744152 2479292 73512479292 4 34 5 75980 0

Логи должны быть разбиты по АТС и по часовым интервалам, при этом имя файла формируется по шаблону dd_HH, файл помещается в zip-архив с именем dd_HH.zip. Логи группируются в каталоги по годам и месяцам. Например, дерево файлов лога АТС.

2005 |
     |-01 |
          |-01_00.zip
          |-01_01.zip
.....................
     |-02 |
          |-01_00.zip
.....................  

Пример подобных логов вы можете посмотреть здесь. На уровень выше расположен скрипт billing.pl конвертации логов АТС в формат модуля. Вы можете модифицировать скрипт под формат логов вашей АТС. Скрипт написан на Perl, для запуска на Win платформе необходима установка Perl-интерпретатора, вы можете взять его с сайта http://www.activestate.com. Разумеется, конвертер может быть реализован на любом другом языке программирования.

Логи каждой АТС должны быть выложены в отдельный каталог, доступный серверу биллинга по FTP, либо через файловую систему. Примеры конвертеров логов доступны на WiKi.

4. Настройка загрузки и обработки логов

Для каждой АТС на вкладке Источники модуля должен быть заведён свой источник. В зависимости от метода доступа к логам у источника устанавливается тип FTP, либо Локальная или сетевая папка.

При указании FTP-источника в поле Сервер вводится DNS-имя, либо IP-адрес FTP-сервера, его порт (если не указан, берётся 21) и каталог, в котором хранятся логи данного источника.

Формат адреса сервера: <HOST>[:<PORT>][PATH], параметры в квадратных скобках не обязательны к указанию.

Например: ftp.bitel.ru/pub/projects/bgbilling/phone/log/source_1. Это реальный каталог с логами, вы можете использовать их для тестирования.

В конфигурации источника может быть указана переменная resource.categories=<коды категорий ресурсов через запятую>. Про ресурсы номеров описано далее. Данная опция, по сути, определяет номерную ёмкость АТС. Обработчик выводит ошибки в журнал ошибок при установленной данной опции и обнаружении звонков в логах данного источника с номеров, относящихся к указанным категориям, но при этом не соотнесённых ни одному поинту. Таким образом можно осуществлять простой аудит.

При создании источника типа Локальная или сетевая папка достаточно указать каталог с логами. Название источника используется для его идентификации в дальнейшем.

Загрузку логов производит процесс DataLoader. Для его запуска на UNIX-системе выполните скрипт data_loader_start.sh, предварительно в файле data_loader.sh необходимо прописать путь к Java-машине, например:

cd ${0%${0##*/}}.

JAVA_HOME=/opt/java/jre

В Windows-системе выполните скрипт data_loader_install.bat для установки загрузчика в список служб и далее вы можете запускать службу BGDataLoader через оснастку Администрирование=>Службы.

В случае успешного старта загрузчика логов в log/dataloader.log должен быть примерно такой текст.

Checking port 9033...
Port is free starting the applicalion...
Starting DLProcessManager on 9033
Creating socket on 9033

Если лог пуст, проверьте лог log/dataloader.out на предмет ошибок.

Процесс обработки логов включает в себя две стадии: загрузку первичных логов в базу данных и непосредственно обработку логов, при которой звонки соотносятся клиентам и тарифицируются. Загруженные логи можно переобрабатывать неограниченное количество раз, количество сессий в базе не будет увеличиваться. При загрузке часового лога задание на его обработку генерируется автоматически.

Загрузка часового лога может быть инициирована вручную, либо автоматически. Для ручной инициации загрузки логов откройте вкладку Менеджер источников модуля.

По мере загрузки логов цвет часовых квадратов будет изменяться. Загрузка логов производится случайным образом, не по порядку часов. По мере загрузки логов загрузчик логов сам добавляет задания на обработку и производит обработку логов. Обработка логов выполняется по порядку часов. Для отслеживания изменения состояний логов нажимайте кнопку Обновить панели инструментов.

По завершению обработки сессии должны появится в ответах договоров. При этом производится учёт абонентского и операторского трафика и его тарификация. Про настройку абонентов, операторов и их тарифов описано далее.

Если этого не произошло, обратитесь в Сервис=>Журналы=>Журнал ошибок. В выпадающим списке выберите ваш модуль телефонии, установите месяц и нажмите кнопку с галочкой.

Найденные ошибки необходимо исправлять и запускать переобработку логов до полного исчезновения ошибок в журнале. Добавление логов в обработку производится в Менеджере источников путем выбора квадрата часов и активации пункта меню Добавить в обработку для выбранного источника.

После завершения отладки модуля возможна настройка автоматической загрузки логов телефонии. Это может быть сделано двумя способами:

1. По мере подготовки логов автоматически вызывать добавление задачи на загрузку лога запуском:

./data_loader.sh -eload=yyyy-MM-dd-HH-<source_id>
#Например, добавление задания на загрузку лога за 2006-12-14 10 часов для источника с кодом 15
./data_loader.sh -eload=2006-12-14-10-15 

Также можно передать команду через сокет управления dataloader по TCP в виде (9033 по умолчанию):

load=yyyy-MM-dd-HH-<source_id>\n

Этот путь более правильный, подходит для полной автоматизации процесса "подачи" логов в биллинг.

2. Раз в час задача Генератор заданий на загрузку, запускаемая планировщиком, создаёт задание на загрузку очередного часового лога для всех источников FTP, либо Сетевая папка. Запуск задачи необходимо настроить в Планировщике заданий на 15 минут каждого часа. Вполне возможно, что к этому моменту логи ещё не будут добавлены, тогда загрузчик будет пытаться загрузить недостающие логи в течении 3х суток. Этот метод подходит для режима, когда логи подготавливает отдельный специалист, не связанный с биллингом.

Результирующими данными обработки логов являются логи сессий в договорах клиентов и операторов, привязанные к поинтам, либо правилам (см. далее). Для того, чтобы наработка сессий перешла в баланс договора используется вкладка модуля Установка баланса. Единственным параметром выступает дата месяца, за который необходимо установить баланс.

Для того, чтобы не делать установку вручную вы можете настроить задачу планировщика Установка баланса телефонии. При запуске задача берет предыдущий от текущего часа час и производит установку баланса за этот месяц.

Соответственно, необходимо настроить два экземпляра задачи в планировщике заданий. Одну - периодическую, например, каждый час. Другую - в 55 минут первого часа месяца для установки баланса за предыдущий месяц с учётом последнего загруженного часового лога. Примеры настройки периодической и единоразовой задач приведены на снимках ниже.

В параметрах запуска задачи должно быть установлено:

mid=<код модуля телефонии>

5. Географические коды, карты зон и цен

Тарификация с использованием справочника географических кодов является одним из вариантов тарификации для VoiceIP и Phone-модулей. Метод подходит при работе с операторами, разбивающими все множество префиксов мира на зоны с фиксированными ценами.

Справочник географических кодов - это перечень записей вида "префикс-направление", описывающий весь мир. Пример справочника можно загрузить здесь. Перед началом работы с модулем необходимо произвести загрузку справочника на вкладке модуля Географические коды.

Для редактирования над справочником размещена панель инструментов.

Для добавления нового кода выберите родительский узел и нажмите Новый элемент.

Направление можно выбрать из списка существующих, либо создать новое, введя его название в текстовую область и нажав кнопку + справа от области. Следует обратить внимание на параметр Нач. уровень и Кон. уровень. Эти целые числа определяют до какой глубины будет уточняться направление при прохождении дерева. По умолчанию уровни не установлены, что означает уточнение до самого нижнего узла.

Уровни отображаются в дереве двумя числами после направления. Начальный и конечный уровни задают до какой глубины при прохождении дерева кодов будет уточняться направление. Глубина вложенности считается от нуля (корень дерева), т.е. 7 (Россия, СНГ) - это 1-ый уровень, 7352(Курган) - это второй уровень.

При установке уровней как на снимке сверху направление будет уточняться только до Курган, т.е. все звонки в Белозерское, Кетово и т.п. будут выглядеть как Курган.

Кнопка Удалить удаляет географический код.

Кнопка Удалить все коды удаляет все географические коды.

Внимание

Перед удалением проверьте, не используется ли код в картах зон!

Кнопка Экспорт позволяет выгрузить все дерево, либо какой-то префикс в текстовый файл.

Справочник выгружается в текстовый файл с разделителями столбцов - табуляторами и имеет примерно следующий формат:

735111 Трёхгорный 0 0
73512 Chelyabinsk 0 0
735121 ЮУСТ Челябинск 0 0

Последние 2 столбца - уровни определения направления. Их может и не быть.

Для импорта используется аналогичный файл, либо аналогичное содержимое буфера обмена. Можно импортировать как весь справочник, так и его часть.

При импорте можно поставить одну или обе галочки добавлять новые и обновлять существующие. Обновляются направление и уровни префикса.

5.1. Карта зон

Карта зон - это разбиение справочника кодов по зонам - областям равной цены. Карт в модуле может быть несколько.

Перед созданием карты все используемые зоны должны быть описаны на вкладке Справочники модуля. Если МГМН-операторов с зоновой тарификацией несколько - советуем начинать имя зоны названием оператора.

Создание карт производится на вкладке модуля Карты зон модуля. Для создания карты нажмите Новый элемент на стандартной панели инструментов и введите её название. Для открытия карты дважды кликните по ней мышью. Переименование - кнопка Редактировать панели инструментов.

Зоны присваиваются узлам дерева географических кодов. При присвоении зоны узлу-предку она автоматически распространяется на узлы-потомки.

Для установки зон используется меню, вызываемое правой кнопкой мышки. Карту зон можно экспортировать целиком в XML-файл и импортировать из него также целиком. Файл имеет примерно следующий формат:

<?xml version="1.0" encoding="UTF-8"?>
<zones name="Карта 1">
    <zone name="1-я зона">
        <codes>
            <code id="735150"/>
            <code id="3"/>
            <code id="7"/>
            <code id="73512"/>
        </codes>
    </zone>   
    <zone name="Россия 1">
       <codes>
            <code id="7341"/>
            <code id="91"/>
        </codes>
    </zone>
    <zone name="Международная 6 (22,11)">
        <codes>
            <code id="6"/>
        </codes>
    </zone>
</zones>

Атрибут name в корневом узле zones может не указываться в импортируемом файле.

5.2. Карта цен

Карта цен - это привязка цен к географическим кодам. Карт цен в модуле может быть несколько.

Карта цен может быть удобна для тарификации мг/мн звонков, когда оператор мг/мн тарифицирует агента не по зонам, а по связке: префикс - цена или диапазон префиксов - цена.

При использовании карты цен направление вычисляется по географическим кодам.

Карту цен аналогично карте зон можно импортировать и экспортировать в csv-файл формата:

7     10.0
7347  5.0

Или в таком:

7     Россия                   10.0
7347  Республика Башкортостан  5.0

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

Столбцы в файле импорта должны быть разделены одним знаком табуляции.

При импорте можно указать дополнительный префикс - он будет добавлен перед каждым префиксом. Это может быть удобно, если переданный список цен оператора для МГ тарификации представлен без цифры 7, т.е. 917, а не 7917.

При импорте автоматически разделяются префиксы вида:

355(40-41, 43-49)    ALBANIA [1]    1,82
43 644, 650, 660, 680, 681, 688, 699, 711,720    Австрия (mob)    16,51

В качестве значения префикса может выступать префикс-диапазон, например: 374(9300-9328).

Помимо импорта возможно поэлементное редактирование карты цен стандартными кнопками добавления/редактирования/удаления.

6. Управление ресурсами номеров

Управление ресурсами позволяет отслеживать номерную ёмкость. Для управления ресурсами используется вкладка Ресурсы модуля.

Категории ресурса позволяют произвести логическое деление всего объёма ресурсов. Например, на "Золотые" и обычные номера, либо на номера, доступные на разных АТС. Для редактирования категорий используется подвкладка Категории, для добавление категории выберите родительскую категорию и нажмите Новый элемент на стандартной панели инструментов.

На вкладке Управление производится непосредственное управление ресурсами.

6.1. Добавление ресурсов

Для добавления ресурсов выберите категорию в дереве и нажмите кнопку Открыть ресурсы в панели инструментов над таблицей просмотра ресурсов.

В открывшемся редакторе введите диапазон номеров и дату, с которой они доступны.

После загрузки номерной ёмкости возможно изменить период действия для некоторых номеров. Для выбора поддиапазона ресурсов используется фильтр, далее комбинацией клавиш Ctrl+A выбираются все строки открывшейся таблицы и кнопкой Изменить период ресурсов открывается редактор.

Аналогично осуществляется перенос ресурсов в другую категорию и удаление ресурсов. Удалить можно только ресурс, который не проставлен ни в одном договоре.

6.2. Слежение за ресурсами

При выборе категории отображаются ресурсы только выбранной категории, при выборе Все категории - отображаются все ресурсы. Возможен фильтр по диапазону номеров и статусу номера. Свободным считается номер, не выданный никакому договору. При установке фильтра по статусу номера необходима установка даты, на которую выводятся статусы.

Фильтр применяется нажатием кнопки Вывести.

При двойном клике мыши по строке с ресурсом открывается таблица, отображающая историю использования ресурса. Двойной клик в таблице истории открывает договор.

Кнопка Синхронизировать занятые производит обновление состояния ресурсов и истории их использования на основании поинтов договоров. При любом редактировании поинтов происходит автоматическое изменение состояния ресурса и истории его использования.

При установке флага

# Резервирование ресурсов телефонных номеров
phone.resource.reserve=1
#Количество месяцев блокировки 
#phone.resource.reserve.month.count=1

появляется возможность резервирования номеров на месяц, после закрытия номера.

7. Учёт абонентского трафика

Понятие поинта в модуле идентично абонентской точке доступа (порта, либо номера), предоставленной клиенту на АТС. К поинтам привязываются сессии. Для вывода всех поинтов, привязанных к договору, необходимо выбрать экземпляр модуля в дереве договора. Возможна сортировка поинтов по номеру/порту и периоду действия, а также возможна фильтрация поинтов на определенную дату.

В свойствах поинта могут быть указаны параметры: Номер(а), Порт(ы), Алиас и АТС, к которой привязан абонент. Привязка к АТС (источнику) позволяет избежать дублирования звонков, при прохождении вызова абонента через несколько АТС. Алиас может быть не указан, тогда биллинг будет идентифицировать (отображать) поинт как Номер(а) <перечень номеров> на <Название источника>, либо Порты(а) <перечень портов> на <Название источника>.

Внесение нескольких номеров (портов) на один поинт может быть произведено через запятую, однако это лишает возможности просмотра сессий с разбивкой по номерам и данный способ учёта не рекомендуется.

На вкладке Редактирование задаются свойства поинта, его источник и период действия. Кнопка Взять из пула ресурсов рядом с полем ввода номера позволяет получить номер из базы ресурсов модуля.

Вне зависимости от того, был ли номер получен из пула ресурсов, либо введён вручную, если он присутствует в пуле - при всех модификациях поинтов в истории использования ресурса будут изменяться записи. Для возвращения ресурса в пул, достаточно закрыть его в договоре.

Обратите внимание, что должен быть указан номер абонента в формате E.164 (см. снимок). При сохранении поинта система автоматически проверяет отсутствие в модуле одинаковых номеров на двух разных договорах в с пересекающимися периодами. При обнаружении конфликта система выдаст предупреждение и данные не будут изменены.

На вкладке Тарифы могут быть указаны тарифные планы для конкретного поинта.

На вкладке Абонплаты к поинту могут быть привязаны абонентские платы модуля NPay. Для отображения в этой вкладке абонплат в конфигурации модуля телефонии должно быть прописано (<mid> - код экземпляра модуля NPay):

npay.mid=<mid>

Непосредственно к номеру могут быть привязаны абонплаты за различные дополнительные услуги, выделение линии и пр. Начисление абонентских плат производится средствами указанного в конфигурации экземпляра модуля.

При обработке часового лога выполняются следующие шаги для каждой записи. Обработка правил на данной схеме не детализирована, она будет рассмотрена далее.

Как видно из вышеописанной схемы после идентификации поинта производится поочерёдный "просмотр" тарифов его договора с целью определения стоимости минуты звонка, направления и услуги. Порядок просмотра тарифов задаётся позицией. Первыми в порядке позиций просматриваются (если есть) тарифы поинта, персональные тарифы договора, содержащие поддерево для данного модуля, далее глобальные тарифы.

Соответственно в договоре может быть несколько тарифов на телефонию. Например: Местная связь, Зоновая связь, МГМН-связь, упорядоченных по позиции. При этом тариф МГМН-связи может меняться в зависимости от оператора, выбранного абонентом. При использовании хотчойс (выбора оператора префиксом преднабора) в договоре должны быть установлены все тарифы МГМН-операторов.

Ниже приведён снимок редактора тарифов договора с указанными несколькими тарифами.

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

7.1. Тарифы на местную связь

Тариф, содержащий поддерево с тарифами на местную связь, должен располагаться в договоре с минимальной позицией. Т.е. при тарификации звонка поинта он должен просматриваться первым. Следом за ним могут следовать тарифы зоновой и МГМН-связи.

Рассмотрим простейший тариф на местную связь.

Для разбора номера используется узел Часть префикса.

Узел Установка услуги помещает в ответ тарифного запроса услугу данного звонка. Стоимость минуты может быть заключена в фильтр по типу времени, период. Узел Параметры тарификации также может быть добавлен в разные части префикса с различными режимами округления.

Вот пример более сложного местного, тарифа в котором также описываются сотовые префиксы:

Рассмотрим ещё одну линейку из двух тарифов на местную связь - Комбинированный и Поминутный. У оператора выделено два типа внутреннего трафика - Внутрисетевой и Местный, при этом цена внутрисетевого постоянна и равна 0.09, а цена местного в поминутном тарифе зависит от времени суток, а в комбинированном - бесплатна первые 450 минут, а далее по определённой цене.

В данных тарифах используется узел Диапазон наработки, позволяющий изменять стоимость услуги в зависимости от наработки по какой-либо зоне.

Оба тарифа расширены от базового тарифа Телефония, в котором определены 2 зоны в зависимости от префикса. Обратите внимание, что более длинный префикс должен стоять первым. Наследующие тарифы также дополнены поддеревом модуля абонплат, в котором определена стоимость абонплаты за телефонный номер в зависимости от тарифа.

В комбинированном тарифе добавлены 2 узла типа Зона в одном из них жёсткая цена, в другом - два диапазона, определяющие 450 минут в месяц бесплатного местного трафика и далее по 0.18 рубля за минуту.

В поминутном тарифе внутрисетевой трафик также определён по 0.09, а цена местного зависит от времени суток:

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

Рассмотрим пример модернизации комбинированного тарифа, приведённого ранее, когда в бесплатную квоту входят и внутрисетевой и местный трафики. Базовый тарифный план, обратите внимание, что зоновая и местная телефония теперь установлены в одну зону.

Расширяющий комбинированный тариф, оплата превышения общей квоты в 450 минут идёт по разным ценам за внутрисетевой и местный трафики:

7.2. Тарифы на МГМН-связь

Более сложными в реализации являются тарифы МГМН-операторов. Тарифы каждого оператора должны быть реализованы в отдельном плане. Существуют два основных способа тарификации: зоновая и по префиксам.

7.2.1. Тарификация по префиксам

Тарификация по префиксам предполагает внесение в тарифный план дерева префиксов для разбора звонков. Логика тарифа полностью идентична приведённым выше тарифам на местную связь. Например, тариф может выглядеть таким образом:

При построении подобных тарифов целесообразно делать общее дерево префиксов, устанавливая в нем разбивку по направлениям, далее его клиентскими тарифами, определяя цены. Например, базовое дерево тарифов может выглядеть следующим образом.

В верхней части дерева заведены два набора ограничений определяющих 2 диапазона времени тарификации: обычное и льготное время. Далее в наследованном дереве определяются цены для каждого из диапазонов.

Вместо Набора ограничений в последних версиях биллинга можно также использовать Фильтр по типу времени. Также возможно использование узла Диапазон префиксов совместно с узлами типа Часть префикса.

Тариф Телефония Совинтел преселект - наследуется от базового тарифа в нем добавляются цены

В данном тарифе определяются цены звонка и виды услуг. Т.к. в данном тарифе встречаются звонки МГ и МН, то узлов установки услуги множество.

Тариф Телефония Совинтел преселект с НДС - наследуется от предыдущего, но в конце добавляется коэффициент умножения цены. Обратите внимание, что для того, чтобы он сработал, цены минут должны быть помечены галочкой По умолчанию.

7.2.2. Тарификация по зонам

В основу зоновой тарификации ложится карта зон, соотносящая коды из справочника географических кодов с зонами равной цены. Про построение карт зон вы можете почитать ранее. В тарифном плане с помощью узла Использовать карту зон указывается используемая карта и далее добавляются узлы Зона с указанием в каждой стоимости минуты и услуги.

7.2.3. Тарификация по карте цен

В основу этой тарификации ложится карта цен, соотносящая коды и правильные диапазоны из карты с ценами.В тарифном плане с помощью узла Карта цен указывается используемая карта. Если префикс найден в этой карте, то звонку также соотносится направление из георграфических кодов и выполняются дочерние узлы. Чтобы назначить цену из этой карты, внутри должен быть узел Стоимости с параметром "взять из карты цен".

7.2.4. Тарификация с несколькими МГМН-операторами

В случае когда МГМН-звонок клиента может быть терминирован на несколько операторов (преселект) встаёт проблема тарификации звонка с одинаковым конечным направлением, но разными ценами. Задача решается созданием отдельного тарифного плана для каждого из возможных операторов и установку их в договор клиента. При тарификации будут пройдены все тарифные планы до первого, в котором будет найдена цена, услуга и направление.

Для того, чтобы тарифный план отрабатывал только на "свои" звонки, можно использовать метод фильтрации по набранному номеру, либо по исходящему порту АТС.

В первом случае во все узлы Установка услуги дополнительно указывается REGEXP, совпадающий с преселект-набором данного оператора, например:

Во втором случае в начале тарифного плана устанавливается фильтр по портам АТС, исходящие звонки на которые относятся к данному оператору. Несколько портов могут быть указаны через запятую.

7.2.5. Импорт и экспорт тарифных планов голосовых модулей

Внимание

Допускается импорт и экспорт только независимых модульных поддеревьев. Т.е. эти тарифы не должны наследовать и не должны наследоваться от других тарифов.

Тарифные планы голосовых модулей позволяют делать экспорт дерева в XML-формат и загрузку. Для произведения выгрузки, либо загрузки необходимо выбрать корневой узел тарифного дерева для модуля телефонии, либо узел Услуга для модуля VoiceIP. Далее нажать правую кнопку мыши, выбрать пункт Выгрузка/Загрузка.

В появившемся окне выбрать файл и желаемое действие. Выбор Загрузить узел перетирает все подузлы и выгружает их из файла, Догрузить в узел добавляет узлы из файла за существующими подузлами.

Для того, чтобы определить формат, необходимо создать часть нужного тарифа и выгрузить его. Все названия направлений и зон в файле с выгрузкой идентифицируются по имени. Если при загрузке направление или зона не будут найдены - биллинг создаст их. Поэтому следует быть внимательными с регистром и пробельными символами.

Загрузка тарифов удобна для программной генерации тарифа с его последующей загрузкой.

7.3. Специфичные тарифные узлы модуля

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

7.3.1. Стоимость минуты

Редактор и узел в дереве выглядят следующим образом:

В первом выпадающем списке редактора задаётся стоимость либо минуты, либо звонка, в зависимости от того, что необходимо. Во втором списке выбирается символ "=", либо взять из CDR, что позволяет задать стоимость в узле дерева, либо указать необходимость взятия её из CDR-записи поля Стоимость звонка.

Установленная галочка По умолчанию определяет, что цена в запросе переопределяется только в случае, если она не установлена узлом по умолчанию предка. Если цена установлена безусловно, либо узлом по умолчанию в этом же дереве, она не переопределяется.

7.3.2. Фильтр по портам

Редактор и узел в дереве выглядят следующим образом:

Фильтр пропускает запрос внутрь только, если исходящий порт вызова попадает в перечень.

7.3.3. Установка услуги

Редактор и узел в дереве выглядят следующим образом:

Узел помещает в тарифный запрос услугу. Поле REGEXP B позволяет задать REGEXP-выражение, с которым будет сравниваться набор клиента, услуга будет установлена только при совпадении регулярного выражения.

7.3.4. Диапазон наработки

Редактор и узел в дереве выглядят следующим образом:

Фильтр пропускает запрос внутрь только, если наработка поинта по указанной зоне лежит в указанном диапазоне. При выборе пропорционально периоду объёмы определяются пропорционально доле в месяце периода действия поинта.

7.4. Отчёты в клиенте

Для вывода любого отчёта необходимо выбрать месяц и поинты и нажать кнопку с галочкой. Для выбора доступны только те поинты, период которых пересекается с выбранным периодом. Если фильтр по поинту не установлен, то выводится отчёт всех поинтов договора.

Возможна установка фильтра на вывод только платных звонков. Для сохранения, печати или отправки на почту отчёта нажмите кнопку с принтером, дискетой или конвертом.

В нижней области каждого отчёта отображаются количество сессий, суммарная длительность и стоимость. Многостраничные отчёты перематываются стандартным элементом управления.

7.4.1. Сессии

Многостраничный отчёт выводит сессии выбранного поинта (поинтовов) за выбранный месяц. Сортировка - по времени звонка. Может быть сохранен в HTML и CSV-формате. Оформление задаётся шаблонами phone_login_sessions.xsl и phone_login_sessions_csv.xsl соответственно. Для сохранения больших отчётов рекомендуется CSV-формат. HTML-отчёт также может быть отправлен на почту, либо распечатан.

При двойном клике по строке с сессией отображается строка из исходного CRD-лога, по которому была создана данная сессия.

7.4.2. Наработка

Одностраничный отчёт выводит суммарное количество звонков, длительность и стоимость сессий с группировкой по поинтам. Может быть сохранен в HTML и CSV-формате, распечатан, либо отправлен на почту. Шаблоны преобразования - phone_login_direct.xsl, phone_login_direct_csv.xsl.

7.4.3. Направления

Одностраничный отчёт выводит суммарное количество звонков, длительность и стоимость сессий с группировкой по поинтам и направлениям. Может быть сохранен в HTML и в CSV-формате, распечатан, либо отправлен на почту. Шаблоны преобразования в HTML - phone_login_direct.xsl, phone_login_direct_csv.xsl. При двойном клике по строке таблицы выводится отчёт по сессиям с фильтром по выбранному в строке поинту и направлению.

7.4.4. Услуги

Одностраничный отчёт выводит суммарное количество звонков, длительность и стоимость сессий с группировкой по поинтам и услугам. Может быть сохранен в HTML и в CSV-формате, распечатан, либо отправлен на почту. Шаблон преобразования в HTML - phone_login_service.xsl, phone_login_service_csv.xsl. При двойном клике по строке таблицы выводится отчёт по сессиям с фильтром по выбранному в строке поинту и услуге.

7.4.5. Детализация

Отчет выводит сессии, собранные в следующем формате:

Услуга А
Номер телефона А
Сессия 1
Сессия N
Итого по номеру A: количество, минут, рублей
Номер телефона B
Сессия 1
Сессия K
Итого по номеру B: количество, минут, рублей
Итого по услуге B: количество, минут, рублей
Услуга B....

При переходе отчёта по услуге, либо отчёта по номеру на несколько страниц, строки с суммами повторяются на каждой странице отчёта. Номера телефонов берутся непосредственно из звонков, привязанных к поинтам договора.

Отчет может быть сохранен в HTML и CSV-форматах. HTML-формат может быть распечатан или отправлен на почту. Шаблоны преобразования в HMTL и CSV - phone_login_service_sessions.xsl и phone_login_service_sessions_csv.xsl соответственно.

7.4.6. Входящие сессии

Учет входящих сессий производится только при установке в конфигурации модуля переменной store.incoming.calls=1.

7.5. Отчёты в Web-интерфейсе

Логика отчётов абсолютно идентична отчётам в клиенте биллинга.

8. Учёт операторского трафика

8.1. Редактирование правил

Для подключения модуля телефонии в договор добавьте одну или несколько услуг модуля к договору. Для модуля телефонии в данный момент наличие той или иной услуги модуля в договоре кроме подключения модуля к договору не означает.

Понятие правила в модуле означает фильтр, извлекающий звонки определённого типа из потока звонков первичного лога. Правила, как и поинты, привязываются к договору на соответствующей вкладке. Для редактирования используется собственная панель инструментов, расположенная над таблицей.

Имя правила формируется из АТС + привязанной услуги, либо используется алиас, если он указан.

Обязательными к заполнению являются код услуги, АТС, к которой привязано правило. Период действия правила влияет на выбор правил, участвующих в обработке лога за конкретную дату. Алиас используется для ввода идентификатора правила, если алиас не введён, правило называется в виде Услуга + АТС.

Правило представляет из себя набор полей фильтров, связанных условием И. Т.е. звонок будет отнесён к правилу только при совпадении всех заполненных в нем фильтров. Фильтры применяются к полям CDR, описанным в формате лога.

В качестве фильтров могут быть указаны:

1) REGEXP-маска номера B.164 и A.164 из первичной информации;

2) REGEXP-маски, под которые не должны подпадать номера B.164 и A.164 (исключающие шаблоны)№

3) порты (см. формат первичного лога) исходящие и входящие через запятую, условие срабатывает при совпадении порта хотя бы с одним из перечисленных;

4) диапазоны префиксов A.164 и B.164 номеров.

Диапазоны префиксов указываются следующим образом: <общий префикс>|диапазоны, либо единичные префиксы через запятую.

В приведённом на скриншоте примере указаны префиксы 735128-735129,73512478,73512479

5) диапазоны префиксов, в которые не должны попадать A.164 и B.164 номера.

Обработка правил производится для каждой CDR-записи часового лога после обработки поинтов. Производится последовательный просмотр правил, привязанных к обрабатываемой АТС и действующих в сутки, к которым относится лог. Обработка происходит по следующему алгоритму:

Как видно из схемы, в отличие от поинтов, в тарифном плане оператора указываются только услуги и цены за минуту. Например, тариф оператора может выглядеть так:

При заведении операторских договоров необходимо руководствоваться следующей логикой: правила добавляются тому, кто должен.

Например, мы завершаем звонки на некого оператора через 5-ый порт некой АТС. Заводится договор ОПЕРАТОР Я. В редакторе модулей и услуг добавляется услуга "Завершение на некого оператора". В правилах договора ОПЕРАТОР Я прописывается, что звонок на "некой АТС" с любого порта на 5-ый есть услуга "Завершение на некого оператора". В тарифе определяется стоимость данной услуги.

В результате в договоре ОПЕРАТОР Я будет наработка по услуге "Завершение на некого оператора" - ваш долг данному оператору за предоставленную им услугу.

В случае когда ОПЕРАТОР Х завершает на вас и подключён он через некоторые порты АТС Y, то зачастую проще рассмотреть оператора как клиента, тем более, если стоимость завершения разнится на разные префиксы. В этом случае заводится поинт на данные порты и далее тарифы как для клиента, но установка услуги производится "Завершение на Z".

Услуга инициации вызова для какого-либо оператора решается также правилом. Но т.к. за данную услугу платит оператор вам, то правило добавляется в договор оператора.

Внимание

При использовании в договоре одновременно поинтов и правил необходимо, чтобы тарифы правил по позициям были выше тарифов поинтов, иначе правило может обсчитаться по тарифу поинта.

8.2. Отчёты операторов

Для операторских правил доступны все отчёты поинтов за исключением отчёта по направлениям, т.к. операторским сессиям не сопоставляются направления. При сохранении больших отчётов по сессиям следует использовать исключительно CSV-формат.

8.3. Транзитные операторы

С точки зрения биллинга настройка тарификации транзитных операторов не отличается от настройки и тарификации операторских правил, за исключением того, что при тарификации в тарифе доступны узлы-префиксы, карта зон, т.е. возможно тарифицировать операторов по направлениям.

8.4. Операторские отчеты

8.4.1. Общие сведения

В модуле телефонии возможно генерировать отчеты операторам дальней связи по агентским договорам. Форматы отчётов "зашиты" в модуле, для добавления поддержки новых операторов обратитесь к разработчикам. Поддержаиваемые форматы очётности:

Комстар;
Совинтел (Вымпелком);
МТТ;
Инфолада.

Описание поддерживаемых форматов вы можете найти на странице WiKi.

Генерация отчётности осуществляется на вкладке Операторы модуля.

Для каждого оператора в конфигурацию модуля добавляются записи с ключами вида operator.<n>.<param_rest>, описывающие коды параметров, тарифов и прочую информацию для выгрузки отчётности.

Где:

<n> - уникальный числовой код оператора в конфигурации;
<param_rest> - наименование параметра

Отчёты из перечня операторской отчётности можно либо загрузить, либо просмотреть и распечатать прямо в интерфейсе клиента. В последующих разделах описывается настройка конфигурации для поддержанных форматов отчётности. Некоторые отчёты требуют выполнения при каждом съёме срезов абонентской базы.

8.4.2. Совинтел (ВымпелКом)

Поддержаны отчёты:

Изменения по абонентам.
Отчетность по абонентам.
Отчет о реализованных услугах.
Акт сдачи-приемки услуг.

Параметры конфигурации оператора.

# Наименование оператора
operator.<n>.title=ВымпелКом
operator.<n>.class=bitel.billing.server.phone.oper.bean.sovintel.Operator
# Ваш код оператора, число
operator.<n>.code=
#
# Дата заключения договора с оператором
operator.<n>.contract.date="01" января 2006 г.
operator.<n>.min.account=
operator.<n>.act.city=Москва
operator.<n>.act.preamble=ООО «СЦС Совинтел» (далее - «Совинтел»), в лице Коммерческого директора ..., действующего на основании Доверенности №Р001/01/01 от «01» сентября 2006 г., с одной стороны, и ... (далее - «Оператор»),  в лице  Генерального директора ..., действующего на основании Устава, совместно именуемые «Стороны», а по отдельности – «Сторона», составили настоящий Акт сдачи-приемки услуг о нижеследующем:
operator.<n>.act.report.date="1" июля 2006 г.
#
# Привязка услуг оператора (10, 12, 14) к услугам в биллинге
# международная
operator.<n>.service.10=
# междугородняя
operator.<n>.service.12=
# внутризоновая
operator.<n>.service.14=
# Режим субдоговоров (договоры в биллинге являются субдоговорами с независимым балансом)
operator.<n>.subContract=1
# Коды мг/мн тарифов, через запятую
operator.<n>.tariff.list=
#
# Код экземпляра модуля бухгалтерии (для отчета BIL)
operator.<n>.bill.moduleId=
# Привязка позиций счета-фактуры к кодам услуг оператора (10, 12, 14), пример: 500:14,501:12,502:10
operator.<n>.bill.positions=
operator.<n>.lastPayDay=20
# Номер договора оператора в биллинге
operator.<n>.contract=FW000
#
# Код(ы) параметров договора через запятую: название/фио
operator.<n>.param.name=
# Код(ы) параметров договора адрес через запятую, пример: 25,27
operator.<n>.param.address=
# Код параметра договора ИНН
operator.<n>.param.inn=
# Код параметра договора КПП
operator.<n>.param.kpp=
# Код параметра договора типа флаг "Дипломат"
operator.<n>.param.diplomat=
# Код параметра договора типа флаг "Не является резидентом РФ"
operator.<n>.param.notResident=
# Код параметра "Информации"
operator.<n>.param.info=
operator.<n>.country.code=
operator.<n>.location.code=

8.4.3. МТТ

Поддержаны отчёты:

Объем услуг междугородней связи, оказанных автоматическим способом (по направлениям);
Объем услуг международной связи, оказанных автоматическим способом (по направлениям);
Детализация уступаемых прав требования по оплате услуг связи.

Параметры конфигурации оператора.

# Наименование оператора
operator.<n>.title=МТТ
operator.<n>.class=bitel.billing.server.phone.oper.bean.mtt.Operator
#
# Коды услуг МГ для отчета по уступке прав
operator.<n>.yield_rights.mg.sids=
# Коды услуг МН для отчета по уступке прав
operator.<n>.yield_rights.mn.sids=
# Группы договоров через запятую
operator.<n>.contract_groups=
# Договор - номер договора
operator.<n>.yield_rights.contract=title
# или параметр договора
# yield_rights.contract.pid=
# ФИО - комментарий договора
operator.<n>.yield_rights.name=comment
# или параметр договора
# yield_rights.name.pid=
#
# Коды услуг мг через запятую
operator.<n>.service.mg.sids=
# Тип генерации отчета - по карте зон
operator.<n>.service.mg.mode=zone_map
# Код карты зон
operator.<n>.service.mg.mapId=
# Regexp для номера B (E.164)
operator.<n>.service.mg.regexp=^([012345689].*|771|772|7700|7701|7702|7705|7707|7760|7761|7762|7763|7777)
# Regexp-исключение для номера B (E.164)
operator.<n>.service.mg.notRegexp=
# Lополнительные условия
#operator.<n>.service.mg.exception.1.code=
#operator.<n>.service.mg.exception.1.regexp=
#operator.<n>.service.mg.exception.1.notRegexp=
#
# Коды услуг мн через запятую
operator.<n>.service.mn.sids=
# Тип генерации отчета - по карте зон
operator.<n>.service.mn.mode=zone_map
# Код карты зон
operator.<n>.service.mn.mapId=
# Regexp для номера B (E.164)
operator.<n>.service.mn.regexp=
# Regexp-исключение для номера B (E.164)
operator.<n>.service.mn.notRegexp=^([012345689].*|771|772|7700|7701|7702|7705|7707|7760|7761|7762|7763|7777)
# Дополнительные условия
#operator.<n>.service.mn.exception.1.code=
#operator.<n>.service.mn.exception.1.regexp=
#operator.<n>.service.mn.exception.1.notRegexp=

8.4.4. Комстар

Поддержаны отчёты:

Форма 41;
Форма 42;
Форма 1.7;
Форма 1.7 условная стоимость.

Параметры конфигурации оператора.

# Наименование оператора
operator.<n>.title=Комстар
# Класс оператора
operator.<n>.class=ru.bitel.bgbilling.modules.phone.server.oper.komstar.Komstar
# Ваш код оператора
operator.<n>.oper.code=VTKM
#
# Тут своебразная "заглушка", без нее не работает, ни на что в данном случае не влияет, уберем позже
operator.<n>.service.1=100500
#
# Код модуля бухгалтерии
operator.<n>.bill.module.id=5
# Код услуги "Междугородная связь" для Комстар (нужно для формы 1.7)
operator.<n>.service.mg=0
# Код услуги "Международная связь" для Комстар (нужно для формы 1.7)
operator.<n>.service.mn=0
# Код услуги "Внутризоновая связь" для комстар (нужно для формы 1.7)
operator.<n>.service.vz=264
#
#--------------------------------------
# Форма 4.1
#--------------------------------------
# Тип(ы) счетов-фактур, которые должны попадать в отчет 4.1 (числа через запятую), если не указано - идут все
operator.<n>.form.41.invoice.types=
# Далее коды параметров с ИНН, КПП, юридическим адресом и наименованием организации соответственно:
operator.<n>.form.41.inn.pid=
operator.<n>.form.41.kpp.pid=
operator.<n>.form.41.address.pid=
operator.<n>.form.41.title.pid=-1
#
# Сводная СФ для населения
operator.<n>.form.41.fz.need.total=1
operator.<n>.form.41.fz.contract.title=100000
operator.<n>.form.41.fz.invoice.title=01#111
#
#--------------------------------------
# Форма 4.2
#--------------------------------------
# Типы счетов-квитанций для формы, коды через запятую
# id типа счета - квитанции комстар 17
operator.<n>.form.42.bill.types=
# Коды параметров договора ИНН, адрес и ФИО
operator.<n>.form.42.inn.pid=
operator.<n>.form.42.fio.pid=
operator.<n>.form.42.address.pid=

9. Тарификация при работе по агентской схеме

Агентская схема предполагает, что клиент, совершая звонки, может потреблять услуги нескольких операторов, с которыми у оператора местной связи, обслуживающего клиента, заключены агентские договора. Наработка одного и того же телефонного номера должна быть отнесена к различным договорам, по каждому из которых, в общем случае, ведется свой баланс и работа с задолженностью.

Для поддержки агентской схемы в модуле телефонии используются независимые субдоговоры. Номер абонента добавляется на супердоговор, одновременно являющимся договором на услуги местной связи. В супердоговор заносятся тарифные планы на местную связь.

Далее к супердоговору соотносят один или несколько независимых субдоговоров с тарифами конкретных операторов. Номера супердоговора "наследуются" субдоговором, период субдоговора определяет период отношений данного оператора с клиентом.

При тарификации последовательно просматриваются тариф основного договора и тарифы всех независимых субдоговоров, исходя из чего звонок соотносится либо к супердоговору (местный звонок, отработал тариф местной связи), либо к одному из субдоговоров. На снимках экрана ниже изображена связка супердоговор-субдоговор, тарифы и отчеты в каждом из них.

9.1. Составление тарифов при агентской схеме

В тарифном плане тарифа агентского договора может быть дополнительно указана ссылка на тариф, используемый для вычисления цены для оператора-агента, по которым он приобретает трафик. По сути, это цена, по которой "продает" трафик оператор дальней связи и на которую в дальнейшем производится наценка оператором-агентом.

Для этого используется узел тарифа Тарифицировать оператора. В операторском тарифе необходимо указать правила округления и цену. Вычисленное время сессии для оператора и стоимость для оператора используются для предоставления отчетности и вычисления агентского вознаграждения.

9.2. Отчетность

10. Отключение абонентов.

Для отключения абонентов используется статус модуля Phone. Этот статус можно менять вручную в договоре. При этом отработает скрипт смены статуса модуля Phone, который пошлет на АТС команды на закрытие абонента

Статус модуля Phone зависит от статуса договора . Типичаня схема отключения должников: зайти в Монитор статуса , отфильтровать должников и поменять им статус договора. При этом произойдет смена статуса модуля Phone и отработает скрипт.

Потом по событию прихода платежа биллинг открывает статус договора , что также влечет за собой открытие статуса Phone.

Для настройки отключения абонетов делаем следующие шаги:

1) В настройках моудля Phone на Вкладке Шлюзы->Типы добавляем новый тип шлюза .

Тут мы задаем название, коментарий, конфигурацию и код шлюза на BeanShell

void doSync()
{
  // тут пишем код сихронизации с АТС.
}

В этом скрипте доступны объекты :

con - объект типа java.sql.Connection - соединение с БД;

gate - объект типа ru.bitel.bgbilling.modules.phone.common.bean.Gate - данные шлюза;

log - объект типа org.apache.log4j.Logger для логирования;

mid - код модуля телефония;

cid - код договора, для которого вызван скрипт;

status - статус договора (0 - открыт, 1 - закрыт ).

2) Добавляем шлюз на вкладке Шлюзы->Шлюзы

Тут задается хост, порт , ключевое слово, коментарий,конфигурация, тип шлюза (создан на предыдущем шаге).

3) Добавляем шлюз в договор.

Теперь мы можем менять статус модуля Phone, при этом история смены статусов для каждого шлюза отображается в таблице справа . Лог выполнения скрипта можно посмотреть с помощью двойного щелчка мыши по конкретной строке таблицы.

11. Web-интерфейс

Через Web-интерфейс модуля Phone имеется возможность просмотра сессий, наработки, наработки по направлениям, наработки по услугам, детализации и входящих звонков клиента по поинтам или правилам. Используя фильтры по дате, можно просмотреть интересующие данные как за конкртеный день, так и за целый месяц.

Для просмотра сессий телефонии нужно выбрать поинты/правила, указать период. Если необходимо вывести только платные сессии, то нужно поставить галочку. Отчет по данному пункту можно загрузить с этой страницы, нажав на формат, в котором будет сформирован отчет.

Для просмотра наработки по телефонии нужно выбрать поинты/правила, указать период. Если необходимо вывести только платные сессии, то нужно поставить галочку. Отчет по данному пункту можно загрузить с этой страницы, нажав на формат, в котором будет сформирован отчет.

Для просмотра наработки по направлениям нужно проделать те же действия, что и в просмотре наработки по телефонии.

Для просмотра наработки по услугам нужно проделать те же действия, что и в просмотре наработки по телефонии. Отчет по данному пункту можно загрузить с этой страницы, нажав на формат, в котором будет сформирован отчет.

Для просмотра детализации по телефонии нужно выбрать поинты/правила, указать период. Если необходимо вывести только платные сессии, то нужно поставить галочку. Отчет по данному пункту можно загрузить с этой страницы, нажав на формат, в котором будет сформирован отчет. Отчет по данному пункту можно загрузить с этой страницы, нажав на формат, в котором будет сформирован отчет.

Для отображения пунка "Входящие звонки" в Web-интерфейсе необходимо в конфигруации модуля добавить следующее:

web.incommingCall=true
web.incommingCall.exception=2,3

Значение web.incommingCall может быть true или false. Соответственно, если указано true, то данный пунк будет виден для всех, а если false - то ни для кого. Значение web.incommingCall.exception - это исключение из правила выше, т.е. если стоит значение true в web.incommingCall, а в исключении перечислены id групп договоров, то для перечисленных групп договорв данный пункт в Web-меню не будет отображен, и наоборот, соответственно.

Для просмотра входящих звонков по телефонии нужно выбрать поинты, указать период.

Для изменения логики отображения поинтов/правил можно в конфигурации прописать:

# Какие поинты/правила показывать в web в "наработках" разных.
# В зависимости от параметра web.item.list.content.mode делаем разные выборки
# "all" - все выбираем поинты/правила (0...+бесконечность)
# "last" - только последние (прошлый месяц...+бесконечность) - сейчас так по умолчанию
# "currperiod" - выбираем только за заданный промежуток в web (от...до) 
web.item.list.content.mode=currperiod

12. Черно-белые списки.

Опционально доступен функционал черно-белых списков. Включить его можно в конфигурации. Пользователь сам может определять номера, вызовы с которых на его телефонный номер запрещены (черный список) или, наоборот, разрешены (белый список). На одном номере абонента можно включить либо черный, либо белый список. Управление оборудованием (АТС) осуществляется глобальным скриптом поведения, запускаемым по таймеру, который разрабатывается уже под конкретную АТС.

При редактировании поинта в клиенте доступна вкладка "Управление списками"

Тут можно добавлять/удалять/редактировать номера телефонов и выбрать тип списка - черный или белый.

Аналогичный интерфейс доступен абоненту в личном кабинете:

Синхронизация черно-белых списков с АТС осуществляется с помощью глобального скрипта поведения. Вот примерная структура скрипта:

import bitel.billing.server.util.*;
import ru.bitel.bgbilling.modules.phone.server.bean.*;
import ru.bitel.bgbilling.modules.phone.common.bean.*;
import java.util.*;
import java.net.*;
import java.io.*;

int mid = 0;
public void main( setup, con, conSlave )
{
	con.setAutoCommit( false );
	PhoneItemListManager pilm = new PhoneItemListManager( mid, con );
	
	//получаем измененные режимы
	List changedModes = pilm.getToUpdateModes();
	for( PhoneItemListMode mode : changedModes )
	{
		updateModeOnBackend( mode );
		mode.setNewMode( false );
		pilm.updateMode( mode );
	}

	//получаем далее удаленные из списка номера
	List deletedNumbers = pilm.getToDeleteNumbers();
	for( PhoneItemListNumber number : deletedNumbers )
	{
		deleteNumberOnBackend( number );
		pilm.deleteNumber( number );
	}

	//наконец, получаем добавленные номера
	List addedNumbers = pilm.getToUpdateNumbers();
	for( PhoneItemListNumber number : addedNumbers )
	{
		addNumberOnBackend( number );
		number.setNewNumber( false );
		pilm.updateNumber( number );
	}
	con.commit();
}

//функция реального изменения состояния на АТС
private void updateModeOnBackend( PhoneItemListMode mode )
{
	URL example = new URL("http://www.example.com/");
	URLConnection yc = example.openConnection();
 	//TODO
}

//фунцкия реального удаления номера на АТС
private void deleteNumberOnBackend( PhoneItemListNumber number )
{
	URL example = new URL("http://www.example.com/");
	URLConnection yc = example.openConnection();
	//TODO
}

//функция реального добавления номера на АТС
private void addNumberOnBackend( PhoneItemListNumber number )
{
	URL example = new URL("http://www.example.com/");
	URLConnection yc = example.openConnection();
	//TODO
}

Глава 28. Модуль PSB (Промсвязьбанк)

1. Назначение модуля

Модуль PSB предназначен для оплаты картами через процессинг Промсвязьбанка.

Модуль работает по защищенному протоколу https с использованием шифрования SSL, что исключает возможность перехвата информации и нарушения целостности данных третьими лицами.

2. Настройка модуля

Установите модуль на сервер, обновите клиент. Затем создайте экземпляр модуля. Создайте в редакторе конфигурации модуля новую конфигурацию, пропишите необходимые параметры. После этого сохраните конфигурацию и сделайте её активной.

Глава 29. Модуль Qiwi

1. Назначение модуля

Модуль Qiwi предназначен для проведения платежей с использованием кошелька в системе Qiwi. Для проведения платежей вашими абонентам у вас должен быть заключен договор с системой.

2. Настройка модуля

Установите модуль на сервер, обновите клиент. Затем создайте экземпляр модуля. Создайте в редакторе конфигурации модуля новую конфигурацию.

#Название пункта меню в кабинете статистики
web.menuItem1=Оплата с помощью кошелька Qiwi
#Логин провайдера в системе Qiwi. Выдается системой после заключения договора
qiwi.login=123456
#Пароль провайдера в системе Qiwi
qiwi.password=password
#Комментарий платежа
qiwi.comment=Оплата с помощью кошелька Qiwi
#Формат строки, которая идентифицирует транзакцию
qiwi.transaction.format=BG00000000
#Идентификатор типа платежа из справочника типов платежей
qiwi.payment.type=1
#Адрес, куда будет перенаправлен клиент при успешной оплате
qiwi.success.url=http://www.bgbilling.ru
#Адрес, куда будет направлен клиент в случае неудачной оплаты
qiwi.fail.url=http://www.bgbilling.ru
#Идентификатор параметра договора, по которому можно дополнительно идентифицировать договор. 
#По этому параметру можно осуществлять поиск платежей в мониторе транзакций
qiwi.additional.identify.key.pid=1

После этого сохраните конфигурацию и сделайте её активной.

Замечания:

  1. Прежде, чем задавать qiwi.payment.type, необходимо создать соответствующий тип платежа в Справочнике (Справочники->Другие->Типы платежей).

  2. Номер транзакции создается следующим образом: берется ID транзакции из таблицы qiwi_transaction_<mid> и соединяется с шаблоном. Например: если шаблон "BG0000", а ID пусть будет 34, тогда номер транзакции, отсылаемый в Qiwi, будет иметь вид: BG0034.

  3. После заключения договора с системой необходимо зайти в свой личный кабинет провайдера на стороне Qiwi и в настройках подключения в разделе SOAP ввести адрес веб-сервиса на стороне биллинга, на который будет приходить информация по статусу счета. Этот адрес формируется следующим образом: http://<адрес_машины_биллинга>/bgbilling/qiwiexecuter/ru.bitel.bgbilling.modules.qiwi/<код_модуля_Qiwi>/IShopClientWS. Например, если у вас биллинг находится по адресу http://billing.example.com/bgbilling/ и модуль Qiwi имеет mid=16, то результирующий URL, который нужно ввести в личном кабинете, выглядит следующим образом: http://billing.example.com/bgbilling/qiwiexecuter/ru.bitel.bgbilling.modules.qiwi/16/IShopClientWS.

3. Оплата через кошелек Qiwi

Если у клиента подключен экземпляр модуля в дереве договора, то он может осуществлять оплату через свой Qiwi-кошелек, используя личный web-интерфейс.

В личном кабинете на странице отображается история платежей, совершенных клиентом:

Над таблицей с историей платежей расположена форма для совершения нового платежа. Чтобы осуществить платеж, необходимо заполнить обязательные поля Сумма и Телефон. Далее необходимо нажать кнопку Создать счет и подтвердить создание счета. После подтверждения клиент попадает на страницу системы Qiwi, где ему необходимо авторизоваться и подтвердить созданный счет с помощью своего мобильного телефона.

В случае успеха, клиент будет перенаправлен на страницу, указанную в конфигурации модуля в параметре qiwi.success.url.

4. Мониторинг платежей

В клиенте билинга есть возможность отслеживать историю платежей по каждому абоненту. Для этого необходимо выбрать модуль Qiwi в дереве параметров договора. Здесь присутствует фильтр по статусу платежей (оплаченные, выставленные, проводимые, отмененные, все) с указанием периода, когда производилась оплата.

Для просмотра ВСЕХ платежей, проведенных с использованием модуля Qiwi, существует глобальный монитор транзакций в параметрах модуля (Модули -> Модуль Qiwi). На открывшейся вкладке у Вас есть возможность просмотреть все платежи, совершенные вашими абонентами за указанный временной период. Также можно установить фильтр платежей по группам договоров, по имени договора, по статусу, а также по произвольному текстовому параметру договора, по которому можно идентифицировать договор (например, в параметре договора хранится ИНН абонента, его расчетный счет и т.п. ). В последнем случае код параметра договора задается в конфигурации модуля в опции qiwi.additional.identify.key.pid.

Глава 30. Модуль RBK.Money

1. Назначение модуля

Модуль RBK.Money предназначен для проведения платежей через платежную систему RBK.Money c использованием пластиковых карт. Для проведения платежей Вашими клиентами у Вас должен быть заключен договор с системой.

Модуль работает по защищенному протоколу https с использованием шифрования SSL, что исключает возможность перехвата информации и нарушения целостности данных третьими лицами.

2. Настройка модуля

Установите модуль на сервер, обновите клиент. Затем создайте экземпляр модуля. Создайте в редакторе конфигурации модуля новую конфигурацию, скопируйте туда приведённый ниже текст и введите требуемые параметры. После этого сохраните конфигурацию и сделайте её активной.

#Название пункта меню в Web-интерфейсе (по умолчанию "Оплата через RBK.Money")
#web.menu=Оплата через RBK.Money

#Код продавца (выдается после заключения договора с RBK.Money)
rbkmoney.eshop.id=

#ваш секретный ключ (выдается после заключения договора с RBK.Money)
rbkmoney.private.security.key=

#URL, на который осуществляетя перевод для оплаты ("/" в конце не нужен)
rbkmoney.online.url=https://secure.payonlinesystem.com/ru/payment

#Код типа платежа, которыми будут зачисляться платежи
rbkmoney.payment.type=

#URL возврата, на который будет возвращать клиента после платежа
rbkmoney.success.url=
rbkmoney.fail.url=

#Минимальная разрешенная сумма платежа
rbkmoney.min.summa=100

#Максимальная разрешенная сумма платежа
rbkmoney.max.summa=3000

#Заголовок чека (может быть несколько таких связок)
#pdf.check.title.1.regex=^Pech+$
#pdf.check.title.1.title=Good

#Замена комментария по умолчанию к платежам
#Простой платеж
usual.comment="Простой платеж"
#тип комиссии 0-без комиссии, 1- с суммы, 2- сверх суммы
#rbkmoney.commission.type=2
#rbkmoney.commission.percent=2
#rbkmodey.commission.charge.type.id=64


Замечания:

  1. Прежде, чем задавать rbkmoney.payment.type.id необходимо создать соответствующий платеж в Справочники->Другие->Типы платежей

  2. Параметры rbkmoney.success.url и rbkmoney.fail.url будет выглядеть следующим образом: http://<адрес_машины_биллинга>/rbkmoney/<mid>. Например, если у вас биллинг находится по адресу http://billing.example.com/bgbilling/ и модуль RBK.Money имеет mid=16, то результирующий URL, который нужно дать компании PayOnline, выглядит следующим образом: http://billing.example.com/bgbilling/rbkmoney/16.

3. Оплата через систему PayOnline

Для предоставления возможности клиенту платить банковской картой через платежный шлюз RBK.Money необходимо подключить данный модуль к договору клиента. В Web-интерфейсе клиента появится новый пункт в меню - Оплата через RBK.Money (название по умолчанию).

На изображении приведен Web-интерфейс клиента. Цифрами обозначены следующие области:

  1. Суммы минимального и максимального платежей, которые настраиваются в конфигурации модуля;

  2. Поле для введения суммы платежа;

  3. Фильтр платежей и сами платежи.

4. Простой платеж

Для совершения простого платежа необходимо ввести необходимую сумму в поле 2 и нажать кнопку Оплатить. Далее клиент попадает на страницу подтверждения оплаты. На данном этапе уже сформирован запрос на платежный шлюз и от клиента требуется нажать на кнопку Да для продолжения оплаты, либо Отмена для отмены платежа.

В случае, если клиент подтверждает оплату, то он перенаправляется на платежный шлюз, где может ввести информацию о своей пластиковой карте. Правильно заполнив предложенную форму и нажав кнопку Оплатить, клиент будет уведомлен о результате платежа.

В случае положительного результата биллинговая система начислит клиенту указанную им сумму на счет в виде нового платежа договора.

5. Мониторинг платежей

В клиенте билинга есть возможность отслеживать историю платежей по каждому абоненту. Для этого необходимо выбрать модуль RBK.Money в дереве параметров договора. Здесь присутствует фильтр по типу платежа с указанием периода, когда производилась оплата. Для просмотра ВСЕХ платежей, проведенных через систему RBK.Money, существует глобальный монитор в параметрах модуля. В открывшейся вкладке Проведенные платежы модуля RBK.Money у Вас есть возможность просмотреть платежи с учетом фильтра по типу платежа и указанному периоду, совершенные вашими абонентами.

По двойному клику левой кнопкой мыши на строке в таблице открывается соответствующий договор.

Глава 31. Модуль Reports

Модуль представляет из себя набор различных отчётов как по ядру системы, так и по модулям. Отказ от классической схемы генератора отчётов позволяет строить максимально оптимизированные и быстрые запросы в базу для каждого из отчётов, снижая тем самым нагрузку на сервер. При необходимости модуль позволяет разрабатывать недостающие отчёты самостоятельно силами клиента. Отчет можно экспортировать во внешние форматы - csv, xls, odt, ods, pdf, html.

1. Установка и настройка модуля

Достаточно проинсталлировать модуль с помощью утилиты bg_installer.sh (.bat), а затем создать его экземпляр в редакторе модулей и услуг.

2. Отчёты основного модуля

1. Отчет по договорам

Позволяет просмотреть существующие в системе договоры, фильтруя их по группам, виду лица (юридическое или физическое), статусу договора и другим критериям. Возможно отслеживание созданных, удалённых договоров.

Таблица 31.1. Фильтр и внешний вид

ФильтрВнешний вид

2. Отчет по платежам

Выводит принятые системой платежи с фильтрацией по типу, группе договора. Возможно использовать для анализа суммы поступлений, с фильтром по группам и типам. Также пригоден для сверки с кассой.

Таблица 31.2. Фильтр и внешний вид

ФильтрВнешний вид

3. Отчет по расходам

В целом идентичен отчёту по платежам, но выводит не платежи, а расходы, занесённые на договоры.

4. Отчет по наработке

Выводит наработку договоров выбранных групп за определённый месяц.

Таблица 31.3. Фильтр и внешний вид

ФильтрВнешний вид

5. Детализированный отчёт по наработке

Выводит наработку по договорам из выбранных групп.

Таблица 31.4. Фильтр и внешний вид

ФильтрВнешний вид

5. Отчет по тарифам

Выводит договоры, сгруппированные по тарифам . Доступен фильтр по договорам и дате тарифного плана.

Таблица 31.5. Фильтр и внешний вид

ФильтрВнешний вид

6.Наработка по тарифам

Выводит наработку по тарифам за выбранный месяц.

Таблица 31.6. Фильтр и внешний вид

ФильтрВнешний вид

Клик мышки по строке выводит детализацию по конкретному тарифу:

7.Отчет по должникам

Отчет выводит должников за определённый период. Фильтр и внешнее представление имеют вид:

Таблица 31.7. Отчет по должникам

ФильтрВнешний вид

Этот отчет не является встроенным в BGBilling и может быть изменён . Файлы отчёта - kernel_contract_debtor.rep.xml и kernel_contract_debtor.jrxml. О том, как создавать свои собственный отчёты читайте здесь.Тут возможны режимы: Сальдо по периоду и Текущий баланс.

В режиме Текущего баланса анализируется входящий остаток на начало месяца и исходящий остаток на конец месяца. При это должником считается тот, у кого исходящий остаток отрицательный. Оплатившим считается тот, у кого входящий остаток на начало месяца отрицательный, а исходящий остаток на конец месяца не отрицательный . В столбце Входящее сальдо показывается входящий остаток на начало месяца. В столбце Итоговое сальдо указывается исходящий остаток на конец месяца. В столбце Приход указывается сумма всех платежей (кроме платежей типа ГОРОД) с начала месяца по вторую дату (если на указана, то по текущее число). В столбце Приход (Город) указывается сумма всех платежей типа ГОРОД с начала месяца по вторую дату (если на указана, то по текущее число). Если договор является супердоговором, то при учёте платежей ему добавляются все платежи субдоговоров.

В режиме Сальдо по периоду анализируется входящий остаток на начало месяца и сальдо на конец месяца. Сальдо вычисляется как сумма входящего остатка на начало месяца и платежей в указанный период. Введём следующие обозначения:

incoming - входящий остаток на начало месяца;

payment_1_date1 - сумма всех платежей с начала до первой даты указанного периода (не включая её);

payment_date1_date2 - платежи в указанный период (включая границы);

saldo = incoming + payment_date1_date2 - сальдо.

Должником считается тот, у кого сальдо на конец периода отрицательное ( saldo < 0 ) . Оплатившим считается тот, у кого incoming + payment_1_date1 < 0 , а saldo >= 0 (т.е сумма входящего остатка на начало месяца и платежей до первой даты указанного периода (не включая её) отрицательное, а сальдо не отрицательное) . В столбце Входящее сальдо показывается incoming + payment_1_date1. В столбце Итоговое сальдо указывается сальдо. . В столбце Приход указывается payment_date1_date2 - (платежи типа ГОРОД в указанный период) . В столбце приход (Город) указывается сумма всех платежей типа ГОРОД в указанный период. Если договор является супердоговором, то при учёте платежей ему добавляются все платежи субдоговоров. В этом режиме нужно обязательно указать обе даты, иначе результат будет пустым.

В обоих режимах, если указано выводить всех, то выводятся все договора независимо от того оплатили они или являются должниками.

Для этого отчёта требуется настройка в конфигурации модуля (Модули->Отчёты->Конфигурация модуля):

#код параметра договора ФИО
report.contract_debtor.fio.pid=1
#код параметра договора телефон
report.contract_debtor.phone.pid=2
#код параметра договора адрес
report.contract_debtor.address.pid=3
#код типа платежа ГОРОД. можно указать 0, если он не используется отдельно. 
report.contract_debtor.gorod.pt=4
#Не обязательный параметр(можно не указывать). метод обрезания адреса . Остается то, что попадает в (). 
#report.contract_debtor.address.cut=г.Новосибирск,\s*(.*)

Эта настройка привязывает столбцы отчёта к реальным параметрам договоров и задаёт код типа платежа Город.

3. Отчёты модуля DialUP

1. Отчёт по услугам

Выводит наработку договоров по выбранным услугам в часах, либо мегабайтах.

Таблица 31.8. Фильтр и внешний вид

ФильтрВнешний вид

2. Отчёт Ситно 1

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

Таблица 31.9. Фильтр и внешний вид

ФильтрВнешний вид

3. Отчёт Dolphin 1

Позволяет посмотреть загрузку модемного, либо VPN-пула по количеству одновременных соединений с заданным шагом.

Таблица 31.10. Фильтр и внешний вид

ФильтрВнешний вид

4. Отчёт по сессиям

Позволяет просмотреть dialup-сессии клиентов. Для фильтрации по IP-адресу его нужно вводить полностью

Таблица 31.11. Фильтр и внешний вид

ФильтрВнешний вид

5. Отчёт Shturman 1

Позволяет просмотреть наработку по dialup + произвольным услугам

#В конфигурации модуля отчётов добавьте параметры
#параметры услуг dialup-услуга:делитель:еденица
#reports.shturman_1.sids=23:1048576:МБ;24:1024:КБ
reports.shturman_1.sids=
#
#добавочные услуги для отображения в модуле, через "," (например, услуга абонплаты)
#1,2,3
reports.shturman_1.addsids=

Таблица 31.12. Фильтр и внешний вид

ФильтрВнешний вид

Промежуточные итого по договорам выводят количество записей для данного договора.

6. Отчёт Телекей 1

Выводит наработку с группировкой по договорам и услугам . Он имеет 2 части, вначале выводится информация по услугам для каждого договора, потом информация по услугам для всех договоров.

Таблица 31.13. Фильтр и внешний вид

ФильтрВнешний вид

4. Отчёты модуля IPN

1. Отчет по трафику

Позволяет вывести объем трафика за выбранный месяц по группам договоров. Он имеет 2 части: вначале выводится информация по услугам для каждого договора, потом информация по услугам для всех договоров.

Таблица 31.14. Фильтр и внешний вид

ФильтрВнешний вид

2. Отчет Телекей 1.

Выводит наработку по трафику с группировкой по договорам и услугам.

Таблица 31.15. Фильтр и внешний вид

ФильтрВнешний вид

5. Отчёты модуля IP Телефония

1. Отчет по сессиям

Позволяет выбрать сессии за определённые период с фильтром по причине завершения (disconnect-cause). Этот отчёт предназначен, прежде всего, для мониторинга качества связи. Несколько DC могут быть введены через запятую.

Таблица 31.16. Фильтр и внешний вид

ФильтрВнешний вид

2. Отчет Чита-Он-Лайн 1

Позволяет просмотреть voip-сессии с фильтром по типу и группам договоров. В отличие от предыдущего отчёта техническая информация не отображается.

Таблица 31.17. Фильтр и внешний вид

ФильтрВнешний вид

6. Отчёты плагина CRM.

1. Отчет по проблемам

Позволяет отслеживать количество проблем, решённых различными исполнителями, а также количество проблем по категориям и типам.

Таблица 31.18. Фильтр и внешний вид

ФильтрВнешний вид

7. Отчёты модуля Телефония (Phone).

1. Отчет Dect 1.

Отчет выводит статистические данные по услугам телефонии . Для каждой услуги он выводит суммарное количество соединений, суммарную длительность соединений и сумму за указанный период. Доступна фильтрация по услугам и группам договоров.

Таблица 31.19. Фильтр и внешний вид

ФильтрВнешний вид

2. Отчет по направлениям.

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

Таблица 31.20. Фильтр и внешний вид

ФильтрВнешний вид

8. Отчёты модуля Карточки

1. Отчет по дилерам.

Выводит информацию по дилерам: количество карт на начало периода (Входящий остаток), количество карт? взятых дилером за период, количество активированных карт за период, количество карт на конец периода. Доступна фильтрация по периоду, стоимости карт (сумма), услугам, дилерам.

Таблица 31.21. Фильтр и внешний вид

ФильтрВнешний вид

9. Отчёты модуля RSCM

1. Отчет "Разовые услуги RSCM"

Отчет выводит начисленные разовые услуги по всем договорам за период. Отчет не является встроенным и может быть изменен. Файлы отчёта - rscm_contract_telenettv_rscm.jrxml и rscm_contract_telenettv_rscm.rep.xml.

Таблица 31.22. Фильтр и внешний вид

ФильтрВнешний вид

10. Отчёты модуля CerberCrypt

10.1. Отчет "Количество абонентов"

Выводит количество абонентов по пакетам.

10.2. Отчет "Наработка пакетов"

Выводит общую наработку по пакетам за определённый период месяца.

Таблица 31.23. Фильтр и внешний вид

ФильтрВнешний вид

11. Создание собственных отчетов

Для модуля отчетов возможно создание шаблонов двух видов: в формате JasperReports с помощью программы iReport и создание табличных отчётов.

Фильтр отчётов создаётся единым образом, меняется только их вывод.

Для того, чтобы сервер не кэшировал шаблоны отчётов добавьте в конфигурацию сервера (не модуля) параметр reports.cache=0.

Для того, чтобы скрыть "ненужные" отчеты из выпадающего списка с отчетами, необходимо удалить поле title в файле *.rep.xml (см. ниже).

11.1. Настройка фильтра

Создайте в директории сервера биллинга директорию reports. Создайте файл <модуль>_<id>.rep.xml, где <модуль> - название модуля, для которого создаётся отчёт: kernel (ядро, основной модуль), dialup, voiceip, bill, mps и т.д., а <id> - уникальное имя отчёта (рекомендуется добавлять суффикс, чтобы идентификатор не совпал с идентификаторами отчётов, которые входят/войдут в будущем в дистрибутив модуля).

В *.rep.xml хранится название отчёта и описание фильтра в виде xml-файла. Далее представлена структура файла и доступные фильтры:

<?xml version="1.0" encoding="UTF-8"?>
<report title="Мой отчёт">
  <month name="month" title="Месяц"/>
  <combo name="combo" title="ComboBox" textBefore="textBefore" textAfter="textAfter">
    <item id="0" title="-"/>
    <item id="1" title="Value 1"/>
  </combo>
  <checkedList name="name" title="title>
    <item id="0" title="title"/>
    <item id="1" title="item2"/>
  </checkedList>
  <textField name="textField" title="TextField" textBefore="textBefore" textAfter="textAfter"/>
  <contracts name="contracts"/>
  <date name="date" default="today"/>
  <hours name1="hours1" name2="hours2"/>
  <module name="servs" title="Услуги модулей">
  <monthAndDays name1="monthAndDays1" name2="monthAndDays2" title="Месяц и дни"/>
  <period name1="period1" default1="yesterday" name2="period2" default2="last_day_of_month"/>
  <contractGroups name="contractGroups" title="Группы договоров"/>
  <services name="services" title="Услуги"/>
  <paymentTypes name="paymentTypes" title="Типы платежей"/>
  <chargeTypes name="chargeTypes" title="Типы расходов"/>
  <tariffs name="tariffs" title="Тарифы"/>
  <tariffOptions name="tariffOptions" title="Тарифные опции"/>
  <tariffGroups name="tariffGroups" title="Группы тарифов"/>
  <registerCategories name="registerCategories" title="CRM - категории проблем"/>
  <registerExecutors name="registerExecutors" title="CRM - исполнители"/>
  <registerGroups name="registerGroups" title="CRM - группы решения"/>
  <users name="users" title="Пользователи"/>
  <nases name="nases" title="NASы"/>
  <dealers name="dealers" title="Дилеры"/>
  <cashcheckKKM name="kkm" title="ККМ"/>
  <inetDevices title="Выбор устройств" mid="<mid>", name="inetDevices" />
</report>

<!--
month - месяц
combo - combobox с указанием значений в дочерних элементах item, где title - выводимое значение, id - передаваемое значение
checkedList - отмечаемый список с указанием дочерних элементов item (аналогично combo)
textField - текстовое поле
contracts - выбор из открытых договоров
date - дата (default - для указания даты по умолчанию с использованием макроса)
hours - часы с по
module - услуги модулей с возможностью произвольной каталогизации
monthAndDays - месяц и дни (период в пределах одного месяца )
period - период (default1, default2 - для указания даты по умолчанию с использованием макроса)
contractGroups - группы договоров
services - услуги данного модуля
paymentTypes - типы платежей
chargeTypes - типы расходов
tariffs - тарифные планы
tariffOptions - тарифные опции
tariffGroups - группы тарифов
registerCategories - CRM категории проблем
registerExecutors - CRM исполнители
registerGroups - CRM группы решения
users - пользователи биллинга
nases - NASы модуля
dealers - Дилеры для модуля Карточки
cashcheckKKM - все настроенные принтеры в плагине cashcheck
inetDevices - выбор списка устройств заданного экземпляра модуля Inet с возможностью фильтрации
address - Адрес (город, улица, район, квартал, дом). Пример - <address cityName="city" streetName="street" houseName="house" title="Адрес"/> 
list - список (с галочками) с указанием значений в дочерних элементах item, где title - выводимое значение, id - передаваемое значение. Список поодерживает выбор нескольких значений
<hide title="name"></hide> - фильтры заключенные в эти теги скрываются и доступны по щелчку на title
макросы для даты: today - сегодня, yesterday - вчера, tommorrow - завтра, first_day_of_month - первый день месяца, last_day_of_month - последний день месяца.
 -->

report/@title - отображаемое в списке название отчёта (если имя пустое или отсутствует, то отчет не попадает в выпадающий список с перечнем отчетов).

Дочерние элементы report - фильтры отображаемые в клиенте. Например, фильтры, описанные выше будут выглядеть так:

Если фильтр большой и не помещается в высоту, то можно установить в элемент report атрибуты высоты и использования скроллинга. По умолчанию элементы фильтра располагаются друг под другом, последними размещаются фильтры-вкладки. Однако, можно изменять положение элементов фильтра атрибутами x и y - координатами фильтров по горизонтали и вертикали. Ниже приведён фрагмент кода rep.xml файла с установленными координатами фильтров и скроллированием.

<?xml version="1.0" encoding="UTF-8"?>
<report title="Отчет УСТ Интернет" scroll="true" height="1200">
<month name="month_from" title="Месяц с" width="4"/>
 <month name="month_to" title="Месяц по" width="4"/>

 <combo name="status" title="Статус" width="4">
  <item id="0" title="--Любой--"/>
  <item id="1" title="Статус 1"/>
  <item id="2" title="Статус 2"/>
 </combo>
 
 <address cityName="city" streetName="street" areaName="area" houseName="house" title="Адрес" width="4"/>
 <textField name="frac" title="Дробь" x="0" y="4"/> 
 <textField name="flat" title="Квартира" x="1" y="4"/>
 <textField name="room" title="Комната" x="2" y="4" width="2"/>
 <textField name="pod" title="Подъезд" x="0" y="5" width="2"/>
 <textField name="floor" title="Этаж" x="2" y="5" width="2"/>
 
 <textField name="inRestFrom" title="Вх. ост. от" x="0" y="6"/>
 <textField name="inRestTo" title="до" x="1" y="6"/>
 <textField name="outRestFrom" title="Исх. ост. от" x="2" y="6"/>
 <textField name="outRestTo" title="до" x="3" y="6"/>	
 <textField name="accountFrom" title="Наработка от" x="0" y="7" width="2"/>
 <textField name="accountTo" title="до" x="2" y="7" width="2"/>
 <textField name="payFrom" title="Плат. от" x="0" y="8"/>
 <textField name="payTo" title="до" x="1" y="8"/>
 <textField name="chargeFrom" title="Расх. от" x="2" y="8"/>
 <textField name="chargeTo" title="до" x="3" y="8"/>
 
 <textField name="trafVneshInFrom" title="Внеш. вх. от" x="0" y="9"/>
 <textField name="trafVneshInTo" title="до" x="1" y="9"/>
 <textField name="trafVneshOutFrom" title="Внеш. исх. от" x="2" y="9"/>
 <textField name="trafVneshOutTo" title="до" x="3" y="9"/>
 <textField name="trafVnutrInFrom" title="Внутр. вх. от" x="0" y="10"/>
 <textField name="trafVnutrInTo" title="до" x="1" y="10"/>
 <textField name="trafVnutrOutFrom" title="Внутр. исх. от" x="2" y="10"/>
 <textField name="trafVnutrOutTo" title="до" x="3" y="10"/>
 
 <combo name="trafDiv" title="Выводить трафик в" y="11" width="4">
  <item id="b" title="байтах"/>
  <item id="kb" title="КБ"/>
  <item id="mb" title="МБ"/>
 </combo>
 
 <module title="Услуги модулей" name="sids">
   <service_set mid="66">
     <folder title="Платные услуги">
       <folder title="ДОРОГИЕ услуги">
         <folder title="САМЫЕ-САМЫЕ ДОРОГИЕ услуги" items ="120,198" />
         <folder title="СУПЕРДОРОГИЕ услуги" items ="103,114" />
       </folder>
       <folder title="ДЕШЕВЫЕ услуги" items ="79" />
       <folder title="Разное" items="other"/>
     </folder>
  </service_set>
  <service_set mid="179">
     <folder title="Платный интернет">
       <folder title="ДОРОГОЙ интернет">
         <folder title="САМЫЙ-САМЫЙ ДОРОГОЙ интернет" items ="208" />
         <folder title="СУПЕРДОРОГОЙ интернет" items ="209,210" />
       </folder>
       <folder title="ДЕШЕВЫЙ интернет" items ="207" />
     </folder>
     <folder title="Интернет по сходной цене" items ="205,203" />
     <folder title="Интернет в регионах" items ="other" />
  </service_set>
</module>
....

Внешний вид получившегося фильтра:

Код генерации отчёта имеет доступ к:

  • значениям фильтра с использованием атрибута name;

  • переменным конфигурации модуля, используя название переменной конфигурации, также можно использовать для передачи в отчёт кодов параметров и т.п.;

  • переменной mid - коду текущего выбранного экземпляра модуля, для которого делается отчёт (0 - для ядра).

11.2. Отчёты JasperReports.

В iReport создайте шаблон и сохраните его в директорию reports как <модуль>_<id>.jrxml. Откройте его в iReport.

Для отображения отчёта необходимо получить данные (datasource). Получение данных описывается в шаблоне отчёта, для iReport - это пункт меню Data->Report Query (Запрос Отчёта).

На данный момент возможны два метода получения datasource - SQL и BGBS. В параметре Query language необходимо указать используемый.

SQL-метод используется для отчётов, данные которых можно получить одним запросом.

При этом значения фильтров, переменные конфигурации подставляются в запрос макросами:

$(name) - подставляет текстовое значение, где name - имя фильтра, либо переменная конфигурации модуля;

$mm(name) - подставляет значение месяца вида MM, январь - 01;

$yy(name) - подставляет год вида yyyy;

$date(name) - подставляет дату в формате sql;

$time(name) - подставляет время в формате sql;

$module_month_table(table, name) - подставляет имя таблицы в зависимости от текущего модуля, указанного имени таблицы и даты - параметра фильтра,

т.е $module_month_table( log_session , date ) , если фильтр date="01.01.2008", а текущий модуль 1 подставит log_session_1_200801;

$month_table - тоже самое без идентификатора модуля, т.е, например log_session_200801;

При построении запроса можно установить соединение с базой и, используя статические данные вместо макросов значений фильтров, проверить запрос и получить имена и типы полей отчёта. Промежуточные и итоговые значения (сумма, счётчик, максимум, минимум) можно указать для подсчёта в variables - параметр Calculation Type, а в Variable Expression указать макрос поля (например $F{col2}). Если одного запроса для построения отчёта не достаточно? то можно воспользоваться скриптом - в Query language укажите bgbs, а в поле запроса должна быть конструкция вида

import java.sql.*;
import java.util.*;

public void fillReport( con, filter, result )
{
   //код для получения datasource

   result.setParams( params ); //установка параметров, которые будут доступны в отчёте (Parameters) - объект интерфейса Map
   result.setDataSource( datasource ); //установка datasource, это может быть объект интерфейса Collection<Map<String, Object>>, ResultSet
}

con - объект класса java.sql.Connection - соединение с базой данных;

filter - объект класса bitel.billing.server.admin.reports.BGReportFilter, содержащий параметры фильтра, переменные конфигурации модуля отчётов. Краткий перечень доступных функций (полный - в API-документации для разработки скриптов BGBS):

String getStringParam( String name )

int getIntParam( String name )
int getIntParam( String name, int def )

long getLongParam( String name )
long getLongParam( String name, long def )

Calendar getCalendarParam( String name )
Date getDateParam( String name )

result - объект, в который необходимо передать параметры отчёта и datasource. У него имеются функции:

void setDataSource( JRDataSource dataSource )
void setDataSource( Collection<Map<String, Object>> dataSource )
void setDataSource( ResultSet dataSource )

void setParams( Map params )

JRDataSource createDataSource( ResultSet dataSource ) //создание объекта datasource из ResultSet
JRDataSource createDataSource( Collection<Map<String, Object>> dataSource ) //создание объекта datasource из коллекции Map

String sql( String sql, BGReportFilter filter ) //преобразование строки запроса с помощью шаблонов
// (преобразование аналогично sql варианту получения данных)

В параметрах (Parameters) отчёта должны быть определены параметры _filter и _months с соответствующими снимку экрана ниже типами:

Пример шаблона отчёта "Отчет наработки по услугам":

Файл kernel_report.rep.xml

<?xml version="1.0" encoding="UTF-8"?>
<report title="Мой отчёт по наработке">
  <month name="month" title="Месяц"/>
  <contractGroups name="gr" title="Группы договоров"/>
</report>

При использовании типа запроса SQL: Query language - SQL, сам запрос:

SELECT t3.title as col1, SUM(t1.summa) as col2 FROM contract_account AS t1,  contract AS t2, service AS t3 
WHERE t1.cid=t2.id AND t1.sid=t3.id 
AND t2.gr&$(gr)>0
AND t1.yy=$yy(month) AND t1.mm=$mm(month)
GROUP BY t1.sid ORDER BY t3.mid, t3.title

Здесь макросы $() будут заменены на соответствующие значения фильтра, т.е month и gr.

При использовании типа запроса BGBS: Query language - BGBS, запрос:

import java.sql.*;
import java.util.*;

public void fillReport( con, filter, result )
{
  PreparedStatement ps = con.prepareStatement( result.sql( "SELECT t3.title as col1," +
  " SUM(t1.summa) as col2 FROM contract_account AS t1,  contract AS t2, service AS t3"+
  " WHERE t1.cid=t2.id AND t1.sid=t3.id AND t2.gr&$(gr)>0 AND t1.yy=$yy(month) AND"+
  " t1.mm=$mm(month) GROUP BY t1.sid ORDER BY t3.mid, t3.title", filter ) );

  ResultSet rs = ps.executeQuery();
  result.setDataSource( rs );
}

запрос использующий Collection<Map>:

import java.sql.*;
import java.util.*;

public void fillReport( con, filter, result )
{
  PreparedStatement ps = con.prepareStatement( result.sql( "SELECT t3.title as col1," +
  " SUM(t1.summa) as col2 FROM contract_account AS t1,  contract AS t2, service AS t3"+
  " WHERE t1.cid=t2.id AND t1.sid=t3.id AND t2.gr&$(gr)>0 AND t1.yy=$yy(month) AND"+
  " t1.mm=$mm(month) GROUP BY t1.sid ORDER BY t3.mid, t3.title", filter ) );

  ResultSet rs = ps.executeQuery();

  double total = 0;
  List res = new ArrayList();
  while(rs.next())
  {
    Map  map = new HashMap();
    map.put("col1", rs.getString(1));
    double val = rs.getDouble(2);
    map.put("col2", val);
    total += val;

    res.add(map);
  }

  Map params = new HashMap();
  params.put( "total", total );

  result.setDataSource( res );
  result.setParams( params );
}

Для отображения в отчёте даты отчёта добавляем textfield с Expression Class: java.util.Date, Pattern: год: yyyy месяц: MMMMM, Expression: $P{_filter}.getDateParam( "month" ).

Подсчёт итогового значения предоставим отчёту, добавив variable sum c Class Type java.lang.Double, Calculation Type Sum, Variable Expression $F{col2}.

Добавим текстовое поле для его отображения, Expression Class java.lang.Double, Pattern # ##0.00, Text Field Expression $V{sum}.

iReport вместе с вариантом данного примера: ftp://bgbilling.ru/pub/bgbilling/reports/iReport_1.3.2.zip

Другие примеры отчётов доступны на Wiki. Наиболее простой способ разработки собственного отчёта - модификация существующего. Также некоторые отчёты, идущие в стандартной поставке (например, отчёт по должникам) могут быть изменены.

Имеется возможность в отчёте использовать гиперссылки. Это позволяет из одного отчёта быстро открывать другие связанные отчёты или разные сущности системы, например, договоры. Можно использовать отчёты как "универсальный поиск" - формируем любые фильтры и логику поиска, связываем строки результата с отрываемыми договорами и можно получить список договоров по любому критерию с возможностью открыть нужный. На данный момент поддерживаются следующие типы ссылок:

  • bgbilling:reports://bitel.billing.module.services.reports.BGReportsPanel?param1=value1&param2=value2&... для открытия любого другого отчёта. Для этого нужно знать соответствующие параметры метода Report модуля reports (код отчёта и т. д.).

  • bgbilling:reports://bitel.billing.module.contract.ContractEditor?<cid> для открытия вкладки с соответствующим договором.

Можно указывать глобальные настройки для библиотеки jasperreports в файле jasperreports.properties, путь к которому можно указать с помощью параметра запуска сервера ( server.sh/server.bat):

-Dnet.sf.jasperreports.properties=/path/jasperreports.properties

Значения опции вы можете узнать в документации библиотеки jasperreports.

11.3. Табличные отчёты.

Это отчёты, выполняемые с помощью скрипта Beanshell. С возможностью сохранения в csv.

Фильтр отчёта настраивается так, как описано выше. Кроме того, нужно сделать следующие модификации: в файле *.rep.xml нужно поместить атрибут type=""java":

<report title="Test" type="java">
  <address title="Адрес" cityName="cityId" streetName="streetId" houseName="house"/>
  <combo name="status" title="Статус">
    <item id="-1" title="любой"/>
    <item id="0" title="активен"/> 
    <item id="4" title="приостановлен"/>
    <item id="3" title="закрыт"/>
  </combo>
  <fields>
    <item id="title" title="Имя"/>
    <item id="comment" title="Комментарий"/>
  </fields>
</report>

В теге fields указываются заголовки полей данного отчёта .

Создайте файл и сохраните его в директории reports как <модуль>_<id>.java. Пример файла :

public void fillReport( con, filter, bitel.billing.server.reports.BGCSVReport.ReportResult result )
{
  query = " SELECT * from contract ";
  query += " LIMIT " + ((pageIndex - 1) * pageSize )+ "," + pageSize;

  ps = con.prepareStatement( query );
  data = new ArrayList( 1000 );

  rs = ps.executeQuery();

  while( rs. next() )
  {
    title = rs.getString("title");
    comment = rs.getString("comment"); 
  
    map = new HashMap();
    map.put( "title", title );
    map.put( "comment", comment );
    data.add( map );     
  }

  result.setData( data );
}

con - объект класса java.sql.Connection - соединение с базой данных;

filter - объект класса bitel.billing.server.admin.reports.BGReportFilter, содержащий параметры фильтра, переменные конфигурации модуля отчётов;

result - объект класса bitel.billing.server.reports.BGCSVReport.ReportResult, в который необходимо передать параметры отчёта и datasource;

pageSize - размер страницы;

pageIndex - номер страницы.

Пример внешнего вида отчёта :

С помощью кнопки "сохранить" можно сохранить данные отчёта в csv-файл.

Примеры отчётов доступны на Wiki.

Есть возможность спрятать столбец в итоговой таблице, для этого надо в файле с описанием фильтров его значение title предворить символом '#':

<fields>
  ...
  <item id="cid" title="#cid"/>
...

После этого столбец станет невидимым (и его настоящее заглавие останется с решёткой). Это может понадобиться, например, для нижеописанной возможности.

При клике на строки таблицы могут выполняться некоторые действия в зависимости от содержимого таблицы и содержимого в каждой строке. В данный момент имеются следующие возможности:

  • Если в таблице присутствует столбец с заголовком cid (или же невидимый #cid), то при клике на строку откроется соответствующий содержимому столбца cid договор. Как и в случае с jasper-отчётами, это можно использовать для организации произвольного поиска договоров.

12. Мобильные отчеты

Модуль отчетов позволяет просматривать отчеты на мобильных устройствах( пока только для ios ) в виде интерактивных графиков. Где бы вы не находились вы сможете получать свежую информацию по состоянию дел вашего биллинга, соотносить данные на разных промежутках времени и анализировать их. Например кол-во приходов и их сумма, кол-во и активность абонентов и в обще любую информацию которую вы хотите визуализировать в виде графиков, диаграмм и т.д.( с помощью дин. классов ).

Для установки программы пройдите по ссылке в магазин приложений Apple. Если вы это сделаете с мобильного устройства у вас автоматически запуститься App Store, иначе iTunes, и приобрести бесплатно приложение. Если вы это сделали через iTunes, то вам надо будет в мобильном устройстве зайти в историю ваших покупок и установить от туда, либо синхронизировать с iTunes.

12.1. Настройка сервера

Для обмена данными между приложением и сервером вы должны открыт доступ к reportsexecuter и предоставить пользователям приложения адрес который они должны вводить в приложении BGBilling Top Reports. Для работы приложения сервер должен знать код модуля отчетов, его можно передать как в запросе к серверу (../reportsexecuter?mid=12) или для удобства прописать его в настройках сервера(Сервис ->Настройка -> Конфигурация) под параметром reports.defaultCodeModuleForMobileReports где в качестве значения будет код модуля отчетов. При этом возможность указания кода модуля при запросе сохраниться и будет иметь более высокий приоритет.

Далее вам следует настроить модуль отчетов. Для этого пропишите метод входа пользователей под параметром reports.mobileLoggingMetod, где в качестве значения можете использовать 1 или 2. Соответственно 1 - это свободный вход, 2 - вход по логину/паролю пользователя BGBilling

reports.mobileLoggingMetod=2

Рекомендуется использование защищенного протокола https. Приложение поддерживает работу с само подписанными сертификатами.

12.2. Собственные отчеты.

Вы можете создавать собственные отчеты для приложения BGBilling Top Reports. Для этого создайте дин. класс потомок от MobileReport

В методе getReportType вам нужно передать параметры отчета по которым пользователь сможет производить выборку. В getData вам нужно вернуть данные для построения отчета. В getTypeGraf вам нужно вернуть тип графика который будет строиться по вашим данным(гистограмма, линейный график, круговой график или табличный отчет ). В методе getOptions можно вернуть дополнительные данные которые будут отображаться при построении графика или указывать способ отображения. Ниже примеры отчетов.

Круговой отчет

import java.awt.Color; import
import java.awt.Color;
import java.sql.Connection;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;
import ru.bitel.bgbilling.common.BGIllegalArgumentException;
import bitel.billing.server.reports.mobile.MobileParamType;
import bitel.billing.server.reports.mobile.MobileReport;
import bitel.billing.server.reports.mobile.MobileReportType;
import bitel.billing.server.reports.mobile.Slice;

public class Test2 extends MobileReport
{
    @Override
    public MobileReportType getReportType( Connection con )
    {
        List<MobileParamType> list = new ArrayList<>();
        // тут нам необходимо добавить параметры, по которым пользователь сможет регулировать выборку данных.
        // расмотрим способ и типы параметров ниже
        list.add( new MobileParamType( "Date1", MobileParamType.DateType, "От даты", "11.12.2010" ) );
        list.add( new MobileParamType( "Date2", MobileParamType.DateType, "До даты", "03.03.2014" ) );
        list.add( new MobileParamType( "flag1", MobileParamType.BooleanType, "По дням", "false" ) );
        return new MobileReportType( "Test2", list );
    }

    @Override
    public List<Object> getData()
        throws BGIllegalArgumentException
    {
        ArrayList<Object> list = new ArrayList<>();
        // Добавление в список значений. Для кругового и гистограммного отчета использовать класс Slice.
        // Параметры: 1- Название, 2 - Цвет, 3 - Кол-во.
        list.add( new Slice( "Приходы", new Color( 101, 214, 86 ), 23 ) );//цвет можно создать свой
        list.add( new Slice( "Расходы", getColor(), 34 ) );// или вытягивать по порядку предопределенные
        list.add( new Slice( "Наработка", getColor(2), 45 ) );// или по номеру
        grafType = PieChartType;// задание типа графика (PieChartType,HistogramChartType,LinearChartType,TableType)
        return list;
    }

    @Override
    public Map<String, Object> getOptions()
    {
        return null;// Для круговых пока не предусмотрено особых опций.
    }
}
      

Гистограммный отчет.


public class Test1    extends MobileReport
{
    @Override
    public MobileReportType getReportType( Connection con )
    {
        List<MobileParamType> list = new ArrayList<>();
        list.add( new MobileParamType( "flag1", MobileParamType.BooleanType, "По дням", "false" ) );
        list.add( new MobileParamType( "Date1", MobileParamType.DateType, "От даты", "01.09.2014" ) );
        list.add( new MobileParamType( "Date2", MobileParamType.DateType, "До даты", "07.09.2014" ) );
        return new MobileReportType( "Приходы( гистограмма )", list );
    }

    @Override
    public List<Object> getData()  throws BGIllegalArgumentException
    {
    	grafType = HistogramChartType;
        try
        {
            boolean flag1 = getBooleanParameter( "flag1", false );
            
            Date date1 =  getDateParameter( "Date1", new Date() );// получение данных выбранных пользователем.
            Date date2 =  getDateParameter( "Date2", new Date() );// в первый раз передаются дефолтные значения
            if( date1 == null || date2 == null && TimeUtils.dateBefore( date1, date2 ) )
            {
                throw new BGIllegalArgumentException();
            }
            
            StringBuilder query = new StringBuilder( "SELECT SUM(summa), DATE_FORMAT(dt, '" );
            String periodParam = getParameter( "period", "w" );
            if( periodParam != null)
            {
                String format = "";
                Calendar time = Calendar.getInstance();
                flag1 = true;
                switch ( periodParam )
                {
                    case "w":
                        time.add( Calendar.DAY_OF_YEAR, -7 );
                        format = "%d.%m";
                        break;
                    case "m":
                        time.add( Calendar.MONTH, -1 );
                        format = "%d.%m.%y";
                        break;
                    case "q":
                        time.add( Calendar.MONTH, -3 );
                        format = "%d.%m.%y";
                        break;
                    case "y":
                        flag1 = false;
                        time.add( Calendar.YEAR, -1 );
                        format = "%m.%Y";
                        break;
                }
                query.append( format );
                date1 = time.getTime();
                date2 = new Date();
            }
            else
            {
                query.append( flag1 ? "%d.%m" : "%m %Y" );// если по дням, то года не выдаем.
            }
            query.append( "'), COUNT(id) FROM contract_payment WHERE dt>=? AND dt<? GROUP BY YEAR(dt),MONTH(dt)" );
            query.append( flag1 ? ",DAY(dt)" : "" );
            query.append( " ORDER BY dt ASC" );
            PreparedStatement ps = con.prepareStatement( query.toString() );// коннекшен просто берете и используете.

            ps.setDate( 1, TimeUtils.convertDateToSqlDate( date1 ) );
            ps.setDate( 2, TimeUtils.convertDateToSqlDate( date2 ) );
            
            ArrayList<Object> dataList = new ArrayList<>();
            ResultSet rs = ps.executeQuery();
            int count = 1;
            while( rs.next() )
            {
                dataList.add( new Slice( rs.getString( 2 ), getColor(), rs.getDouble( 1 ) ) );
            }
            return dataList;
        }
        catch( SQLException e )
        {
            e.printStackTrace();
        }
        return null;
    }

    @Override
    public Map<String, Object> getOptions()
    {
    // Для гистограммного отчета есть возможность выставить панель быстрого вызова ниже графика.
    // Для этого создаем мап для опций и мап для панели. Мап панели должен иметь значения для ключей id,values и titles.
    // Где id - это ид по которому вы будет получать значения( как это было сделано выше - getParameter( "period", "w" ) ).
    // values - код/значение которое пользователь может выбрать, и которое вы получите если он это сделает.
    // titles - пользовательское описание кнопок панели.
        HashMap<String, Object> map = new HashMap<>(), dateMap = new HashMap<>();
        dateMap.put( "id", "period" );
        dateMap.put( "values", "w,m,q,y" );
        dateMap.put( "titles", "Неделя,Месяц,Квартал,Год" );
    // Далее кладём мап панели в мам опций с ключом dataToolbar.
        map.put( "dataToolbar", dateMap );
    // С помощью ключа changeGrafHide, можно запретить возможность пользователю переключаться на круговой график.
//        map.put( "changeGrafHide", "1" );
        return map;
    }
}
	  		

Линейный график.

import java.sql.Connection;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.util.ArrayList;
import java.util.Date;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

import ru.bitel.bgbilling.common.BGIllegalArgumentException;
import bitel.billing.common.TimeUtils;
import bitel.billing.server.reports.mobile.MobileParamType;
import bitel.billing.server.reports.mobile.MobileReport;
import bitel.billing.server.reports.mobile.MobileReportType;

public class PaymentsMobileReport    extends MobileReport
{
    private ArrayList<String> descriptionList = null;
    private ArrayList<String> titleList = null;
    
    @Override
    public MobileReportType getReportType( Connection con )
    {
        List<MobileParamType> list = new ArrayList<>();
        list.add( new MobileParamType( "Date1", MobileParamType.DateType, "От даты", "11.12.2010" ) );
        list.add( new MobileParamType( "Date2", MobileParamType.DateType, "До даты", "03.03.2014" ) );
        list.add( new MobileParamType( "flag1", MobileParamType.BooleanType, "По дням", "false" ) );
        return new MobileReportType( "Приходы( линейный )", list );
    }
    
    @Override
    public List<Object> getData() throws BGIllegalArgumentException
    {
    // Линейный график должен вернуть в качестве данных список double значений. Каждое значение это точка на графике.
    	grafType = LinearChartType;
    	try
    	{
    		boolean flag1 = getBooleanParameter( "flag1", false );
    		StringBuilder query = new StringBuilder( "SELECT SUM(summa), DATE_FORMAT(dt, '" );
    		query.append( flag1 ? "%d.%m" : "%m %Y" );// если по дням, то года не выдаем.
    		query.append( "'), COUNT(id) FROM contract_payment WHERE dt>=? AND dt<? GROUP BY YEAR(dt),MONTH(dt)" );
    		query.append( flag1 ? ",DAY(dt)" : "" );
    		query.append( " ORDER BY dt ASC" );
    		PreparedStatement ps = con.prepareStatement( query.toString() );
    		
    		Date date1 =  getDateParameter( "Date1", new Date() );
    		Date date2 =  getDateParameter( "Date2", new Date() );
    		if( date1 == null || date2 == null && TimeUtils.dateBefore( date1, date2 ) )
    		{
    			throw new BGIllegalArgumentException();
    		}
    		ps.setDate( 1, TimeUtils.convertDateToSqlDate( date1 ) );
    		ps.setDate( 2, TimeUtils.convertDateToSqlDate( date2 ) );
    		
    		ArrayList<Object> dataList = new ArrayList<>();
    		titleList = new ArrayList<>();
    		descriptionList = new ArrayList<>();
    		ResultSet rs = ps.executeQuery();
    		while( rs.next() )
    		{
    			dataList.add( rs.getDouble( 1 ) );
    			titleList.add( rs.getString( 2 ) );// то что будет отображаться по оси абсцисс
    			descriptionList.add( "кол-во платежей: " + rs.getInt( 3 ) );// для доп. описания
    		}
    		return dataList;
    	}
    	catch( SQLException e )
    	{
    		e.printStackTrace();
    	}
    	return null;
    }
    
    @Override
    public Map>String, Object> getOptions()
    {
        HashMap<String, Object> map = new HashMap<>();
        // Для линейного графика можно помимо точек передать описание каждой точки
        if( descriptionList != null && descriptionList.size() > 0 )
            map.put( "description", descriptionList );
        // и заголовки с ключами description и titles соответственно.
        if( titleList != null && titleList.size() > 0 )
            map.put( "titles", titleList );
        return map.size() > 0 ? map : null;
    }
}
	  		

Табличный отчет.

	@Override
    public List<Object> getData() throws BGIllegalArgumentException
    {
    	// Табличный отчет должен вернуть список содержащий список значений ячеек.
    	// Изменение размерности запрещено, если у вас первая строка содержала 3 столбца, то и остальные должны содержать 3.
    	grafType = TableType;
    	ArrayList<Object> list = new ArrayList<>();
    	ArrayList<String> rowList1 = new ArrayList<>();
    	ArrayList<String> rowList2 = new ArrayList<>();
    	rowList1.add("Столбец 1 строка 1");
    	rowList1.add("Столбец 2 строка 1");
    	rowList1.add("Столбец 3 строка 1");
    	rowList2.add("Столбец 1 строка 2");
    	rowList2.add("Столбец 2 строка 2");
    	rowList2.add("Столбец 3 строка 2");
    	list.add(rowList1);
    	list.add(rowList2);
    	return list;
    }
	@Override
    public Map<String, Object> getOptions()
    {
    // С ключом titles передаем название столбцов
        HashMap<String, Object> map = new HashMap<>();
        ArrayList<String> titles = new ArrayList<>();
        titles.add("Название 1 колонки");
        titles.add("Название 2 колонки");
        titles.add("Название 3 колонки");
        map.put( "titles", titles );
        return map;
    }
	  		

Рассмотрим параметры отчетов, по которым пользователь может регулировать выборку данных. Существует 5 типов параметров: Дата(DateType), Список(ListType), Число(NumberType), Список с возможностью выбрать несколько значений(MultiSelectListType), Логический(BooleanType).Ниже приведены примеры их создания в методе getReportType.

List<MobileParamType> list = new ArrayList<>();
// Дата
Calendar calendar = Calendar.getInstance();
list.add( new MobileParamType( "d1", MobileParamType.DateType, "От даты", TimeUtils.format( calendar, TimeUtils.DATE_FORMAT_PATTERN_DDMMYYYY ) ) );
// Список
LinkedHashMap<Integer, String> map = new LinkedHashMap<>();
map.put( 1, "10" );
map.put( 2, "100" );
map.put( 3, "1000" );
list.add( new MobileParamType( "limit", MobileParamType.ListType, "Макс. размер табл.", "3", map ) );
// Число
list.add( new MobileParamType( "Num1", MobileParamType.NumberType, "Отсекать меньше", "50" ) );
// Список с возможностью выбрать несколько значений
LinkedHashMap<Integer, String> fields = new LinkedHashMap<>();
fields.put( 1, "Договор" );
fields.put( 2, "Комментарий" );
fields.put( 3, "Пользователь" );
fields.put( 4, "Сумма" );
fields.put( 5, "Дата" );
fields.put( 6, "Тип платежа" );
fields.put( 7, "Примечание" );
list.add( new MobileParamType( "fields", MobileParamType.MultiSelectListType, "Поля", "1,2,3,4,5,6", fields ) );
// Логический
list.add( new MobileParamType( "flag1", MobileParamType.BooleanType, "По дням", "false" ) );
	  		

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

reports.mobile.dinamic.1.title=Мои отчеты
reports.mobile.dinamic.1.classes=mobileReports.Test2,mobileReports.Test1

В параметре reports.mobile.dinamic.1.title должно содержаться название категории отчетов, а в reports.mobile.dinamic.1.classes через запятую полное название ваших классов. Если вы решите добавить еще одну категорию, то измените 1 на 2 и т.д.

Глава 32. Модуль RSCM

1. Назначение

Модуль RSCM (Random Service Calculate Module - Обсчёт произвольных услуг) предназначен для начисления на счёт пользователя наработки за потребление различных типов услуг.

2. Установка и настройка модуля

Модуль устанавливается с помощью bg_installer. После создания его экземпляра в редакторе модулей и услуг заносится перечень услуг данного модуля. Например: Вызов мастера, Получение пакета обновлений. После этого необходимо закрыть BGBillingClient и подключиться им снова к серверу для того чтобы модуль появился в меню.

Для каждого типа услуги устанавливается единица измерения. Например: "Вызов мастера" в часах, "Получение пакета обновлений" в КБ. Привязка производится на вкладке Параметры услуг модуля.

При добавлении новой услуги на вкладке Параметры услуг в Редакторе из выпадающего списка можно выбрать лишь те услуги, которые еще не были добавлены ранее. Это сделано для того, чтобы нельзя было добавить несколько одинаковых услуг с разными единицами измерения.

Установите конфигурацию модуля:

#проверка баланса перед занесением услуги в договор (1 - проверять)
check.lower.bound=0
#начисление денег сразу по добавлению услуги в договор
hot.calc=1
#количество выводимых ошибок в периодических процессах
max.periodic.errors=30

Для произведения начисления наработки необходимо в планировщике добавить задачу Начисление RSCM с параметром в конфигурации

mid=<код модуля>

Также начисление за определённый месяц можно вызвать вручную на вкладке Переобсчёт.

3. Использование модуля

Подключение модуля к договору осуществляется через выбор узла Модули дерева договора, нажатием на кнопку Новый элемент стандартной панели инструментов. После занесения в договор наработки по услуге и выполнения переобсчёта в баланс договора будет занесена наработка в соответствии с текущим тарифным планом.

В тарифном плане должны быть определены цены для каждого вида услуги. Логика поиска тарифа соответствует Алгоритму 1.

Узел с ценой услуги может быть заключён в контейнеры Период, либо Временной фильтр.

4. События модуля

Для данного модуля определено одно событие BGBS :

"Изменение/добавление начисления услуги RSCM в договор" - вызывается при изменении/добавлении начисления услуги RSCM в договор.

Глава 33. Модуль RuRuPay

1. Назначение модуля

Модуль предназначен для предоставления пользователям личного кабинета способа пополнения счёта через систему RuRu ( https://www.ruru.ru/ ). В личном кабинете работа ведётся через всплывающий виджет, позволяющий оплатить с помощью электронных валют, баланса сотового телефона, кредитных карт и других доступных способов оплаты системы. Также поддерживается оплата с витрины RuRu, с помощью смс и т.п (см. возможности системы).

2. Настройка модуля

В общем виде конфигурация модуля выглядит так:

# параметры подключения к системе (дают в RuRu)
partner_id=***
service_id=***
# секретное слово
secretword=***
# тип добавляемого платежа
paymenttype=32
# шаблон комментария добавляемого платежа
# contract.getTitle - название договора
# contract.getComment - комментарий договора
# payment.getSum - сумма пришедшего платежа
# payment.getDate - дата пришедшего платежа
# sum - сумма отформатированная
# date - дата отформатированная
payment_comment=Оплата по дог. {$contract.getTitle} ({$contract.getComment}) через RuRu на сумму {$payment.getSum} от {$date}
# префикс/домен для обращения к скриптам виджета (например, демо: "https://wdemo.ruru.ru/", боевой: "https://widget.ruru.ru/")
action_url=https://wdemo.ruru.ru/

Обмен данными со стороны RuRu нужно настроить так, чтобы приходил запрос init.

URL для оповещения настраивается со стороны RuRu и выглядит так: http://<host>/bgbilling/rurupayexecuter/<mid> , где mid - ид экземпляра модуля.

3. Использование модуля

При добавлении модуля на договор в web-интерфейсе статистики появляется пункт меню "Пополнение счёта через RuRu". На странице оплаты — список операций со статусами и кнопка для вызова виджета оплаты.

Все оплаты логгируются в модуле.

В договоре также можно посмотреть подобную статистику.

Глава 34. Модуль Subscription

1. Назначение модуля

Модуль предназначен для начисления наработки за периодические услуги. Модуль похож по функционалу на модуль NPay, за следующими исключениями: начисление возможно за произвольные периоды от 1 секунды до бесконечности, соответственно период не привязян к календарным дням, месяцам и т.д.; начисление происходит сразу в момент активации нового учетного периода при условии наличия на момент активации необходимой суммы на счете, в случае недостачи средств новый период не активируется; продление подписки возможно на новый учетный период как в автоматическом режиме так и вручную.

2. Настройка модуля

Установите модуль на сервер, используя утилиту bg_installer, обновите клиент биллинга. Затем создайте экземпляр модуля, назвав его произвольным образом (например, Подписки).

Определите в редакторе модулей и услуг услуги, связанные с этим модулем. Рекомендуем для каждой подписки создать отдельную услугу. Для начала можете определить несколько тестовых услуг, скорректировав список впоследствии.

Для работы модуля необходимом создать "Типы подписок" в соответствующем справочнике Меню = Модули = Подписки, закладка "Типы подписок". Октройте редактор щелкнув по иконке "Новый элемент" на панели инструментов.

В редакторе необходимо указать название подписки, выбрать связанную с подпиской услугу, указать период действия, продолжительность, время начала подписки (задается с помощью параметров Задержка и Округление, подробнее ниже), флаг разрешения автопродления подписки, комментарий и конфигурацию.

Время начала подписки задается двумя параметрами Задержка и Округление, которые используются следующим образом: берем время активации очередного учетного периода, к нему прибавляем время заданое параметром Задержка и округляем до значения заданного параметром Округление. Например, если параметр Задержка и Округление равны 1 HOUR, то время начала подписки будет установлено в 00 минут следующего часа (XX/XX/XXXX 15:34 + 1 HOUR = XX/XX/XXXX 16:34 окр. до 1 HOUR = XX/XX/XXXX 16:00). Если необходимо, что бы подписка была активирована сразу оба параметра необходимо установить в 0.

3. Привязка подписок к клиентам

Подключение модуля к договору осуществляется выбором узла Модули дерева договора, выбором экземпляра модуля в правом списке и нажатием кнопки "<".

После добавления модуля к договору, необходимо добавить нужные подписки на договор. Для этого выбрать в дереве договора элемент Подписки и открыть редактор кликнув по иконке "Новый элемент" на Панели инструментов. В редакторе нужно выбрать Тип подписки, ввести период, при необходимости выставить флаг автопродления и ввести комментарий если нужно.

После добавления подписки на договор, подписку необходимо активировать, для этого выбираем подписку из списка в договоре, правой клавишей мыши вызываем контекстное меню и из выпадающего меню выбираем "Активировать новый учетный период". Активация происходит только при условие, что на договоре есть необходимая для активации сумма и услуга прописана в тарифном плане.

При удачной активации в списке подписок в столбце "Последний учетный период" отображается период на который подписка активирована. По окончании этого периода система попытается повторно активировать новый учетный период, при условии, что на договоре достаточно средств и стоит флаг автопродления. Если флаг автопродления включен, а средств не достаточно, активация будет приостановлена до прихода на договор средств достаточных для активации подписки. Новый период не будет активирован если период действия "Типа подписки" или период подписки на договоре заканчивается раньше, чем период подписки.

4. Примеры тарифных планов модуля

5. Групповые операции

На данный момент для модуля нет доступных групповых операций.

Глава 35. Модуль Sberbank

1. Назначение и настройка модуля

Платежный модуль Sberbank предназначен для осуществления безопасного приема платежей от абонентов банковскими картами Visa/MasterCard. Более подробную информацию о сервисе, размере комиссии можно прочитать на сайте sberbank.ru

Скачайте модуль sberbank с нашего сервера, установите на сервере с помощью утилиты bg_installer.sh (.bat).

В редакторе модулей и услуг создайте экземпляр модуля sberbank.

Для дальнейшей работы модуля необходимо создать конфигурацию модуля и настроить под себя опции, представленные ниже:

Для совершения платежа необходимо перейти в личный кабинет, выбрать пункт меню, соответствующий платежной системе Sberbank. Перед абонентом появится окно следующего содержания:

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

Для просмотра общего списка платежей по всем договорам в системе существует Монитор транзакций, который доступен через меню Moдули->Sberbank ->Монитор транзакций.

Платежи можно отфильтровать по названию договора, по статусу и периоду.

Также можно отслеживать платежи по каждому договору в отдельности. Для этого необходимо открыть карточку договора, в списке модулей выбрать экземпляр модуль Sberbank. Справа появится окно со списком платежей договора.

Глава 36. Модуль TV

1. Назначение модуля

Модуль предназначен для интерактивной интеграции с TV/IPTV Middleware и CAS-системами, организует доступ к услугам, пакетам и каналам, их подключение/отключение из личного кабинета и приставок, тарификацию в реальном времени с точностью до секунды и миниальным периодом тарификации - 1 минута.

На данный момент поддерживаются системы Middleware Stalker (infomir), FrontStage Middleware (TelecomTV, BCC), IPTV Портал, CTI TVEngine.

2. Базовые сведения о модуле

Базовые понятия модуля:

Продукт - абстракция, которая может содержать в себе один или несколько сервисов TV или представлять собой пакет каналов, услугу или тариф MW/CAS. Именно на продукт осуществляется подписка;
Сервис - абстракция, которая может содержать в себе один или несколько каналов TV или представлять собой пакет каналов, услугу или тариф MW/CAS;
Канал - канал MW/CAS;
Подписка - период, когда продукт подключен у аккаунта;
Аккаунт - отражение аккаунта в MW/CAS, дочерний аккаунт - STB (на дочерний аккаунт невозможно активировать подписку);
Тип аккаунта - определяет параметры, которые должны быть указаны у аккаунта;
Устройство - в дереве устройств определяется иерархия устройств разного типа, имеющих значение для модуля. Обычно это устройство Access+Accounting, отражающее приложения BGTVAccess и BGTVAccounting, и дочернее по отношение к нему устройство, отражающее систему упраления MW;
Тип устройства - определяет поведение устройства, механизм управления аккаунтами и подписками на продукты на устройствах данного типа;

Внимание

Не путайте понятия тип устройства и устройство.

Приложения модуля:

BGTVAccess - выполняет синхронизацию аккаунтов в MW/CAS, управляет доступом аккаунтов к подписанным услугам/пакетам/каналам;
BGTVAccounting - выполняет тарификацию подписок.

Связь между приложениями осуществляется посредством базы данных и MQ-сообщений.

Внимание

После очередного обновления модуля необходимо в Автоматизация->Управление динамическоим кодом скомпилировать все классы, т.к. перекомпиляция после обновления автоматически не происходит, а классы, входящие в сборку, могли обновиться.

3. Настройка модуля

Установите модуль на сервер, создайте экземпляр. Определите в Редакторе модулей и услуг услуги, обсчитываемые этим модулем. Например: "Подписка IPTV". Услуги используются для разделения наработки по типам в балансе договора. Установка услуги происходит в тарифе, в зависимости от продукта, на который осуществляется подписка и других параметров.

В конфигурации модуля укажите:

# Активные и приостановленные статусы договора
contract.status.active.codes=0
contract.status.suspend.codes=3,4

# Id сущностей (Справочники - Атрибуты) для продукта, сервиса и канала,
# для привязки атрибутов к продуктам, сервисам и каналам
#productSpec.entitySpecId=
#serviceSpec.entitySpecId=
#tvChannelSpec.entitySpecId=

#Пункты Web - меню
web.menuItem1=TV подписки

# Параметры автоматической генерации логина для аккаунта. Можно указать в конфигурации модуля, конфигурации устройства, конфигурации типа сервиса
# (в последнем случае значения будут главнее):
# минимальное значение логина при генерации логина
#account.login.min=1
# максимальное значение логина при генерации логина (т.е. если в базе присутствуют логины 1,2,3 и 10000000,
# то при генерации создастся логин 4, а не 10000001)
#account.login.min=9999999
# форматирование генерируемого логина
#account.login.format=0000000

# Парамерты пароля для аккаунта. Можно указать в конфигурации модуля, конфигурации устройства, конфигурации типа сервиса
# (в последнем случае значения будут главнее):
# минимальная длина пароля
account.password.length.min=4
# Максимальная длина пароля
account.password.length.max=8
# Разрешенные символы (используются также при генерации пароля)
account.password.chars=1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz
# Описание разрешенных символов, если пользователь ввел другие
account.password.chars.description=В пароле допустимы только цифры и латинские буквы.
# Длина для автоматически генерируемого пароля
account.password.length.auto=6
# Используемые символы для автоматически генерируемого пароля (по умолчанию значение берется из параметра account.password.chars)
#account.password.chars.auto=

4. Продукты, Сервисы, Каналы

Продукт - сущность на которую осуществляется подписка (активация продукта/активация подписки). Начисление наработки согласно тарифу может происходить как при активации продукта, так и периодически, согласно указанному в тарифе периоду тарификации.

Продукт может отражать пакет каналов, услугу или пакет услуг из MW/CAS. Например, в MW/CAS заведены тарифы, на которых, внутри MW/CAS прописаны каналы и услуги, и при этом подписка будет осуществляться только на эти тарифы. Тогда достаточно будет завести продукты-тарифы MW/CAS и указать в продуктах соотвутсвтующие идентификаторы тарифов MW/CAS. В этом случае интеграция с MW/CAS будет на уровне продуктов.

В случае, если группировка в пакеты в MW/CAS отсутствует, такую группировку можно сделать средствами модуля, т.к. продукт может содержать в себе сервисы. Когда активен продукт - активны все сервисы, указанные в нем. Например, можно создать продукт "Все включено", в котором будут добавлены сервисы "Базовый пакет" и "VIP-пакет", отражающие соответствующие пакеты в MW/CAS (и с прописанными идентификаторами пакетов MW/CAS). В данном случае интеграция будет на уровне сервисов.

В случае, когда группировки каналов в пакеты нет, или же есть возможность подключать каналы без пакетов, а группировка внутри MW/CAS не желательна, можно интегрировать модуль на уровне каналов, т.к. сервис может содержать в себе каналы. В этом случае потребуется полная связка Продукт - Сервисы - Каналы.

4.1. Продукты

Для удобства продукты (а точнее - их спецификации) можно добавлять в виде дерева.

На вкладке Параметры необходимо указать название, тип, период действия спецификации продукта, а также идентификатор сущности в MW/CAS системе, если данный продукт будет отражать какую-то сущность MW/CAS.

Атрибуты сущности используются опционально и позволяют указывать произвольные параметры.

Если необходимо (например, когда интеграция с MW/CAS создается на уровне сервисов или каналов), в спецификации продукта указывается список привязанных к нему спецификаций сервисов. Таким образом, когда у аккаунта будет активен продукт, будут и активны все указанные здесь сервисы. Для того чтобы привязать спецификацию сервиса к спецификации продукта, сначала ее нужно создать.

У каждой спецификации продукта, на который будет осуществляться подписка, должен быть добавлен хотя бы один режим активации. В режиме активации указываются длительность (0, если действует бесконечно или до деактивации), время начала действия, возможна ли деактивация (для бесконечных подписок) или реактивация (для деактивированных подписок, период действия которых еще не закончился).

На вкладке Доступность указывается тарифные планы и группы договоров, для которых подписка на данный продукт будет доступна. Если ничего не указано - доступно всем.

На вкладке Зависимость указывается от каких продуктов он зависит и с какими не совместим. Т.е. если происходит попытка активации продукта, зависимого от другого, то период подписки другого продукта должен включать в себя период подписки нового продукта. И наоборот для несовместимости - период подписок данных продуктов не должен пересекаться. Для того, чтобы один продукт нельзя было активировать несколько раз, в продукте нужно указать, что он несовместим сам с собой.

Если продукт необходимо не показывать в личном кабинете абонента для определенных групп договоров или же не показывать всем, то это нужно указать на вкладке Видимость.

4.2. Сервисы

Для того, чтобы привязать спецификации сервисов к спецификации продукта, сначала их нужно создать. Для удобства спецификации сервисов можно создавать в виде дерева.

Для спецификации сервиса необходимо указать название, период действия и идентификатор сущности в MW/CAS, если данный сервис отражает какую-то сущность (например, пакет каналов) в MW/CAS.

Атрибуты сущности используются опционально и позволяют указывать произвольные параметры.

Если инеграция с MW/CAS осуществляется на уровне каналов, то в спецификации сервиса необходимо указать список каналов, которые будут доступны при активности данного сервиса. Таким обзом сервис может являться пакетом каналов, настроенным в биллинге.

4.3. Каналы

В канале указывается название, период действия и идентификатор канала в MW/CAS.

Атрибуты сущности используются опционально и позволяют указывать произвольные параметры.

5. Типы аккаунтов

Для того, чтобы добавить аккаунт на договор, нужно сначала создать тип аккаунта.

Тип аккаунта представляет собой описание того, что должно быть в аккаунте, конфигурацию (с указанием шаблона названия аккаунта) и указание родительских типов, если необходимо.

Флаги логин, пароль, PIN, устройство, идентификатор и MAC-адрес указывают на наличие данного поля при редактировании аккаунта данного типа.

В конфигурации аккаунта в параметре const.device.id необходимо указать Id устройства, к которому будет привязан добавляемый аккаунт (устройство-MW/CAS) и шаблон названия аккаунта:

# Id устройства, к которому привязан аккаунт
const.device.id=
# Шаблон названия аккаунта
title.pattern=Аккаунт: (${login})

В параметре title.pattern можно использовать макросы вида (${macros}), где вместо macros можно указать:

deviceIdentifier - идентификатор устройства, к которму привязан аккаунт,
deviceTitle - название устройства, к которому привязан аккаунт,
login - логин аккаунта,
id - Id аккаунта,
interfaceId - интерфейс,
vlan - VLAN,
identifier - идентификатор аккаунта,
macAddress - MAC-адрес аккаунта.

Для каждого типа STB может быть свой тип аккаунта, например, с различной конфигурацией. Пример типа аккаунта описывающего STB-приставку:

Аккаунт-приставка должен быть дочерним к обычному аккаунту - для этого в нем нужно указать родительские типы аккаунтов.

Пример конфигурации типа аккаунта:

# Шаблон названия аккаунта
title.pattern=(${login})

# Постоянный код устройства для всех аккаунтов данного типа,
# будет автоматически устанавливаться при сохранении аккаунта
#const.device.id=

# Парамерты пароля для аккаунта. Можно указать в конфиге модуля, конфиге устройства, конфиге типа аккаунта
# (в последнем случае значения будут главнее):
# минимальная длина пароля
#account.password.length.min=5
# максимальная длина пароля
#account.password.length.max=16
# разрешенные символы (используются также при генерации пароля)
#account.password.chars=1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz
# описание разрешенных символов, если пользователь ввел не разрешенный символ
#account.password.chars.description=В пароле допустимы только цифры и латинские буквы.
# длина для автоматически генерируемого пароля
account.password.length.auto=6
# используемые символы для автоматически генерируемого пароля (по умолчанию значение берется из параметра account.password.chars)
#account.password.chars.auto=<account.password.chars>

6. Типы устройств

Тип устройства описывает поведение и функции устройства.

Обычно достаточно создать два типа устройства - Access+Accounting, отражающий приложения TvAccess и TvAccounting, и тип устройства, отражающий систему MW/CAS. На скриншоте тип устройства для FrontStage Middleware.

Сущность - сущность из Справочники - Атрибуты. Определяет опциональный набор атрибутов, доступных при редактировании устройства,

OrderManager - динамический класс, осуществляющий бо́́льшую часть интеграции с MW/CAS системой со стороны биллинга.

В конфигурации типа устройства указываются параметры, специфичные для выбранного OrderManager.

7. Устройства

Дерево устройств состоит из корневого устройства Access+Accounting и дочернего к нему устройства-MW/CAS. Корневое устройство отражает приложения BGTVAccess и BGTVAccounting.

В параметрах устройства-MW/CAS системе указываются параметры, с помощью которых OrderManager будет подключаться к системе и выполнять синхронизацию. Обычно это хост/порт и логин/пароль для подключения к системе.

Аккаунты необходимо привязывать именно к этому устройству.

На вкладке Атрибуты можно опционально указать дополнительные параметры, набор которых определяется сущностью, назначенной в пункте Сущность типа устройства.

8. Аккаунты

Аккаунты привязываются к договору на соостветствующей вкладке модуля в договоре.

При редактировании аккаунта доступны параметры, указанные в выбранном типе аккаунта.

В дочернем аккаунте недоступна активация продуктов (подписки). В данном случае дочерний аккаунт является SetTopBox'ом:

К аккаунту привязываются активированные продукты (подписки).

Именно для аккаунта производится активация продукта (т.е. подписка на продукт).

9. Тарифы

В модуле TV начисление может производиться как единовременное списание при активации продукта, как периодическое списание, так и оба вместе, в зависимости от тарифа.

Важно знать, что период продукта не означает, что в этот период абоненту будет доступен продукт. Период продукта не изменяется при периодическом начислении, а изменяется период состояния "включен" продукта.

В тарифе необходимо обызательно указать стоимость подписки и услугу. Дополнительно можно указать стоимость активации продукта.

При указании стоимости активации данная сумма будет списана со счета абонента при активации. Если баланса на договоре будет не хватать, т.е. баланс минуст стоимость активации будет меньше лимита, то абонент не сможет активировать продукт.

При указании стоимости подписки 0.0 за определенный период и удачной активации, продукт будет активен на весь период подписки.

При указании стоимости подписки больше 0.0 за определенный период сразу после активации продукта произойдет попытка списания данной суммы. Списание произойдет только в том случае, если баланс минус сумма стоимость подписки за период больше или равно чем лимит. В случае списания продукт поменяет состояние с выключен на включен, т.е. станет активным. По истечении периода из тарифа произойдет новая попытка начисления. В случае, если денег на счету абонента не хватает, сумма не будет списана, а продукт перейдет в состояние выключен.

Флаг "выровнено" означает, что периоды когда продукт включен или выключен всегда будут кратны периоду, указанному в тарифе и зависеть от времени начала активированного продукта. Т.е., предположим, что в тарифе указана стоимость подписки 10 руб за 30 минут. У абонента на счету 15 рублей, лимит 0 рублей, он активирует продукт в 12:46, происходит списание 10 рублей и продукт становится активным. В 13:16 происходит попытка продления периода, когда продукт включен, но денег на счету не хватает, продукт переходит в состояние выключен (и происходит отключение соответствующего, например, пакета каналов). В 13:30 абонент вносит платеж 5 рублей - при установленном флаге "выровнено", произойдет продление с 13:16 до 13:46, когда произойдет новая попытка начисления; при неустановленном - с 13:13 до 14:00, когда произойдет новая попытка начисления. Если же абонент вносит платеж не в 13:30, а в 14:10, при включенном флаге - с 13:46 до 14:16, а при выключенном - с 14:10 до 14:40.

Флаг "выровнено" подойдет в случае подневного начисления - необходимо в режиме активации указать, x дней с текущего, в тарифе y за 1 день. Теперь, если абонент заплатит в течение дня, следующее начисление все равно произойдет в 00:00.

Если необходимо единовременное списание за активацию, нужно указать режим активации и стоимость активации, а стоимость подписки указать 0 за какой-либо не нулевой период:

При необходимости можно совместить списание за активацию и периодическое списание:

Или же, в зависимости от режима активации указать разную стоимость периодического начисления:

10. Переобсчет

11. Интеграция

11.1. IPTV Портал (iptvportal.ru)

Интеграция с данным MW "IPTV Портал" представлена в виде отрытого кода (динамические классы).

При интеграции с данной системой продукты модуля (или, в зависимости от конфигурации, сервисы модуля) являются подключаемыми пакетами MW.

Добавьте конфигурацию модуля и установите ее активной:

# Активные и приостановленные статусы договора
contract.status.active.codes=0
contract.status.suspend.codes=3,4

# Id сущностей (Справочники - Атрибуты) для продукта, сервиса и канала,
# для привязки атрибутов к продуктам, сервисам и каналам
#productSpec.entitySpecId=
#serviceSpec.entitySpecId=
#tvChannelSpec.entitySpecId=

#Пункты Web - меню
web.menuItem1=TV подписки

# Параметры автоматической генерации логина для аккаунта. Можно указать в конфигурации модуля, конфигурации устройства, конфигурации типа сервиса
# (в последнем случае значения будут главнее):
# минимальное значение логина при генерации логина
account.login.min=10000001
# максимальное значение логина при генерации логина (т.е. если в базе присутствуют логины 1,2,3 и 10000000,
# то при генерации создастся логин 4, а не 10000001)
account.login.max=99999999
# форматирование генерируемого логина
#account.login.format=0000000

# Парамерты пароля для аккаунта. Можно указать в конфигурации модуля, конфигурации устройства, конфигурации типа сервиса
# (в последнем случае значения будут главнее):
# минимальная длина пароля
account.password.length.min=4
# Максимальная длина пароля
account.password.length.max=8
# Разрешенные символы (используются также при генерации пароля)
account.password.chars=1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz
# Описание разрешенных символов, если пользователь ввел другие
account.password.chars.description=В пароле допустимы только цифры и латинские буквы.
# Длина для автоматически генерируемого пароля
account.password.length.auto=6
# Используемые символы для автоматически генерируемого пароля (по умолчанию значение берется из параметра account.password.chars)
#account.password.chars.auto=

# тип устройства - IPTVPortal (для синхронизации терминалов из MW)
om.deviceTypeIds=2

Необходимо создать новый тип устройства, назвать его, например, Access+Accounting - данный тип устройства будет отражать приложения TvAccess и TvAccounting.

Далее создайте новый тип устройства, назовите его, например, IPTVPortal и добавьте конфигурацию:

# Коды параметров договора для заполнения полей в MW-системе (если не указано - используется комментарий договора)
# код параметра договора ФИО или Фамилия (если фамилия указывается отдельно)
#customer.lastName.pid=
# код параметра Имя (если он указан отдельно)
#customer.firstName.pid=
# код параметра - названия компании (для юр. лиц)
#customer.company.pid=


# Режим синхронизации продуктов (0 - по событию, 1 - по событию, полная)
om.product.syncMode=1
# уровень интеграции, 0 - интеграция на уровне продуктов модуля, 1 - интеграция на уровне сервисов модуля
om.product.serviceMode=0

Заметьте, что у типа устройства IPTVPortal ID получился равным 2. Именно это значение и прописано в конфигурации модуля, в параметре om.deviceTypeIds.

Создайте устройство типа Access+Accounting и укажите конфигурацию:

# Обработка/обсчет
# кол-во потоков в обработчике
accounting.worker.1.thread.count=1
# пауза перед следующим выполнением
accounting.worker.1.tracking.account.1.delay=60
# максимальное кол-во обработанных аккаунтов в одном выполнении
accounting.worker.1.tracking.account.1.batchSize=500
# пауза перед следующим выполнением
accounting.worker.1.tracking.event.1.delay=10
# максимальное кол-во обработанных аккаунтов в одном выполнении
accounting.worker.1.tracking.event.1.batchSize=100


# Синхронизация
# кол-во выполняемых задач в одном блоке
om.batch.size=20
# время ожидания завершения future задач
om.batch.pause=0
# время ожидания завершения future задач
om.batch.wait=5
# время ожидания следующей задачи перед закрытием соединения
om.batch.waitNext=5

# пауза после ошибки
om.error.pause=60
# кол-во попыток с ошибкой перед тем как отложить задачу
om.error.redelivery.count=5
# кол-во попыток с ошибкой после которого отправить оповещение
om.error.alarm.count=20
# таймаут задания, выполняющегося с ошибкой
om.error.redelivery.timeout=86400

Данное устройство будет отражать приложения TVAccess и TVAccounting.

Создайте дочернее к предыдущему устройству устройство типа IPTVPortal, указажите хост подключения, логин и пароль.

Получившееся дерево устройств:

Добавьте тип аккаунта Аккаунт.

А также тип устройства - Терминал. В поле Родительские типы поставьте галочку на типе "Аккаунт", который создали только что.

Теперь необходимо создать Продукты - они будут отражать пакеты системы IPTVPortal. Поле Название - это название, с которым данный продукт будет отображаться в биллинге. Поле Идентификатор - идентификатор пакета системы IPTVPortal (по умолчанию обычно free, pkg0, pkg1, pkg2...).

Чтобы абонент мог активировать Продукт (тем самым активируя подписку в IPTVPortal) необходимо, чтобы в продукте был задан хотя бы один режим активации. Далее от выбранного режима активации может зависеть режим тарификации.

Получившееся дерево Продуктов:

Далее нужно создать тарифный план с веткой модуля. Пример тарифа:

На договоре нужно добавить модуль TV и создать аккаунт, который будет связан с аккаунтом из системы IPTVPortal

Можно (не обязательно) добавить терминал, как дочерний к аккаунту.

Получившееся дерево аккаунтов:

При регистрации терминала в системе IPTVPortal не приходит какое-либо уведомление в биллинг. Поэтому для синхронизации информации о терминалах нужно создать отдельную задачу. Для этого сначала нужно добавить глобальный скрипт поведения:

Далее добавить задачу в планировщик "Выполнение глобальных скриптов по таймеру".

11.2. FrontStage Middleware (TelecomTV, BCC)

При интеграции с системой FrontStage Middleware используется единый тариф MW, продукты модуля являются подключаемыми услугами MW.

Создайте конфигурацию модуля и сделайте ее активной:

# Параметры аккаунта
# минимальный логин при генерации
account.login.min=100000
# максимальный логин при генерации
account.login.max=999999
# форматирование логина
account.login.format=000000
# длина пароля при генерации
account.password.length.auto=4
# символы генерируемого пароля
account.password.chars=0123456789

# Тип устройства - TelecomTV
# используется для задачи синхронизации терминалов из MW в биллинг
om.deviceTypeIds=

# Web-сервис для обращения MW к биллингу по адресу /bgbilling/tv-ws/ru.bitel.bgbilling.modules.tv.dyn.bcc.telecomtv.ws.billing/<mid>/BillingIptv
tv.ws.billing.class=ru.bitel.bgbilling.modules.tv.dyn.bcc.telecomtv.ws.billing.impl.BillingIptvImpl

# Привязка orderType MW (в данном случае TV1) к продукту биллинга для активации через приставку
om.orderType.TV1.productSpecId=

Необходимо создать новый тип устройства, назвать его, например, Access+Accounting - данный тип устройства будет отражать приложения TvAccess и TvAccounting.

Далее создайте новый тип устройства, назовите его, например, TelecomTV и добавьте конфигурацию:

# Регион MW-системы
om.regionId=1
# Язык MW-системы
om.lang=ru

# Коды параметров договора для заполнения полей в FrontStage Middleware
# код параметра договора ФИО или Фамилия (если фамилия указывается отдельно)
customer.lastName.pid=
# код параметра Имя (если он указан отдельно)
#customer.firstName.pid=
# код параметра - названия компании (для юр. лиц)
customer.company.pid=
# код параметра - адрес
customer.address.pid=
# код параметра - телефон
#customer.phone.pid=

# Тариф системы FrontStage Middleware по умолчанию для аккаунта
om.tariff.default=

# Режим интеграции FrontStage Middleware с биллингом
#om.integrationMode=Prepaid 2.0

# Режим синхронизации продуктов (0 - по событию, 1 - по событию, полная)
om.product.syncMode=1
# уровень интеграции, 0 - интеграция на уровне продуктов модуля, 1 - интеграция на уровне сервисов модуля
#om.product.serviceMode=0

Создайте устройство типа Access+Accounting и дочернее к нему устройство типа TelecomTV, укажите хост и порт подключения, логин и пароль.

Добавьте тип аккаунта Аккаунт, установите галочки на "логин" и "пароль", укажите конфигурацию:

# ID устройства TelecomTV
const.device.id=
# Шаблон имени аккаунта
title.pattern=Аккаунт: (${login})

Далее добавьте тип аккаунта для STB, установите галочки на "идентификатор" и "MAC-адрес", укажите конфигурацию, в зависимости от типа приставки:

# Шаблон имени
title.pattern=Yuxing IPTV: (${identifier}) ([${macAddress}])

# Тип приставки в FrontStage Middleware
terminal.typeId=18
terminal.bandwidth=99

В поле Родительские типы поставьте галочку на типе "Аккаунт", который создали только что.

11.3. Middleware Stalker (infomir)

Интеграция с Middleware Stalker представлена в виде отрытого кода (динамические классы).

11.4. CTI TVEngine

Интеграция с CTI TVEngine представлена в виде отрытого кода (динамические классы).

При интеграции с данной системой продукты модуля являются подключаемыми сервисами TVEngine.

После установки TVAccess и TVAccounting скопируйте папку BGBillingServer/lib/endorsed в TVAccess/lib и TVAccounting/lib, если она там отсутствует. Скопируйте BGBillingServer/lib/ext/serializer.jar в TVAccess/lib/ext и TVAccounting/lib/ext. Удостоверьтесь, что в access.sh и accounting.sh есть строка -Djava.endorsed.dirs=${APP_HOME}/lib/endorsed:${JAVA_HOME}/lib/endorsed" именно в таком виде. После этого необходимо перезапустить TVAccess и TVAccounting.

Добавьте конфигурацию модуля, укажите в ней веб-сервисы, к которым будет обращаться TVEngine и установите конфигурацию активной:

# Активные и приостановленные статусы договора
contract.status.active.codes=0
contract.status.suspend.codes=3,4

# Id сущностей (Справочники - Атрибуты) для продукта, сервиса и канала,
# для привязки атрибутов к продуктам, сервисам и каналам
#productSpec.entitySpecId=
#serviceSpec.entitySpecId=
#tvChannelSpec.entitySpecId=

#Пункты Web - меню
web.menuItem1=TV подписки

# Параметры автоматической генерации логина для аккаунта. Можно указать в конфигурации модуля, конфигурации устройства, конфигурации типа сервиса
# (в последнем случае значения будут главнее):
# минимальное значение логина при генерации логина
account.login.min=10000001
# максимальное значение логина при генерации логина (т.е. если в базе присутствуют логины 1,2,3 и 10000000,
# то при генерации создастся логин 4, а не 10000001)
account.login.max=99999999
# форматирование генерируемого логина
#account.login.format=0000000

# Парамерты пароля для аккаунта. Можно указать в конфигурации модуля, конфигурации устройства, конфигурации типа сервиса
# (в последнем случае значения будут главнее):
# минимальная длина пароля
account.password.length.min=4
# Максимальная длина пароля
account.password.length.max=8
# Разрешенные символы (используются также при генерации пароля)
account.password.chars=1234567890ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz
# Описание разрешенных символов, если пользователь ввел другие
account.password.chars.description=В пароле допустимы только цифры и латинские буквы.
# Длина для автоматически генерируемого пароля
account.password.length.auto=6
# Используемые символы для автоматически генерируемого пароля (по умолчанию значение берется из параметра account.password.chars)
#account.password.chars.auto=

# Веб-сервисы биллинга, к которым обращается TVEngine
tv.ws.billing.class=ru.bitel.bgbilling.modules.tv.dyn.cti.tve.ws.billing.impl.BillingServiceWSImpl
tv.ws.pricing.class=ru.bitel.bgbilling.modules.tv.dyn.cti.tve.ws.pricing.impl.PricingServiceWSImpl
tv.ws.order.class=ru.bitel.bgbilling.modules.tv.dyn.cti.tve.ws.order.impl.OrderManagementServiceWSImpl

Обратите внимание, что для этих сервисов нет авторизации, т.е. они должны быть закрыты от внешнего доступа (контекст tv-ws, т.е. http://billing:8080/tv-ws/...).

В конфигурации TVEngine iptvmw-config.properties должны быть указаны пути к этим веб-сервисам биллинга (10 - это код модуля, значение нужно будет заменить):

#--------------------------------------------------------------------------------------------------------
# 1.2 PUSH (EXTERNAL) MODE
#--------------------------------------------------------------------------------------------------------
# type of billing system:
# db - internal billing
# ws - external billing through web-services
# cti - CTI-BILLING
# fastcom - FASTCOM-billing
tve.billing.type=ws
# getting customer status from billing during stb authentication process (default - FALSE)
tve.billing.needGetDataFromBillingDuringStbAuthentication=false
# allows to select OrderManagementService implementation type  (available values:  db , ws, cti, fastcom)
tve.billing.external.orderManagementService.type=ws
# allows to select  BillingManagementService implementation type for 'queryCustomerAccountInfo' method only  (available values:  db , ws, cti, fastcom)
tve.billing.external.billingManagementService.queryCustomerAccountInfo.type=ws
# external billing realization for "askPermissionToActivateOnBilling" method
# (using during set top box registration operation)
tve.billing.external.customerManagementService.askPermissionToActivateOnBilling.type=ws
tve.billing.external.billingManagementService.type=db
tve.billing.external.billingManagementService.queryCustomerAccountInfo.type=ws
tve.billing.external.billingManagementService.queryBillingEntries.type=ws
tve.billing.external.billingManagementService.querySummByService.type=ws


#--------------------------------------------------------------------------------------------------------
# 1.3.1.1 SINGLE BILLING SYSTEM  - setting for single billing PULL mode
#--------------------------------------------------------------------------------------------------------
billadapter.pull.pricingservice=http://billing:8080/bgbilling/tv-ws/ru.bitel.bgbilling.modules.tv.dyn.cti.tve.ws.pricing/10/PricingServiceWS?wsdl
billadapter.pull.orderservice=http://billing:8080/bgbilling/tv-ws/ru.bitel.bgbilling.modules.tv.dyn.cti.tve.ws.order/10/OrderManagementServiceWS?wsdl
billadapter.pull.billingservice=http://billing:8080/bgbilling/tv-ws/ru.bitel.bgbilling.modules.tv.dyn.cti.tve.ws.billing/10/BillingServiceWS?wsdl

После изменения конфигурации TVEngine необходимо его перезапустить (service jetty restart).

Необходимо создать новый тип устройства, назвать его, например, Access+Accounting - данный тип устройства будет отражать приложения TvAccess и TvAccounting.

Далее создайте новый тип устройства, назовите его, например, TVEngine и добавьте конфигурацию:

# Коды параметров договора для заполнения полей в CTI TVEngine
# код параметра договора ФИО или Фамилия (если фамилия указывается отдельно)
customer.lastName.pid=
# код параметра Имя (если он указан отдельно)
#customer.firstName.pid=
# код параметра Отчество (если он указан отдельно)
#customer.middleName.pid=
# код параметра - названия компании (для юр. лиц)
customer.company.pid=
# код параметра - пол
#customer.gender.pid=
# код параметра - дата рождения
customer.birthDate.pid=

Укажите в нем OrderManager - ru.bitel.bgbilling.modules.tv.dyn.cti.tve.TveOrderManager.

Создайте устройство типа Access+Accounting и укажите конфигурацию:

# Обработка/обсчет
# кол-во потоков в обработчике
accounting.worker.1.thread.count=1
# пауза перед следующим выполнением
accounting.worker.1.tracking.account.1.delay=60
# максимальное кол-во обработанных аккаунтов в одном выполнении
accounting.worker.1.tracking.account.1.batchSize=500
# пауза перед следующим выполнением
accounting.worker.1.tracking.event.1.delay=10
# максимальное кол-во обработанных аккаунтов в одном выполнении
accounting.worker.1.tracking.event.1.batchSize=100


# Синхронизация
# кол-во выполняемых задач в одном блоке
om.batch.size=20
# время ожидания завершения future задач
om.batch.pause=0
# время ожидания завершения future задач
om.batch.wait=5
# время ожидания следующей задачи перед закрытием соединения
om.batch.waitNext=5

# пауза после ошибки
om.error.pause=30
# кол-во попыток с ошибкой перед тем как отложить задачу
om.error.redelivery.count=5
# кол-во попыток с ошибкой после которого отправить оповещение
om.error.alarm.count=20
# таймаут задания, выполняющегося с ошибкой
om.error.redelivery.timeout=86400

Данное устройство будет отражать приложения TVAccess и TVAccounting.

Создайте дочернее к предыдущему устройству устройство типа TVEngine, указажите хост подключения, логин и пароль.

Добавьте тип аккаунта Аккаунт, установите галочки на "логин" и "пароль", укажите конфигурацию:

# ID устройства TVEngine
const.device.id=
# Шаблон имени аккаунта
title.pattern=Аккаунт: (${login})

Добавьте тип аккаунта для приставки. Конфигурацию укажите в зависимости от типа приставки:

# Шаблон имени
title.pattern=SagemHD85: (${identifier}) ([${macAddress}])

# Тип приставки в MW CTI TVEngine
stb.type=sagemHD85

В поле Родительские типы поставьте галочку на типе "Аккаунт", который создали только что. В договоре он будет дочерним по отношению к аккаунту типа "Аккаунт".

11.5. Модуль Inet

Интеграция с модулем Inet производится на уровне активных продуктов с помощью опций Inet. В тариф необходимо добавить ветку Продукт, в нее ветку Опция. Внутрь ветки Продукт запрос будет попадать только, если выбранный продукт(ы) на данный момент активен. А уже в модуле Inet, в зависимости от того активна или нет данная опция, можно производить какие-либо действия, например, менять параметры порта на коммутаторе.

Глава 37. Модуль Vidimax

1. Назначение модуля

Модуль Vidimax предназначен для интеграции биллинга с поставщиком услуг video on demand Vidimax. На данный момент модуль предоставляет следующие возможности:

  • автоматическая привязка ЛС Абонента в Vidimax к договору в биллинге.

  • установка тарифов Vidimax на договоре в момент создания ИД абонента.

  • возможность оплаты услуг Vidimax, после привязки, со счета клиента;

  • просмотр платежей и активных тарифов клиента из договора.

2. Настройка модуля

Установите модуль на сервер, обновите клиентскую часть. Затем создайте экземпляр модуля. Создайте в редакторе конфигурации модуля новую конфигурацию, скопируйте туда приведённый ниже текст и введите требуемые параметры. После этого сохраните конфигурацию и сделайте её активной.

#######################################     Обязательные параметры     ################################

# параметр используется при генерации подписи к запросу (выдается Vidimax-ом)
operator.secret=password

# логин и пароль Basic http аутентификации для запроса на списание средств ( вы передаёте Vidimax-у )
basic.auth.login=username
basic.auth.password=password

# логин и пароль Basic http аутентификации модуля на сервере Vidimax ( выдается Vidimax-ом )
vidimax.basic.auth.login=vmusername
vidimax.basic.auth.password=vmpassword

# url для получения тарифных планов( TV и VoD ) к нему после добавиться listActiveTariffsTv или listActiveTariffsVod
url.tariff.active=https://adressVidimax:1234/api/5.0/

# Код наработки услуги по дефолту, это с каким типом наработки будут начисляться наработка
account.default.serviceId=1

#######################################     Рекомендуемые параметры     ###############################
#активные статусы договора, при которых возможно списание средств
contract.status.active.codes=0

# Для отображения названия тарифов в расходах видимакса вместо их кодов, перечислите их как показано ниже.
tariffsIds=0,210,492
tariff.0.title=Тариф 90 руб
tariff.210.title=Тариф 300 руб
tariff.492.title=Тариф 500 руб

# Идентификаторы тарифов которые можно будет добавить абоненту до связывания( из списка tariffsIds ):
tariffsIds.available=492,0

# Описание сервисов видимакса для наглядного их отображения в расходах Видимакса.
serviceIds=1,2,3,4,5
service.1.title=Аренда SD фильма
service.2.title=Аренда HD фильма
service.3.title=Покупка SD
service.4.title=Покупка HD
service.5.title=Абон. плата за тариф

# Вместо account.default.serviceId можно использовать другой код наработки для отдельных типов сервиса Видимакса.
service.1.accountServiceId=41
service.2.accountServiceId=52
service.4.accountServiceId=21

#######################################     Дополнительные параметры     ##############################

# Отключение наработки по тарифам. Введите коды тарифов на которые не будут вешаться наработки( только для Абонентской платы ), то есть вы будете субсидировать клиентов по абонкам данных тарифов.
#tariffsIds.notAccounting=492

# Включение возможности удаления связанных договоров( рекомендуется только на время тестирования модуля )
#contract.canDeletePaired=1

Замечания:

  1. Прежде, чем задавать account.default.serviceId или service.X.accountServiceId(где X код сервиса видимакса) необходимо создать соответствующую услугу в Модули->Редактор модулей и услуг->"Название вашего модуля"

    ,а коды услуг вписать в значения параметров.
  2. После заключения договора с системой Vidimax нужно будет передать им значение URL-адреса, по которому к биллингу будут приходить запросы. URL должен выглядеть следующим образом: http://<адрес_машины_биллинга>/vidimax_api/<mid>.

    Например, если у вас биллинг находится по адресу http://billing.example.com/bgbilling/ и модуль Vidimax имеет mid=17, то результирующее URL, которые нужно передать компании Vidimax, выглядит следующим образом: http://billing.example.com/bgbilling/vidimax_api/17.

  3. Логин и пароль для запроса на списание средств запрашиваются при входящем запросе с сервера Vidimax на списание средств.

3. Принцип работы модуля

Последовательность действий при работе с модулем следующая:

  1. Заводиться договор;

  2. Вноситься номер телефона в модуль( он выступает в качестве идентификатора для Vidimax-а ) и если надо выбирается тариф;

  3. Пользователь подключает приставку и производиться автоматическое связывание ЛС Vidimax-а и Билинга на основании идентификатора;

  4. Далее Vidimax может запросить списание средств;

Алгоритм списания средсв:

  1. Поиск договора с переданным от Vidimax ид. абонента;

  2. Проверка является ли договор связанным;

  3. Проверка является ли статус договор разрешенным для данного модуля( параметр contract.status.active.codes );

  4. Проверка на достаточность средств на договоре( расход Vidimax-a будет отвергнут, если баланс станет ниже 0 в результате этого расхода );

  5. Добавляется наработка на договор( если только данный тариф не входит в параметр tariffsIds.notAccounting и расход является абонентской платой );

4. Мониторинг платежей

В клиенте билинга( а так-же в ЛК клиента ) есть возможность отслеживать историю расходов по каждому абоненту. Для этого необходимо выбрать модуль Vidimax в дереве параметров договора. Платежи можно отображать с фильтрацией по периоду, в течение которого производилось списание средств.

Глава 38. Модуль VoiceIP

1. Назначение модуля

Модуль VoicеIP предназначен для подсчёта стоимости звонков через IP-телефонию. В настоящее время он поддерживает оборудование, которое шлёт запросы RADIUS в стандарте CISCO, а также поддерживается оборудование QUINTUM. Так же как и модуль DialUp, этот модуль использует RADIUS-сервер, установка аналогична установке DialUP.

2. Базовые понятия и алгоритм работы модуля

Структура взаимодействия основных частей модуля VoicеIP изображена на рисунке.

NAS (Network Access Server) - сервер, через который происходит звонок клиента. В роли NASа могут выступать специализированные компьютеры типа Cisco, но практически может быть любое оборудование, способное обеспечивать звонки клиентов по IP и использующее аналогичный с Cisco h323 стандарт RADIUS-запросов.

Обрабатываются три типа запросов: авторизационный, старт и стоп.

Базовые сведения о протоколе RADIUS и конфигурировании атрибутов.

Протокол RADIUS основан на UDP, представляет из себя пакет определённого типа с набором атрибутов. Рассмотрим ход типового соединения по логу RADIUS запросов (radius.log).

В данном случае обмен запросами идёт между RADIUS-сервером и IVR-платформой, запрашивающей данные пользователя и проводящей авторизацию по телефону пользователя.

01 13:13:21
Type=AUTHENTICATION_REQUEST
Attributes:
User-Password=
NAS-IP-Address=81.30.199.58
Service-Type=1
Calling-Station-Id=3472558528
cisco-avpair=h323-ivr-out\u61transactionID:69732
h323-conf-id=585DAE20 CFD411DC 9F39C1A6 BC2D9958

01 13:13:21
Type=AUTHENTICATION_ACCEPT
Process time:10
Attributes:
h323-credit-amount=99540.38
h323-return-code=0

01 13:13:26
Type=AUTHENTICATION_REQUEST
Attributes:
User-Password=
NAS-IP-Address=81.30.199.58
Service-Type=1
Calling-Station-Id=3472558528
Called-Station-Id=6767#79174444339
cisco-avpair=h323-ivr-out\u61transactionID:69732
h323-conf-id=585DAE20 CFD411DC 9F39C1A6 BC2D9958

01 13:13:26
Type=AUTHENTICATION_ACCEPT
Process time:10
Attributes:
h323-credit-amount=99540.38
h323-credit-time=7200
h323-return-code=0

01 13:14:36
Type=ACCOUNTING_REQUEST
Attributes:
User-Name=3472558528
NAS-IP-Address=81.30.199.58
Service-Type=1
Acct-Input-Octets=54043
Acct-Output-Octets=33311
Acct-Status-Type=2
Acct-Delay-Time=0
Acct-Session-Time=57
Acct-Input-Packets=1370
Acct-Session-Id=00033F15
Acct-Authentic=1
Acct-Output-Packets=1136
Calling-Station-Id=3472558528
Called-Station-Id=6767#79174444339
h323-gw-id=pool3.ufanet.ru
h323-voice-quality=31
h323-remote-address=81.30.206.222
h323-disconnect-cause=10
h323-connect-time=13:13:39.562 ESS Fri Feb 1 2008
h323-disconnect-time=13:14:36.387 ESS Fri Feb 1 2008
cisco-avpair=h323-incoming-conf-id\u61585DAE20 CFD411DC 9F39C1A6 BC2D9958
cisco-avpair=subscriber\u61RegularLine
cisco-avpair=session-protocol\u61cisco
cisco-avpair=gw-rxd-cdn\u61ton:4,npi:1,#:2900222
cisco-avpair=release-source\u614
cisco-avpair=remote-media-address\u6181.30.199.118
cisco-avpair=in-trunkgroup-label\u61TG1
cisco-avpair=gw-rxd-cgn\u61ton:2,npi:1,pi:0,si:3,#:3472558528
cisco-avpair=gw-final-xlated-cdn\u61ton:4,npi:1,#:6767#79174444339
cisco-avpair=gw-final-xlated-cgn\u61ton:2,npi:1,pi:0,si:3,#:3472558528
h323-conf-id=585DAE20 CFD411DC 9F39C1A6 BC2D9958
h323-setup-time=13:13:26.192 ESS Fri Feb 1 2008
h323-call-origin=originate
h323-call-type=VoIP

Каждый пакет содержит информацию о NASе (NAS-Identifier и/или NAS-IP-Address), на основании которой RADIUS-сервер сопоставляет пришедший пакет NASу в модуле. При сопоставлении сначала производится поиск NASа с названием, идентичным атрибуту NAS-Identifier пакета, затем, если результат отрицательный, идёт поиск NASа c IP-адресом, равным NAS-IP-Address. Если пришедшему пакету NAS не сопоставлен в radius.log, выводится ошибка NAS not found for Packet!!!.

Обмен сообщениями с каждым NASом шифруется определённым кодовым словом - секретом. Секрет должен совпадать для NASа в биллинге и для конфигурации самого NASа. При несовпадении секретов проверка пароля будет все время выдавать неверный результат, т.к. секрет используется в шифрации пароля.

Идентификатором соединения в пределах NASа для RADIUS-сервера выступает атрибут h323-conf-id. Обратите внимание, что он идентичен для всех пакетов в пределах сессии. NAS должен контролировать, чтобы в один момент времени одинаковый h323-conf-id не проставлялся в RADIUS-пакетах, относящихся к разным сессиям.

Далее рассмотрим попакетно обмен данными между NASом и RADIUS-сервером по ходу соединения.

1. AUTHENTICATION_REQUEST

Запрос авторизации отправляется NASом RADIUS-серверу и содержит помимо идентификационной информации соединения, указанной выше, информацию, идентифицирующую пользователя. Возможна идентификация пользователя по номеру звонящего, логину и паролю (запрашивает IVR) или любому другому атрибуту, режим поиска настраивается для типа логина.

При наличии пароль шифруется по алгоритму PAP с использованием секрета. При некорректном секрете пароль в PAP-режиме не расшифровывается и отображается в radius.log и в мониторе ошибок не в том виде, в котором был введён пользователем.

Передаётся последовательно два запроса авторизации. Первая авторизация передаётся до набора номера и содержит только идентифицирующую пользователя информацию.

Вторая авторизация высылается в случае успеха первой и содержит набранный номер, атрибут Called-Station-Id.

2. AUTHENTICATION_REJECT

Отказ в авторизации, код ошибки авторизации передаётся дополнительно в атрибуте h323-return-code. Детальную причину отказа в авторизации пользователя можно посмотреть в Мониторе модуля в режиме ошибок. Код ошибки авторизации указанный в квадратных скобках в мониторе совпадает со значением, передаваемым в атрибуте. Значение атрибута может быть использовано IVR системой для озвучивания причины ошибки.

3. AUTHENTICATION_ACCEPT

Пользователь авторизован.

Для первой авторизации это означает что он идентифицирован, пароль введён верно (если есть), остаток на балансе положителен, тариф установлен и т.п. В атрибутах передаётся h323-return-code=0 (нет ошибок) и h323-credit-amount=<остатку счета>.

При второй авторизации это означает, что верны все условия первой авторизации, а кроме того на набранный номер есть цена в тарифе. Дополнительно к атрибутам первой авторизации передаются атрибут h323-credit-time=<на сколько секунд разговора хватает баланса пользователя>. Значение данного атрибута ограничивается сверху значением переменной voip.max.time конфигурации модуля.

Дополнительно в AUTHENTICATION_ACCEPT могут передаваться атрибуты, указанные в конфигурации типа логина (см. далее).

4. ACCOUNTING_REQUEST

Модулем обрабатываются запросы аккаунтинга только типа Stop. Атрибут Acct-Status-Type для них равен 2. Данный тип запросов передаёт на RADIUS-сервер информацию о завершении соединения. Врямя соеденения берется из атрибута Acct-Session-Time.

5. ACCOUNTING_RESPONSE

Ответ RADIUS-сервера о том, что он получил запрос аккаунтинга. Ответ не содержит никаких атрибутов.

Возможны схемы работы с учётом только Stop пакетов, без авторизации. В этом случае RADIUS-сервер не может запретить звонок при отсутствии цены в тарифе и, чтобы не потерять его, помещает его в лог без определённого направления и с нулевой стоимостью.

3. Настройка модуля

Установите модуль на сервер с помощью утилиты bg_installer, обновите клиент. Затем создайте экземпляр модуля. Добавьте услугу IP-телефония. Услуга в понятии модуля - доступ к Voip-услугам определённого NASа.

Перезапустите клиента, откройте в меню Модули созданный экземпляр модуля. Создайте в редакторе конфигурации модуля новую конфигурацию, скопируйте туда приведённый ниже текст и сделайте её активной. Значения параметров указаны после символа комментария(#).

#активные статусы договора
contract.status.active.codes=0

#вендоры-производители оборудования и их коды
vendors=9=Cisco;2011=Huawei;2021=Unix PPP;529=Lucent;6618=Quintum;529=Ascend
#минимальная и максимальная длина пароля 
password.length.min=5 
password.length.max=10 
#длина автоматически генерируемого пароля
password.length.auto=6
#допустимые в пароле символы
password.chars=1234567890
#сколько лет отображать в просмотре сессий через web
showyears=5 
#XSL для печати и отправки на почту сессий
xslt.1=voiceip_login_sessions.xsl 
xslt.1.csv=voiceip_login_sessions_csv.xsl
reportTitle.1=Просмотр сессий VoiceIP
#XSL для печати и отправки на почту наработки по логинам 
xslt.2=voiceip_login_amount.xsl 
xslt.2.csv=voiceip_login_amount_csv.xsl
reportTitle.2=Наработка по логинам VoiceIP
#XSL для печати и отправки на почту наработки логина по направлениям 
xslt.3=voiceip_login_direct.xsl
xslt.3.csv=voiceip_login_direct_csv.xsl
reportTitle.3=Наработка логина VoiceIP по направлениям.
#Кол-во выводимых на странице сессий в просмотре сессий в Web-статистике 
show.sessions.on.page=25
#Названия пунктов Web-меню
web.menuItem1=Просмотр сессий VoiceIp
web.menuItem2=Наработка по логинам VoiceIp
web.menuItem3=Смена пароля на логины VoiceIp
web.menuItem4=Наработка логина VoiceIp по направлениям
#Граница не карточных логинов
top.nocard.login=10000
#----------------------------------------
#выборочное отключение проверки закрытого периода
#Перенос логина с даты
#closed.date.disabled.ActionWrapLogin=1
#Перобсчет
#closed.date.disabled.ActionRecalculateSessions=1
#Установка баланса
#closed.date.disabled.ActionSetBalance=1
#Редактирование логина
#closed.date.disabled.ActionUpdateLoginInfo=1
#----------------------------------------

############### опции RADIUS-сервера #######################
#1 - проверять наличие в договоре всех требуемых услуг при авторизации, иначе - ошибка авторизации "Service deny" 
check.service=0
#Код модуля "карточки", 0 - модуль "карточки" не используется
card.module.id=0
#Максимальная длительность сессии
voip.max.time=1800
#Фтрибуты RADIUS, доступные в списке атрибутов в редактировании логина
radius.attributes=Service-Type;Framed-Protocol;Framed-IP-Address;Framed-IP-Netmask;Framed-Routing;Filter-Id;Framed-MTU;Framed-Compression;Login-IP-Host;Login-Service;Login-TCP-Port;Old-Password;Reply-Message;Callback-Number;Callback-Id;Expiration;Framed-Route;Framed-IPX-Network;State;Class;Session-Timeout;Idle-Timeout;Termination-Action;NAS-Identifier;Proxy-State;Framed-Pool
#Игнорируемые Disconnect cause через запятую
#звонки с такими Disconnect cause будут считается нулевой длины (через ,)
voip.ignore.dc=66
#Установка цветов для подсветки Disconnect-Cause в мониторе DC:HEX Color
voip.monitor.dc.color=10:00ff00;3:ff0000;22:ff00ff;11:ffff00
#Режимы поиска логинов
findmode.0.title=Поиск по User-Name=LOGIN
findmode.0.value=User-Name=LOGIN
findmode.1.title=Поиск по User-Name=ALIAS
findmode.1.value=User-Name=ALIAS
findmode.2.title=Поиск по Calling-Station-Id=ALIAS
findmode.2.value=Calling-Station-Id=ALIAS
#
find.order=0,1,2
#
#Цвета ASR(%) и ACD(сек) в отчёте договора, в зависимости от значения
#color.asr=0-30:#dd0000;30-100:#ffffff
#color.acd=0-60:#dd0000

Параметры xslt.1, xslt.2 и xslt.3 должны указывать на XSLT-шаблоны преобразования для печати сессий клиента и отправки их на E-mail. Параметры reportTitle.1 - reportTitle.3 задают тему письма с отчётом и заголовок отчёта. Если все было сделано правильно, настройка модуля завершена.

4. Настройка режимов поиска и типов логинов

Режим поиска представляет собой запись в конфигурации модуля следующего вида:

findmode.<уникальный код>.title=<Название режима поиска>
findmode.<уникальный код>.value=<Название атрибута>=<LOGIN|ALIAS>

Порядок использования режимов поиска задаётся переменной find.order в конфигурации модуля. Например:

# режимы поиска логинов
findmode.0.title=Поиск по User-Name=LOGIN
findmode.0.value=User-Name=LOGIN
findmode.1.title=Поиск по User-Name=ALIAS
findmode.1.value=User-Name=ALIAS
findmode.2.title=Поиск по Calling-Station-Id=ALIAS
findmode.2.value=Calling-Station-Id=ALIAS
#
find.order=0,1,2

означает, что первая попытка поиска идёт среди логинов, где логин равен атрибуту User-Name. Это, например, карточные пользователи. Далее идёт поиск по User-Name=ALIAS и Calling-Station-Id=ALIAS.

Внимание

Режим поиска User-Name=LOGIN должен существовать всегда с кодом 0 для возможности использования карточной платформы.

Параметр find.order может быть переопределён в конфигурации NASа. Например, если у вас выделен отдельный шлюз под карточную платформу, на нем нет необходимости осуществлять поиск по телефону или текстовому логину.

Кроме того, возможно жёсткое задание режима поиска для конкретного запроса в скрипте предобработки RADIUS-запроса. Например, данный скрипт в случае прихода атрибутов User-Name и User-Password в запросе задаёт жёстко режим поиска = 0, т.е. User-Name=LOGIN.

При этом в конфигурации NASа может быть указан find.order, задающий поиск по номеру звонящего.

import java.sql.*;

import bitel.billing.common.*;
import bitel.billing.server.radius.*;

userName = request.getStringAttribute( RadiusStandartAttributes.User_Name );
userPassword = request.getStringAttribute( RadiusStandartAttributes.User_Password );
if( userName != null && userPassword != null )
{
      request.setOption( "find.mode", new Integer( 0 ) );                
}

Тип Voip-логина определяет поведение логина при его поиске и тарификации его сессий. Типы логинов введены, начиная с версии 4.0 и призваны упростить процесс заведения логинов Voip.

В типе указываются режимы поиска для различных видов запросов: авторизационных (входящих и исходящих) и аккаунтинга (входящего и исходящего).

При последовательном поиске по указанным в find.order режимам RADIUS определяет типы логинов, в которых указан данный режим поиска при данном типе запроса. Если список типов пуст поиск не производится.

Рассмотрим иные параметры типа логинов кроме режимов поиска:

1. Режимы тарификации - какой номер использовать при поиске цены входящего и исходящего звонков;

Для операторских логинов возможна тарификация входящих звонков по вызываемому номеру. При этом в тарифном плане оператора стоимость входящих звонков соответствует стоимости терминации данного префикса данным оператором.

Получив отчёт входящих звонков оператора в отчёте договора, можно получить сумму, которую вы должны данному оператору за терминацию им звонков.

2. Проверять пароль - галочка отсутствует у типов логинов с авторизацией по номеру звонящего;

3. Обсчёт баланса (при каждом звонке/никогда) - опция никогда не стоит у операторских логинов для снижения нагрузки на радиус. При этом после каждого звонка не обновляется наработка в балансе пользователя. Для обычных логинов стоит режим обсчёта после каждого звонка.

4. Использовать DC фильтр - обнулять длительность звонка при h323-dicsonnet-couse, попадающим в перечень из параметра voip.ignore.dc. Данная опция обычно снимается для операторских логинов;

5. Игнорировать одиночные ACCOUNTING STOP - данная опция не учитывает STOP-пакеты, пришедшие без предварительной авторизации, и может быть использована для исключения дублирования звонков клиентов в случае их прохождения через несколько NASов.

В системе присутствует тип логина По умолчанию, устанавливаемый карточным логинам. В нем установлен следующий набор опций:

1. Все режимы поиска User-Name=LOGIN (0);

2. Проверка пароля;

3. Использование DC фильтра;

4. Обсчёт баланса при каждом звонке;

5. Стоимость исходящего по вызываемому номеру, входящего по номеру звонящего;

На вкладке Атрибуты можно указать передаваемые при авторизации данного типа логина атрибуты в следующем формате (пример, первый атрибут смысла не имеет, второй используется в MVTS для SIP-аккаунтов):

Cisco-AVPair=lcp:interface-config=ip unnumbered Loopback135
cisco-avpair=xpgk-ep-number=${ALIAS}

В атрибутах могут быть использованы следующие макро-подстановки:

${ALIAS} - первый алиас voip логина;
${BALANCE_MODE} - 0 - кредитовый режим, 1 - дебетовый;
${MIN_COST} - стоимость минуты звонка, десятичный разделитель - точка.

Если значение подстановки не может быть вычислено, атрибут не будет передан. В дополнение к определённым атрибутам обязательно передаются h323-credit-amount (остаток на счёте), h323-credit-time (максимальная длительность звонка по направлению в секундах) и h323-return-code (код ошибки, либо 0 при успешной авторизации).

Для типа логина По умолчанию передаваемые атрибуты указываются в конфигурации модуля в следующем виде:

default.login.attributes=<ATTR_NAME_1>=<ATTR_VALUE_1>;<ATTR_NAME_2>=<ATTR_VALUE_2>

Например:

default.login.attributes=h323-billing-model=${BALANCE_MODE};h323-ivr-in=tariff:${MIN_COST}

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

При каждой модификации типов логинов, конфигурации модуля или NASов необходимо перегружать RADIUS-сервер.

5. Настройка NASов

Основная информация, которую должна содержать конфигурация NASа - это его идентификатор, IP-адрес и секрет (необходим для шифрования пароля пользователя, должен совпадать на RADIUS, клиенте и сервере).

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

Настройка сервера доступа происходит в два шага.

Сначала кнопкой Новый элемент создаётся новый NAS, ему прописывается идентификатор (что будет приходить от него в атрибуте NAS-Identifier), IP-адрес (что будет приходить от него в атрибуте NAS-IP-Address), RADIUS-секрет, вендор и комментарий. Список вендоров задаётся в конфигурации модуля. После нажатия кнопки Ок должна появиться новая строка в таблице.

Вендор определяет код вендора, указываемый для h323-атрибутов, для большинства оборудования он должен быть Cisco.

Двойным кликом мыши откройте её для редактирования и кнопкой Создать добавьте текстовую конфигурацию. Название - произвольное.

Внимание

Возможна также настройка общих конфигураций для NASов. Создание общих конфигураций происходит аналогично описанному далее, за исключением того, что они могут использоваться в нескольких NASах, при этом локальные настройки имеют больший приоритет (т.е. если оба флага присутствуют и во включенной общей, и в выбранной локальной конфигурациях, то будет использован локальный).

Содержимое конфигурации должно содержать следующие данные:

1) Привязанную к NASу услугу: service=<код услуги>;

2) Необходимо настроить какие звонки считать исходящими, а какие - входящими для пользователя. Для определения направления используются атрибуты h323-call-type и h323-call-origin из RADIUS-запроса. Значения этих атрибутов, соответствующие каждому типу звонка, необходимо указать через дробь.

Ниже приведена конфигурация, которая может быть использована для популярного Гейткипера Aqua:

auth.in=voip/originate
auth.out=voip/answer
acct.in=voip/originate
acct.out=voip/answer

В этом случае авторизационные запросы с атрибутами h323-call-type=Voip h323-call-origin=originate будут считаться исходящими, h323-call-type=Voip h323-call-origin=answer входящими.

При необходимости можно указывать несколько сочетаний данных атрибутов через ;. Например:

acct.out=voip/answer;voip/proxy

STOP-пакет исходящего звонка может содержать как сочетание Voip Answer, так и Voip Proxy. Процесс подборки данных атрибутов эмпирический и зависит от вашего оборудования.

Если через ваш шлюз идут только исходящие вызовы, можно определить следующую конфигурацию. В этом случае всякий вызов будет воспринят как исходящий.

auth.out=all/all
acct.out=voip/originate

С версии 5.1 есть возможность отрезания реалма типа @xxx от атрибута, используемого как имя пользователя. Для этого в конфигурацию необходимо добавить, например:

realm.attr=User-Name
realm.value=ipnet.ru,voipnet.ru

Для идентификации сессии можно имспользовать значение атрибута Acct-Session-Id, для этого в конфигурацию добавить:

acct.session.id=1

Для вывода ошибок, при невозможности определить направление звонка, в конфигурацию нужно добавить:

acct.logError=1

Для полной обработки входящих звонков в конфигурацию нужно добавить:

auth.income.full=1

Подробные инструкции по интеграции BGRadiusVoip с различными NASами доступны в Wiki.

5.1. Скрипт предобработки запроса

На вкладке Скрипт предобработки может быть написан BGS скрипт предобработки, определяющий перечисленные ниже параметры каким-либо сложным способом, для которого недостаточен формат конфигурации. Параметры, заданные скриптом, более приоритетные, чем взятые из конфигурации.

  • Тип звонка - request.setFlag( int callTypeFlag );

  • Тип поиска - request.setOption( "find.mode", int mode );

  • Услуга звонка - request.setOption( "service", int service ).

Вы можете посмотреть примеры скриптов предобработки запросов в WiKi.

Замечание

Скрипты обработки RADIUS-запросов кэшируются RADIUS-сервером при первом исполнении. Для сброса кэша необходимо перезапустить RADIUS-сервер, либо выполнить команду в каталоге RADIUS-сервера.

Для Linux:

./radius.sh flush_script_cache

Для MS Windows:

radius.bat flush_script_cache

Логи работы скриптов вы можете посмотреть в файле BGBillingServer/log/script.log

6. Монитор

В отличие от монитора DialUP модуля здесь отсутствует режим Текущие, т.к. модуль фиксирует соединения только по STOP-пакету RADIUSa. В режиме логов есть фильтр для выделения звонков с ненулевой длительностью и только платных. В первом столбце таблицы сессий отображается направление звонка "<<" - исходящий, ">>" - входящий.

В последнем столбце выводится Disconnect-Cause - причина разрыва, цвета ячейки можно задать в конфигурации модуля. Принципы выбора периодов, фильтрации сессий и ошибок по логину идентичны монитору модуля DialUp.

Перечень типов ошибок в мониторе и их расшифровка:

Таблица 38.1. Таблица кодов ошибок

Код ошибкиНазваниеОписание
1Неверный пин-код картыКарта найдена, но введённый пароль не соответствует её пин-коду.
2Неверный пароль логинаЛогин найден, но введённый пароль не соответствует его паролю.
3Тарифные планы не найденыУ договора не установлен ни один тарифный план для данного модуля на день авторизации.
4Ошибка балансаОстаток баланса договора меньше лимита договора.
6NAS не найденRADIUS-пакету не сопоставлен NAS в модуле.
7Не найден код услугиВ конфигурации NASа не определены коды услуг.
8Карта просроченаИстёк период годности карты.
9Карта заблокированаКарта не передана дилеру.
10Карта активирована на балансКарта уже активирована для пополнения баланса.
11Цена не найденаНа одну или несколько услуг, заявленных в конфигурации NASа, не найдена цена в тарифном плане.
12Соединение не может быть установлено.В пакете либо нет атрибута h323-conf-id, либо нет логина (атрибуты User-Name или Calling-Station-Id).
13Тип звонка не определёнТип Voip-звонка не установлен на основании анализа пакета.
14Логин и карта не найденыНе найдены ни логин, ни карта по данным пакета.
15Нет денег на звонокНедостаточно средств для минуты звонка.
16Звонок не тарифицируетсяДанный тип вызовов не тарифицируется в биллинге (указано в типе логина).
17Невозможно активировать карту на этом NASеКарта не может быть активирована на данном NASе, её услуга активации не прописана в параметре card.activate.service конфигурации NASа.
26Доступ заблокированДоступ логина установлен в Запрещён.
32Префикс ЗапрещёнЗвонок запрещён узлом Запрещение звонка.
33Договор не активенСтатус договора не позволяет авторизовать логин.
35Истек срок жизни карточного договораУ договора, для создания которого активирована карта, закончился период действия.
40Направление не найденоВ тарифном плане не указано направление звонка.

Возможно изменение текста отображаемой ошибки, для этого в конфигурации модуля указывается:

error.message.code.<code>=<название>

Где <code> - код ошибки, <название> - отображаемое в таблице название.

7. Настройка RADIUS-сервера для VoiceIP

Замечание

BGRadiusVoip обновляется как обычное серверное приложение биллинга. Необходимо обновить приложение перед первым запуском.

Внимание

Необходимо перезагружать BGRadiusVoip при любом изменении конфигурации модуля, типов логинов, либо конфигурации NASов. Считывание этих конфигураций происходит только при старте RADIUS-сервера.

7.1. Установка BGRadiusVoip на платформу Linux

1) Извлеките BGRadiusVoip из архива и скопируйте в каталог /usr/local;

2) Перейдите в каталог /usr/local/BGRadiusVoip;

3) Удалите все .ini, .bat и .exe файлы:

rm -f ./*.bat & rm -f ./*.exe & rm -f ./*.ini

4) Откройте для редактирования файл radius.sh и пропишите в нем путь к Java-машине, например, так:

...
cd ${0%${0##*/}}.

JAVA_HOME=/opt/java/jdk16

if [ -z "$JAVA_HOME" ]; then
  echo "The JAVA_HOME environment variable is not defined"
  echo "This environment variable is needed to run this program"
  exit 1
fi
...

5) Проверьте .sh файлы на наличие символов ^M, если символы присутствуют их можно удалить вручную, либо воспользоваться утилитой:

dos2unix *.sh

6) Установите права запуска для всех *.sh файлов:

chmod 744 *.sh

7) Возьмите из каталога BGRadiusVoip/script скрипт запуска bgradius_voip и скопируйте его в каталог /etc/init.d, установите права на исполнение (см. выше);

8) Выясните текущий уровень запуска системы командой:

[root@gate init.d]# runlevel
N 3

9) Создайте линк для автоматического запуска RADIUS-сервера:

ln -s /etc/init.d/bgradius_voip /etc/rc5.d/S99bgradius_voip

10) Произведите настройку radius.properties и запустите RADIUS-сервер (см. далее).

7.2. Установка BGRadiusVoip на платформу Windows

Для установки BGRadiusVoip на платформу Windows на диск С:.

1) Убедитесь, что на машине, где вы собрались ставить RADIUS, стоит Java-машина. Если её нет, установите версию не меньше 1.6.0. Загрузить можете с нашего сайта;

2) Загрузите с сервера RADIUS-сервер для VoiceIp;

3) Распакуйте архив на диск C: ;

4) Установите переменную окружения BGRAD_HOME_VOIP=C:\BGRadiusVoip. Как устанавливать переменные окружения можете посмотреть в инструкции по установке сервера и клиента биллинга;

5) Установите службу BGRadiusVoip, для чего запустите файл radius_install.bat;

6) Убедитесь, что служба появилась в списке служб Windows. В дальнейшем, можете удалить эту службу, используя radius_uninstall.bat .

7.3. Настройка radius.properties

Откройте файл radius.properties и произведите настройку:

#Процессор-обработчик запросов
processor.class=ru.bitel.bgbilling.modules.voiceip.radius.VoiceIpRadiusProcessor
#Код модуля VoiceIP
processor.mid=XXX

#Порты авторизации и аккаунта
auth.port=1812
acct.port=1813
admin.port=1955

#Опции подключения к БД
db.driver=com.mysql.jdbc.Driver
db.url=jdbc:mysql://127.0.0.1/bgbilling?useUnicode=true&characterEncoding=UTF-8&allowUrlInLocalInfile=true&zeroDateTimeBehavior=convertToNull&jdbcCompliantTruncation=false
db.user=bill
db.pswd=bgbilling

#Опции подключения к MQ
mq.url=failover:(nio://127.0.0.1:61616)
mq.user=bill
mq.pswd=bgbilling

Установите переменную processor.mid=<числовой код экземпляра модуля VoiceIP>. При необходимости скорректируйте параметры доступа к базе данных и к MQ-серверу. Параметры auth.port и acct.port - порты, на которых сервер будет слушать авторизацию и аккаунт. Установлены значения по умолчанию. Параметр admin.port определяет порт, на котором работающий процесс BGRadiusVoip открывает сокет управления, данный порт не должен быть доступен с других машин. Если на этой же машине установлены другие сервера, использующие такие же порты, их следует изменить.

Замечание

Изменения описанных в данном разделе параметров в radius.properties применяются только после перезапуска BGRadiusVoip. Все иные настройки могут быть изменены в ходе работы приложения и применяются при редактировании NASов и их конфигураций, редактировании конфигурации ядра (система алармов), конфигурации модуля.

7.4. Управление BGRadiusVoip

Для запуска и останова сервера RADIUS для VoiceIp используйте:

1) для Windows: консоль запуска и управления службами, служба BGRadiusVoip;

2) для UNIX: скрипты radius_start.sh и radius_stop.sh.

После запуска посмотрите логи в папке BGRadiusVoip/log.

radius.log - распечатка пакетов запросов и ответов;
radius.out - выходной поток, критичные ошибки;
connection.log - лог хода соединения, обсчетов.

Если запуск прошёл успешно, в логе connection.log должен вывестись список загруженных NASов, указанных вами в модуле Voip.

В radius.log должно быть сообщение вида:

INFO   18.05.2004 13:04:41 Starting radius auth_port:1812  acct_port:1813 admin_port:1899
INFO   18.05.2004 13:04:41 Init processor 
class: bitel.billing.server.processor.voiceip.VoiceIpProcessor
mid: 6

NFO   18.05.2004 13:04:42 Starting PortListener port=1812|type=AUTH_LISTENER
INFO   18.05.2004 13:04:42 Starting PortListener port=1813|type=ACCOUNT_LISTENER
INFO   18.05.2004 13:04:42 Starting PortListener port=1899|type=ADMIN_LISTENER

Это свидетельствует о том, что сервер запущен и ожидает пакеты.

Если сервер не запустился, ищите причину в файле radius.out. В него пишутся все критические ошибки.

С работающего RADIUS-сервера возможно получение с сервера списка соединений и статуса. Это достигается запуском скрипта radius.bat(.sh) с параметрами. Список параметров можно получить простым запуском radius.bat(.sh). Ниже приведена выводимая при этом справка:

Usage: [start|stop|help|status|ps|kill|flush_script_cache]
Parametrs:
 help|?    - show this help
 start     - starting RADIUS server
 stop      - stopping RADIUS server
 status    - current connections status
 flush_script_cache  - flush BGS script cache
######## Only for DialUp RADIUS #########
 ps        - active connections list 
 kill [-port <#port>] [-nas ] [-login <#login>]
           - kill connections by filter
 kill doesn't work with empty params list

Example: radius.sh start
Example: radius.sh kill -nas supernas.bayan.com -login 11

radius.sh(.bat) status - краткий статус сервера

[bill@bill-2 radius_voip]$ ./radius_status.sh
version 4.2 from 16.05.2007
19.02.2008 17:32:34     Request for minutes:
        Account for min: 98; for five min: 619; for ten min: 1253
        Auth for min: 39; for five min: 191; for ten min: 381
Waiting connections: 63
Started: 05.09.2007 06:10:13    Uptime: 167 d 12:22:20
Memory total: 291 176 448; max: 807 796 736; free: 40 794 064
Trees in cache: 28      Connections pool status Idle: 35; Active: 0; maxActive: 300; maxIdle: 100

Выводимая информация построчно:

  1. Версия, номер и время сборки BGRadiusVoip;

  2. Текущее время;

  3. Количество запросов аккаунтинга в минуту, пять минут и десять минут;

  4. Количество запросов авторизации в минуту, пять минут и десять минут;

  5. Время старта и uptime BGRadiusVoip;

  6. Зарезервированная память, максимально доступная память и свободная в зарезервированной области память;

  7. Количество тарифных деревьев в кэше, число соединений с БД, простаивающих, активных, максимально допустимых активных и максимально допустимых простаивающих. Настраивается в radius.properties.

radius.sh(.bat) flush_script_cache - сброс кэша скриптов предобработки RADIUS-запросов.

8. Настройка клиентов

Для подключения модуля к договору добавьте в него экземпляр модуля, выбрав узел Модули дерева договора и выбрав модуль из списка установленных модулей. Добавление разрешённых услуг модуля имеет смысл при установке опции check.service=1 в конфигурации модуля. Клиент не сможет авторизоваться, если в договоре не будет хотя бы одной из прописанных на NASе услуг.

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

Числовые логины выдаются последовательно и не могут быть изменены. Они могут быть использованы для идентификации, так же как Алиасы. У каждого логина могут быть установлены несколько Алиасов (перечисленных через пробел), в которых могут быть, например, номера телефонов клиентов, их IP-адреса, либо другие идентификаторы на гейткиперах. Отличия алиаса в том, что в нем могут быть указаны произвольные значения (при отсутствии конфликтов с алиасами других логинов).

Каждому логину указывается тип, определяющий его поведение при поиске и обсчёте. Поиск логина может производится путём сопоставления произвольных атрибутов RADIUS-запроса с числовым логином либо алиасом, все зависит от настройки режимов поиска. Обратите внимание на поле ручной установки баланса в нижней части таблицы, он необходим для типов логинов, для которых не осуществляется обсчёт после каждого звонка.

При выборе записей в таблице логинов и нажатии правой кнопкой мыши отображается всплывающее меню.

Пункт Перенести на другой договор переносит логин из одного договора в другой (карточка должна быть открыта в текущий момент), при этом перемещается и вся наработка по данному логину. При переносе переносится наработка по логину только на период действия логина.

Пункт Перенести на другой договор с даты закрывает логин на существующем договоре и открывает аналогичный логин на целевом договоре с другим периодом. Все алиасы и свойства логина копируются. Возможен перенос только логина с неустановленной датой закрытия.

В обоих режимах перераспределение наработки между договорами происходит автоматически, но для этого должен быть запущен планировщик заданий.

9. Интеграция с модулем "Карточки"

Производится аналогично модулю DialUP.

Поиск по базе карточек производится при авторизации, если последовательно не был найден клиент с использованием указанных режимов поиска. При поиске карты используется значение поля User-Name, которое сравнивается с логином карты. Если карта найдена и не активирована, то создаётся договор с шаблоном, указанным в карте, а в него заносится логин с типом По умолчанию.

При следующем звонке RADIUS-сервер должен найти этот логин, для этого в режимах поиска должен присутствовать метод User-Name=LOGIN.

10. Настройка тарифных планов

Определение стоимости звонка производится по префиксу и типу звонка (входящий/исходящий). Кроме того, для отчётности все звонки делятся по направлениям. Для создания нового направления откройте вкладку Модули=>Модуль IP телефонии=>Справочники. Логика поиска тарифа соответствует Алгоритму 1.

В данном модуле единственный справочник - направлений. Для того чтобы редактировать его используйте панель инструментов.

Замечание

Для добавления направлений вы можете также использовать контекстные редакторы в дереве тарифного плана.

Задача тарификации в модуле - определение стоимости минуты, направления звонка и параметров тарификации (опционально). Исходными параметрами тарифного запроса выступают:

Услуга звонка - определяется в конфигурации NASа;
Тип звонка - входящий/исходящий;
Номер - в зависимости от типа звонка и типа логина либо входящий, либо исходящий;
Время начала звонка - может быть использовано для определения льготных периодов.

Последовательно запрос передаётся во все персональные тарифные планы договора, затем в глобальные тарифы, установленные для договора. Просмотр тарифов идёт в порядке позиций, выбираются только тарифные планы с периодом действия, включающим дату начала звонка и содержащие тарифное поддерево для данного экземпляра модуля.

Обработка прекращается, если тариф вернёт в запросе следующие данные:

Стоимость минуты звонка;
Направление звонка;
Параметры тарификации (не обязательно).

Верхний узел в каждом тарифе - типа Услуга. В нем нужно определить услугу, для которой определяется стоимость. В модуле может быть несколько услуг, услуга привязывается к NASу (см. конфигурацию NASов). Таким образом, вы можете дифференцировать стоимость звонка через разные шлюзы.

Далее тарифный план может быть построен двумя путями. Описание логики работы узлов вы можете найти здесь.

10.1. Тарификация по префиксам

Разбор префикса производится непосредственно в тарифном плане, с использованием узлов Часть префикса, Диапазон префиксов.

Приведённый ниже тариф устанавливает стоимость входящих и исходящих вызовов с пятизначных номеров как нулевую. Направление на Россию, Башкирию и Уфу заблокированы с помощью узла Запрещение звонка. Этот узел специфичен для модуля VoiceIP - при прохождении запроса через него в момент авторизации пользователя выдаётся ошибка авторизации Prefix deny.

Следующий тариф определяет стоимость звонков по всем направлениям с помощью узла Часть префикса, в последних версиях биллинга часть из этих узлов может быть заменена Диапазоном префиксов. На направление USA определена льготная и обычная цена, с использованием узла Фильтр по времени. В последних версиях этот узел также может быть заменён Фильтром по типу времени.

Построение тарифов по методу непосредственного разбора целесообразно для небольших тарифов (терминация трафика оператора), либо для тарифов, которые не могут быть приведены к перечню зон с равными ценами.

10.2. Тарификация по зонам.

В тарифном плане возможно использование фильтра по типам времени и зоновой тарификации. Зоновая тарификация основывается на справочнике географических кодов и картах зон, логика работы их совершенно идентична модулю телефонии.

Пример тарифного плана, использующего обе эти возможности, приведён на скриншоте. Использование типов времени особенно удобно в больших тарифных деревьях. Справочники географических кодов и карт зон модулей Телефонии и IP-телефонии могут быть импортированы и экспортированы друг в друга.

Следующий пример тарифа предоставляет квоту на зону Россия 1 в 100 минут в месяц на каждый логин. Флаг Пропорционально периоду означает, что если логин был активен только часть месяца, квоты будут пропорционально уменьшены. При превышении квоты по зоне стоимость минуты различается в зависимости от времени.

10.3. Тарификация по карте цен.

Тарификация по карте цен аналогична модулю телефонии.

10.4. Смешанный режим

Подходит при наличии некоторых исключений из зонового тарифа. Перед зонами размещаются части префикса. В них необходимо устанавливать фиктивную зону для предотвращения повторной тарификации в узле Зона. Направление берётся из справочника тарифных зон.

10.5. Модификация стоимости звонка

C 4.1 версии в наследованных тарифах возможно использование Множителя цены. Принципы его использования можно посмотреть здесь.

C 4.3 версии биллинга в наследованных тарифах возможно использование узла Изменение стоимости. При прохождении тарифного запроса через данный узел стоимость минуты звонка, либо всего звонка целиком может быть увеличена. Ниже приведён пример, как в расширенном тарифе стоимость каждого звонка увеличивается на 10 рублей. Данная функция может быть использована для любого типа тарифов.

10.6. Импорт/экспорт тарифов

Тарифные планы IP-телефонии могут быть экспортированы и импортированы из XML-формата. Данная возможность описана здесь.

11. Работа с операторами

Модуль IP-телефонии позволяет организовать полноценную работу с операторами Voip с учётом терминации и оригинации трафика.

11.1. Старая схема

Логины операторов заводятся аналогично обычным логинам, но в типе операторского логина устанавливаются опции обсчёта входящих звонков по вызываемому номеру. В тарифных планах операторов стоимость входящего звонка соответствует той цене, которую мы платим оператору за звонок через него. Она должна быть установлена отрицательной.

Стоимость в тарифном плане оператора соответствует той цене, которую оператор должен нам за терминацию его звонка.

Таким образом, положительный баланс оператора означает его долг нам, а отрицательный - нашу задолженность ему. Платежи оператора заносятся как приходы. Наши платежи оператору заносятся как расходы.

В свойствах логинов операторов необходимо отключить обсчёт баланса, для его обсчёта используется ручной режим.

На скриншоте изображена панель запуска ручной установки баланса, её необходимо производить каждый раз, как только требуется узнать текущий баланс оператора. В случае, если вы не устанавливали баланс за прошлый месяц, необходимо сначала установить баланс предыдущего месяца, а затем текущий.

С 4.4 версии возможна групповая установка баланса для всего модуля на вкладке Переобсчёт звонков. Необходимо выбрать месяц и нажать Установить баланс.

Также возможна настройка задачи планировщика Установка балансов VoiceIP. В параметрах задачи должно быть указано mid=<код экземпляра модуля VoiceIP>. При выполнении задача берет месяц предыдущего от текущего часа и производит установку балансов на этот месяц.

Более простым является вариант использования положительных цен, в таком случае баланс не используется вовсе, а для сверок берутся значения отчётов по входящим и исходящим сессиям оператора.

Примерная организация тарифных планов может выглядеть следующим образом: создаётся БАЗОВЫЙ тариф, включающий в себя дерево всех направлений и префиксов + стоимость исходящих звонков. Этот базовый тариф может использоваться для тарификации карточных договоров.

Для каждого оператора устанавливается этот тариф, после чего он расширяется и устанавливаются входящие цены оригинации на данного оператора + исходящие цены звонков по различным направлениям для договора.

Обратите внимание, что цена исходящего звонка из базового тарифа перекрыта ценой исходящего звонка из тарифа-расширения.

Также в тарифах операторов могут использоваться "Цены по умолчанию".

Цена по умолчанию проставляется в тарифный запрос только, если в нем уже нет другой цены. Например, в данном случае происходит разбор тарифа по тарифному дереву, т.е. обработка запроса идёт до совпавшей ветке и если звонок идёт на ..4613.., то запрос будет помечен обработанным на узле "Нефтьюганск", после чего все остальные узлы дерева префиксов будут пропускать его без обработки. Направление звонка также будет установлено в "НЕФТЬЮГАНСК".

Если установить простую цену в конце 46 узла, то она будет прописывать себя во все проходящие через нее запросы, т.е. если мы поместим спец. цену на 12 узел, она будет перетёрта в дальнейшем при прохождении цены в конце 46 узла.

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

11.2. Новая схема

Тарификация стоимости звонка для оператора осуществляется во время тарификации звонка клиента. Для этого используется узел тарифа Тарифицировать оператора, в котором указывается ссылка на тариф оператора. Из него извлекается подходящая цена и правила округления.

Чтобы разделить тарификацию на разных операторов используется узел Оператор. Операторы задаются в конфигурации модуля:

#Название
operator.1.title=VTK
#Код(id) договора-оператора
operator.1.cid=135121
#Наработку по оператору c кодом услуги 813 класть в наработку договора с кодом услуги 813
operator.1.account.813=813
operator.2.title=Совинтел
operator.2.cid=135122
#Всю наработку по оператору класть в наработку договора с кодом услуги 4
operator.1.account.4=all

Для привязки звонка к оператору необходимо устанавливать его код в скрипте предобработки запроса наса:

import bitel.billing.server.radius.*;

prefix = "remote-media-address";
length = prefix.length();

attributes = request.getVendorAttributes( Vendors.CISCO, CiscoVendor.Cisco_AVPair );
if( attributes != null )
for( it = attributes.iterator(); it.hasNext(); )
{
    ra = it.next();
    value = ra.getStringValue();

    if( value.startsWith( prefix ) )
    {
        if( value.endsWith( "77.82.17.33" ) )
        { 
            request.setOption( "operator", 1 );
            break;
        } 
        else if( value.endsWith( "172.36.104.61" ) )
        {
            request.setOption( "operator", 2 );
            break;
        }
    }
}

Т.е. в зависимости от содержимого пакета нужно установить request.setOption( "operator", <код оператора> ).

Также следует учитывать, что скрипт предобработки запроса отрабатывает на каждом запросе, при этом установка кода оператора отрабатывает на запросе аутентификации и на Stop-пакете. Если установка произойдет оба раза, то запомнится значение обработки Stop-пакета.

Код оператора сохраняется в звонке, так что при переобсчете ветка Оператор также будет учитываться.

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

Для создания наработки на операторских договорах необходимо в конфигурации модуля указать привязку: код договора - услуги, которые принадлежат этому оператору и указать код услуги модуля, на который будет ложиться наработка в договоре оператора.

#Пример конфигурации для договора оператора с кодом (id договора) 455
#Код договора, на который будет ложиться наработка
operator.1.cid=455
#Коды абонетских услуг, наработка по которым будет суммироваться и ложится в наработку с кодом 4
operator.1.account.4=10,11
#Или же можно указать звонки оператора с любым кодом услуги
#operator.1.account.4=all

Для того чтобы наработка на договоре оператора обсчитывалась нужно настроить задачу планировщика Установка балансов VoiceIP. В параметрах задачи должно быть указано mid=<код экземпляра модуля VoiceIP>. При выполнении задача берет месяц предыдущего от текущего часа и производит установку балансов на этот месяц.

11.3. Оценка операторов

Для оценки стоимости звонка через разных операторов начиная с 4.3 версии в модуле добавлена вкладка Оценка операторов. Необходимо выбрать группу операторских договоров, префикс и запустить поиск.

В договорах должен быть установлен операторский тариф.

Для каждого оператора будет найдена цена входящего звонка по данному префиксу, далее будет выведена сводная таблица.

12. Отчёты

Доступны оперативные отчёты по Сессиям, Наработке и Направлениям.

Для получения отчёта по сессиям - выберите один или несколько логинов и нажмите кнопку вывода отчёта (галочка). Отображаются только те логины, период которых пересекается с указанным для поиска периодом. Дополнительно можно установить фильтр по номеру звонящего, при этом будут выведены только звонки, где в номере звонящего есть указанная подстрока. Также можно установить фильтр для вывода только платных звонков, только входящих, либо только исходящих. Двойной клик мышью в строке отчёта по сессиям показывает RADIUS-лог по текущей сессии.

Для вывода отчёта по наработкам достаточно выбрать месяц и нажать кнопку вывода. Будут отображены суммарные количества сессий, суммарное время по всем логинам договора. Здесь также действуют фильтры по номеру, направлениям звонка и платности.

Отчет по направлениям показывает наработку выбранных логинов в разрезе конечных пунктов звонка (направлений), либо исходящих пунктов звонка для входящих звонков. Чтобы посмотреть все звонки логина по данному направлению, получите отчёт по направлениям и дважды кликните по строке с интересующим вас направлением. Будет выдан отчёт по сессиям с сессиями только по этому направлению.

Параметр ASR рассчитывается как ASR=КОЛИЧЕСТВО_НЕНУЛЕВЫХ_ЗВОНКОВ/ОБЩЕЕ_ЧИСЛО_ЗВОНКОВ по направлению. ACD рассчитывается как ACD=СУММАРНАЯ_ОКРУГЛЕННАЯ_ДЛИТЕЛЬНОСТЬ_ЗВОНКА/КОЛИЧЕСТВО_ЗВОНКОВ * 100% по направлению.

Данные параметры помогают оценить качество связи по направлению и особенно интересны в отчёте операторского договора. Для большего удобства ячейки имеют цветовую индикацию. Цвета столбцов с ASR и ACD задаются в конфигурации модуля следующим образом:

color.asr=0-30:dd0000;30-100:ffffff
color.acd=0-60:dd0000

Здесь 0-30, 30-100, 0-60 - диапазоны параметров, через двоеточие после них указывается цвет ячейки.

Также имеется возможность выгрузки отчётов в CSV и HTML-формате. Для это необходимо нажать на кнопку Сохранить (кнопка с дискетой) и указать интересующий формат файла.

13. Web-интерфейс

Предоставляет доступ к тем же отчётам, что и в АРМ администратора клиенту через страницу статистики. Можно изменять название пунктов меню редактируя параметры web.menuItem1-web.menuItem3 в конфигурации модуля.

14. Переобсчёт сессий

Данная возможность используется для пересчёта сессий задним числом. Например, при неверно указанных ценах. Для пересчёта сессий зайдите на вкладку Переобсчёт звонков, затем выберите группы договоров, чьи сессии нужно переобсчитать, типы звонков и т.п.

Отчет о переобсчёте будет выслан на указанный E-mail. Не забудьте проверить опции почты в настройке сервера биллинга.

15. Создание договоров пользователем через Web

Модуль поддерживает создание договоров самим пользователем через специальную страницу.

URL страницы активации:

http://<адрес сервера биллинга>:8080/bgbilling/pubexecuter?action=CreateContract&module=voiceip&mid=<код модуля>

Шаблон страницы - файл voice_create_contract.xsl в нем необходимо подправить параметр формы mid на правильный код модуля.

Дополнительно необходимо указать в конфигурации модуля:

#Код шаблона договора
web.register.contract.pattern=
#Код параметра ФИО
web.register.fio.param=
#Код параметра e-mail
web.register.email.param=
#Код флагового параметра "разрешить поиск в справочнике"
web.register.refbook.param=
#Диапазоны доступных номеров, например 200000-250000;300;200-201
web.register.alias.range=
#Тип логина
web.register.login.type=

Глава 39. Модуль WebMoney

1. Назначение модуля

Модуль WebMoney предназначен для проведения платежей через систему Merchant WebMoney Transfer. Для работы в нетестовом режиме у вас должен быть аттестат продавца (разновидность персонального) системы WebMoney

2. Настройка модуля

Проинсталируйте модуль на сервер, обновите клиент. Затем создайте экземпляр модуля. Создайте в редакторе конфигурации модуля новую конфигурацию, скопируйте туда приведённый ниже текст и сделайте её активной.

#режим работы модуля: 0 - выкл, 1 - вкл, 2 - вкл/тест
wm.mode=2
#адрес к биллингу
wm.path=http://localhost/bgbilling/
#кошелёк, с которым работает модуль (той же валюты, с которой работает биллинг!)
wm.payee_purse=
#комментарий, который будет показан пользователю при оплате
wm.comment=Оплата по дог. ${contract} (${contract_comment})
#комментарий, который будет привязан к платежу
wm.payment_comment=Оплата по дог. ${contract} через WM-Merchant(WM# ${payer_wm}, ${payer_purse}) от ${trans_time}
#secretkey (длина до 50 символов)
wm.secretkey=
#id типа платежа (например, создайте тип платежа WebMoney и укажите здесь его id)
wm.paymenttype=

Примечание: чтобы узнать id выберите нужный тип платежа в справочнике и нажмите Ctrl+i

Настройте сервис MerchantWM

Введите торговое имя, secretkey, оставьте пустыми поля URL, галочку на Высылать SecretKey. Поставьте галочку на "Передавать параметры в предварительном запросе", "Позволять использовать URL, передаваемые в форме" и ,если необходимо, "Высылать оповещение об ошибке платежа на кипер".

Установите метод вызова Succes URL и Fail URL на POST, метод формирования контрольной подписи на MD5.

Переключите Активность на Вкл.

Переключение из тестового в рабочий режим возможен только при наличии аттестата продавца.

3. Оплата через Merchant WebMoney Transfer

Если у абонента подключён экземпляр модуля, то он может произвести оплату услуг через Web-интерфейс (пункт меню Оплата через WebMoney). Здесь же клиент может просмотреть все проведённые им платежи через WM:

При нажатии кнопки Пополнить счёт клиент попадает на новую страницу, с формой для ввода суммы.

При нажатии кнопки Принять клиент сначала переходит на страницу подтверждения биллинга, а затем к системе Merchant WebMoney Transfer, где может выбрать удобный для себя способ оплаты.

4. Безопасность

При нажатии клиентом кнопки Подтверждаю платёж Merchant WM последовательно производит два запроса в биллинг: предварительный и оповещающий об оплате. При первом запросе модуль проверяет правильность данных и разрешает или же запрещает (например, если модуль в режиме выключен) проведение оплаты на кошелёк. Если биллинг разрешил платёж WebMoney Transfer сразу же (!) производит транзакцию и отправляет второй, оповещающий запрос, в котором, кроме служебных данных, посылается контрольная подпись, созданная из суммы этих служебных данных (почти все из них уникальны) и secretkey (который в запросе не посылается). Модуль проверяет контрольную сумму и, если она совпала, пополняет баланс клиента.

Таким образом secretkey должен быть длинным и не подбираемым (в системе Merchant WM secretkey может быть длиной до 50 символов).

Внимание! В предварительном запросе Merchant WM не посылает контрольную подпись, поэтому если в момент платежа в конфиге биллинга и настройках Merchant WM secretkey будут различными, то транзакция будет проведена, но баланс в биллинге не пополнится. Поэтому при изменении secretkey и вообще при изменении каких-либо параметров модуля настоятельно рекомендуется перевести режим модуля в состояние выключен опцией wm.mode=0, подождать завершения транзакций, которые могут проходить в данный момент (при стабильной работе оба запроса происходят практически в одно время) и только потом изменять настройки.

Все платежи, не прошедшие проверку контрольной подписи (но прошедшие все другие проверки), попадают в базу как не проведённые.

5. Слежение за платежами

В параметрах договора можно посмотреть все платежи, как проведённые, так и не проведённые (см. Безопасность)

В параметрах модуля есть глобальный монитор

6. Коды ошибок

Ошибки проведения платежа представлены в битовой маске, т.е ошибка 384(110000000) это две ошибки из списка:

  • 0x01 - 1 - неверный запрос (не все и/или неправильные параметры, подразумевается запрос не от merchant)

  • 0x02 - 10 - 0x04 - 100 - неверная подпись в запросе (либо неверно указан secretkey в конфиге, либо запрос не от merchant)

  • 0x08 - 1000 - в запросе указан кошелёк, отличный от указанного в конфигурации

  • 0x10 - 10000 - тестовый режим merchant, но не тестовый режим модуля

  • 0x20 - 100000 - в запросе неверно указан номер (id) платежа

  • 0x40 - 1000000 - в запросе неверно указан cid договора

  • 0x80 - 10000000 - в запросе неверно указана сумма платежа

  • 0x0100 - 100000000 - платёж уже помечен как оплаченный

  • 0x0200 - 1000000000 - платёж с таким инвойсом уже есть в базе

  • 0x0400 - 10000000000 - платёж с таким номером транзакции уже есть в базе

  • 0x0800 - 100000000000 - модуль в режиме выключен

  • 0x1000 - 1000000000000 - в конфиге указан id не существующего типа платежа

Глава 40. Модуль Yandex.Деньги

1. Назначение модуля

Модуль Yandex.Деньги предназначен для проведения платежей через систему Yandex.Деньги. Для работы должен быть заведён аккаунт для магазина в системе Yandex.Деньги.

2. Настройка модуля

Установите модуль на сервер, обновите клиент, создайте экземпляр модуля. Создайте в редакторе конфигурации модуля новую конфигурацию, сделайте её активной. Конфигурация в общем виде такая:

# URL платёжной формы. (Будет предоставлен в ЦПП)
yamoney.url=https://demomoney.yandex.ru/eshop.xml
# Номер магазина в ЦПП. Выдается ЦПП.
yamoney.shopId=58
# Номер товара в ЦПП. Выдается ЦПП.
# yamoney.shopArticleId=58
# банк.
# yamoney.BankId=
# Номер витрины магазина в ЦПП. Выдается ЦПП.
yamoney.scid=58
#
# Метод аутентификации, применяемый в запросах от ЦПП. На данный момент поддерживаются:
# pgp - подпись PGP
# md5 – криптографический хэш (в комбинации с секретным паролем Магазина)
# (должен быть прописан такой же, как в настройках магазина)
yamoney.authMethod=md5
# Секретный пароль магазина (20 случайных символов), используемый при расчете криптографического хэша.
# Должен быть указан, если выбран тип аутентификации криптографическим хэшем.
# (должен быть прописан в настройках магазина)
yamoney.shopPassword=01234567890123456789
# Публичная часть PGP-ключа Магазина. (полный путь к локальному файлу)
# Должен быть указан, если выбран тип аутентификации PGP-подписью.
# Если указан, то ЦПП будет шифровать на этот ключ реестры.
# Рекомендуемые параметры ключа для подписи:
# *)Алгоритм симметричного шифрования CAST5, либо 3DES, либо IDEA;
# *)Хеш-функция SHA1;
# *)Алгоритм сжатия ZLIB, BZIP2, ZIP;
# *)Асимметричные ключи шифрования могут быть: RSA (1024 - 2048 bit), Diffie-Hellman/DSS (1024 - 4096 bit);
# (должен быть прописан в настройках магазина)
#yamoney.shopPgpKey=
# идентификатор платежа, которым будут вноситься приходы
paymenttype=16
# Шаблон комментария платежа
# ${contract} - заголовок договора
# ${contract_comment} - комментарий договора договора
# ${orderSumAmount} - сумма заказа
# ${orderSumCurrencyPaycash} - код валюты для суммы заказа (тип currencyCode)
# ${shopSumAmount} - сумма, получаемая Магазином на р/с
# ${shopSumCurrencyPaycash} - код валюты для суммы, получаемой Магазином на р/с
# ${date} - момент времени регистрации оплаты заказа в ЦПП
# ${invoiceId} - номер транзакции
# ${paymentPayerCode} - номер Кошелька «Яндекс.Денег» Покупателя
paymentCommentPattern=Платёж с Yandex.Деньги кошелька ${paymentPayerCode}, транзакция ${invoiceId}

Настройте магазин (на акаунте Yandex.Денег).

1) successURL и failURL указать на страницу списка платежей, но без параметра action:

http://ваш_адрес/webexecuter?mid=<mid>&module=yamoney

дело в том, что платёжная система сама по себе добавляет GET-параметр action, который мы здесь обработаем стандартным образом и сделаем редирект на список платежей в личном кабинете пользователя.

2) checkURL и paymentAvisoURL указать для старой версии протокола (меньше 3) http://ваш_адрес/yaexecuter?mid=<mid> и для новой версии протокола (версия 3): http://ваш_адрес/yaexecuter3?mid=<mid> . Для новой версии протокола везде указывать UTF-8 в настройках магазина. Поддерживается метод секретное слово + md5. (NVP/MD5)

Yandex.Деньги настаивают на https-варианте настройки сервлета yaexecuter. Безотносительно выбранному способу авторизации, ИС рекомендуется осуществлять контроль IP-адресов, с которых она получает запросы ЦПП (список IP можно получить при подключении).

3) Также введите имя, пароль и прочие параметры, которые должны быть выданы для аккаунта.

В версии протокола 3 поддерживаются динамическое задание адресов возврата shopSuccessURL и shopFailURL (если в настройках магазина включены динамические адреса возврата, то обязательно) указание в конфигурации модуля:

yamoney.shopSuccessURL=http://ваш_адрес/webexecuter?...
yamoney.shopFailURL=http://ваш_адрес/webexecuter?...

Переключение из тестового в рабочий режим проводится через менеджеров системы Yandex.Деньги после проверки корректности работы.

Для тестирования платежей вы можете использовать программу Интернет.Кошелек или Web-версию Яндекс.Кошелек. Подробно о том, как проводить тестирование в демо-режиме (с точки зрения разработчика), можно почитать здесь: http://money.yandex.ru/doc.xml?id=459801#2 .

Скачать Интернет.Кошелек: http://money.yandex.ru/doc.xml?id=522773

Открыть демо-версию Яндекс.Кошелька: http://demomoney.yandex.ru/

Обращаем ваше внимание, что счет демо кошелька должен начинаться на 41003.

Пополнить счет демо-валютой: http://demomoney.yandex.ru/shop.xml?scid=666

Ценовую политику и проценты решает для себя организация с учётом процентов Яндекса и т.п.. Дополнительная настройка модуля может быть такой:

# Параметр paymentSumAmount показывает какую именно сумму заносить на счёт юзеру
# order - заносится "сумма заказа, общая сумма" (значение параметра orderSumAmount)
# shop - заносится "сумма на счёт магазина", то есть сумма заказанная клиентом за вычетом процентов (значение параметра shopSumAmount)
paymentSumAmount=order
# Процент комиссии, будет нарисован в Web в случае, когда зачисление будет не полной
# суммы, а за вычетом процента (paymentSumAmount=shop)
paymentSumPercent=5

3. Оплата через Yandex.Деньги

Если у абонента подключён экземпляр модуля, то он может произвести оплату услуг через Web-интерфейс (пункт меню Оплата через Yandex.Деньги). Здесь же клиент может просмотреть все проведённые им платежи:

При вводе суммы внизу страницы и нажатии кнопки Пополнить счёт клиент попадает на страницу системы Yandex.Деньги, где может выбрать удобный для себя способ оплаты.

4. Слежение за платежами

В параметрах договора можно посмотреть все платежи и их параметры.

В параметрах модуля есть глобальный монитор платежей.

Глава 41. Плагин CashCheck

1. Назначение и структура плагина, архитектура системы

Плагин CashCheck позволяет при внесении платежей в биллинг печатать кассовые чеки на подключённом оборудовании: контрольно-кассовой машине (ККМ, Регистратор) или принтере. Также возможна печать приходных кассовых ордеров на обычном принтере. Архитектура плагина подразумевает любые подобные действия, связанные с операцией прихода денежных средств. Далее любое оборудование называется принтер.

Список поддерживаемых на данный момент принтеров находится в разделе "настройка сервера печати".

Плагин (а именно его серверная часть) работает в связке с сервером печати - отдельным приложением, запущенном на некотором удалённом или локальном компьютере и доступном для сервера биллинга по сетевому протоколу TCP. Сервер печати служит для сетевого доступа к принтеру. Сервер печати придуман для того, чтобы несколько принтеров могли быть установлены в любых местах с возможностью любого клиента биллинга (то есть, в конечном итоге, сервера биллинга) печатать на любой из них.

Замечание

Один сервер печати даёт возможность сделать привязку только одного конкретного принтера к одному сетевому порту. Для двух подключённых к одной рабочей машине устройств (одинаковых или разных) требуется запустить два сервера печати на разных портах. (см. раздел запуск двух копий сервера)

Итак, помимо установленных плагинов на сервер биллинга и на необходимые клиенты биллинга, устанавливается несколько серверов печати - по числу работающих принтеров. Серверы печати устанавливаются и запускаются на тех компьютерах, к которым физически подключено оборудование. Ниже представлена схема работы системы и принцип взаимодействия клиентов биллинга, сервера биллинга и принтеров.

Замечание

Несмотря на то, что сервер печати нумеруется версиями, сходными с версиями биллинга, эта нумерация условная и носит больше номенклатурный характер. Соответствие версии сервера печати и версии самого биллинга в общем случае необязательно (в отличие от версии самого плагина CashCheck). Но злоупотреблять этим не стоит.

Внимание

Необходимо предупредить, что очень часты проблемы при использовании схем подключения, отличных от прямого подключения к com-порту. Например, при использовании переходников com-usb, устройств типа nport и прочего, особенно ненадлежащего качества. Если вы используете такие устройства, убедитесь, что они корректно работают в вашей системе, для них правильно установлены и настроены свежие драйверы. При проблемах обмена с принтерами ("ошибка связи", "не отвечает на ENQ", "некорректно ответил в течение 5 попыток" и т. д.) сначала переустановите драйверы этих устройств, а также попробуйте заменить сами устройства. Дешёвые переходники гарантированно будут давать проблемы. Итак, дешёвые китайские — плохие, качественные (в т.ч. на базе ИМС CP2102 и подобных) — хорошие.

2. CashCheck-сервер (сервер печати)

Сервер печати распространяется в виде отдельного пакета BGCashCheckServer, его структура во многом схожа с другими серверами BGBilling. Установка, настройка и запуск осуществляется аналогично. Подготовительные действия смотрите в разделах установка сервера под Linux и установка сервера под Windows, здесь же будут приведены уточнения.

Необходимы переменные окружения JAVA_HOME (полный путь до корня используемой JRE) и BGCASHCHECK_SERVER_DIR (полный путь до корня установленного bgcashcheckserver).

Внимание

Под Windows это должны быть обязательно системные (а не пользовательские) переменные окружения. Обратите внимание, т.к. это очень распространённая ошибка.

Замечание

Для запуска сервера как службы эти условия обязательны. Для проверки просто запуска через bat/sh можно указать вручную переменные в файлах запуска server.bat/sh, testserver.bat/sh и т.д. (см. в начале скриптов установку этих переменных, раскомментировать их установку и скорректировать на нужные пути).

Установка службы под Windows аналогична установке других серверов, запуск производится через JSL, установка службы - server_install.bat.

Установка демона под Linux тоже стандартна (приведён пример, для настройки под ваш дистрибутив обратитесь к документации по системе):

  • Копируем скрипт(ы) из linux_service в /etc/rc.d/init.d

  • Устанавливаем права

    chmod 755 /etc/rc.d/init.d/bgcashcheckserver
  • Добавляем службу

    chkconfig --add bgcashcheckserver
  • Включаем службу, например, для уровней 2,3,4 и 5

    chkconfig --level 2345 bgcashcheckserver on

Внимание

Касается установки под Linux. Обратите внимание на то, что пользователю, от которого запускается приложение, должны быть доступны порты (устройства /dev/ttyS*). Проверьте их группу и владельца, а также права доступа. При необходимости добавьте пользователя в нужную группу (может быть uucp, dialout или другая в вашей системе).Иначе порт будет недоступен, а в testserver выведется пустой список портов. Если сервер стартует как демон, то это, в общем случае, не актуально (стартует от суперпользователя), но утилиты (testserver и пр.) всё равно не будут корректно работать.

2.1. Установка rxtx-библиотеки.

Прежде чем производить запуск сервера печати, необходимо убедиться, что установлена rxtx-библиотека. Она представляет собой native java-библиотеку и должна быть установлена как jvm-библиотека. Работающая сборка библиотеки находится в каталоге jre-lib дистрибутива сервера печати.

Замечание

Несмотря на то, что библиотека rxtx предназначена для осуществления связи по com-порту, корректно установленная библиотека нужна и в том случае, если вы не используете сервер печати с оборудованием, работающем по последовательном порту, потому что в данный момент драйверы зашиты в основную библиотеку сервера печати. При неустановленной библиотеке приложение не запустится.

Расширение представляет собой два файла:

  • файл jre-lib/RXTXcomm.jar, для всех платформ одинаковый;

  • файл jre-lib/<platform>/<бинарная библиотека>, платформозависимый, берём из соответствующей поддиректории.

Файлы в системе должны лежать в следующих местах:

  • Windows

    RXTXcomm.jar -> \jre\lib\ext (в директории java)

    rxtxSerial.dll -> \jre\bin

  • Linux (только x86, x86_64, ia64 here but more in the ToyBox)

    RXTXcomm.jar -> /jre/lib/ext (в директории java)

    librxtxSerial.so -> /jre/lib/[machinetype] (Например, i386)

    Убедитесь в том, что пользователь находится в группах lock и uucp.

  • Mac OS X (x86 и ppc) (есть установки с источником)

    RXTXcomm.jar -> /Library/Java/Extensions

    librxtxSerial.jnilib -> /Library/Java/Extensions

    Запуск fixperm.sh, который находится в директории (разрешения Mac_OS_X подкаталога)

  • Solaris (sparc)

    RXTXcomm.jar -> /jre/lib/ext (в директории java)

    librxtxSerial.so -> /jre/lib/[machinetype]

    Убедитесь в том, что пользователь находится в группе uucp.

2.2. Настройка сервера печати и оборудования, поддерживаемые устройства.

Конфигурация сервера печати находится в файле setupfrk.config. Конфигурация содержит комментарии и все варианты своих параметров, так что настройка не должна вызвать затруднения.

Два параметра - driver и port - управляют связкой "устройство - сетевой порт", остальные параметры конфигурации специфичны для каждого поддерживаемого драйвера (см. параметры в описании каждого драйвера).

Параметр port, как понятно, определяет порт, на котором сервер печати слушает подключения сервера биллинга.

Параметр driver указывает на класс драйвера устройства. В данный момент поддерживаются следующие устройства (в каждом подразделе даётся строка для указания в качестве имени драйвера) со следующими параметрами (см. ниже).

На данный момент это всё оборудование, которое поддерживается сервером печати. Работоспособность других устройств не гарантируется (более того - маловероятна). Но реализация этой поддержки, конечно, возможна.

В конфигурации сервера печати прописаны некие параметры "по умолчанию" для каждого устройства на момент написания драйвера. Вполне возможно, что у вас настройки будут иные. Внимательно проверяйте все параметры! Например, несовпадение параметров COM-порта в устройстве, настройках драйвера и в самой системе чаще всего приведёт к невозможности работы с этим устройством.

2.2.1. Фискальный регистратор Штрих-ФР-К для использования его в BGBilling

driver: ru.bitel.frk.driver.shtrih.Driver

Конфигурация:

portName - имя порта, например, в Windows com<X>, в Linux /dev/ttyS<X>;
baudRate - скорость обмена (2400, 4800, 9600, 19200, 38400, 57600, 115200);
flowControlIn, flowControlOut - описание типа flow control (None, Xon/Xoff Out, Xon/Xoff In, RTS/CTS In, RTS/CTS Out);
databits - настройка data bits (5, 6, 7, 8);
stopbits - настройка stop bits (1, 1.5, 2);
parity - настройка parity (None, Even, Odd);
oneByteTimeout - таймаут приёма одного байта, характеристика порта (по умолчанию 100).

Драйвером поддерживаются следующие устройства:

ШТРИХ-ФР-Ф (версия 03), ШТРИХ-ФР-Ф (версия 04), ШТРИХ-ФР-Ф (Казахстан), ЭЛВЕС-МИНИ-ФР-Ф, ФЕЛИКС-Р Ф, ШТРИХ-ФР-К, ШТРИХ-950К, ЭЛВЕС-ФР-К, ШТРИХ-МИНИ-ФР-К, ШТРИХ-ФР-Ф (Белоруссия), ШТРИХ-КОМБО-ФР-К, Фискальный блок Штрих-POS-Ф, ШТРИХ-950К (версия 02), ШТРИХ-КОМБО-ФР-К (версия 02), ШТРИХ-МИНИ-ФР-К (версия 02, 57 мм), ШТРИХ-КИОСК-ФР-К

Замечание

Из указанного списка проверены не все устройства, но согласно описанию протокола должны работать все из этого списка. Подробная сверка моделей и наличия в них используемых команд не проводилась (за исключением обычных, распространённых моделей - ФР-К и т.д.), поэтому, возможно, что среди указанных моделей есть специфические устройства, которые будут работать с ограниченным функционалом.

Ограниченно поддерживаются следующие (обычные, без ФП) принтеры:

Принтер ШТРИХ-500

Замечание

Полноценной заявки поддержки нет ввиду нереализованных в них команд типа "продажа" и подобных. Но можно подключить и запустить это устройство, но в скрипте обработки формирования чека (см. ниже) формировать нужные строки, без команды добавления платежа, только командами добавления строк, аналогично тому, как это описано для FOP-драйвера сервера печати. Таким образом, несложно вручную сформировать любой вид чека, аналогично обычным ККМ. Но, конечно, чека в данном случае нефискального.

Реализована вторая версия драйвера ККМ Штрих. Задумывалась как обновлённая реализация протокола "Штрих", более полная поддержка железа и устойчивость к ошибкам, особенно в проблемных вариантах (через маппинг портов, при нестойких соединениях через разные переходники usb и т.д.). Написано не по рекомендациям протокола, а по опытным наблюдениям. В данный момент тестируется, рекомендуется к использованию как альтернатива.

driver: ru.bitel.frk.driver.shtrih2.Driver

Параметры и настройки те же.

Для обеих версий драйвера имеются дополнительные параметры драйвера (использовать по ситуации):

# таймаут в мс между опросами состояний для ожидания окончания печати предыдущей операции
waitNoprintTimeout: 1000
    
# кол-во опросов состояния для ожидания окончания печати предыдущей операции (каждое длиной таймаут)
waitNoprintNumtry: 20

# запрет прямого использования команды отрезки (позволяет избежать проблем с отрезчиком в некоторых случаях)
# по умолчанию - 0 (отрезчик используется)
cutterDisabled: 1

# насильное использование резчика после каждой операции печати (если вдруг авторезка не работает)
# по умолчанию - 0 (отрезчик руками не включается, срабатывает только если авторезка)
#cutterForceManual: 0

Замечание

Здесь и далее - флаг cutterDisabled действует только на ручную команду отрезки при печати произвольного текста или при приветствии итд итп. А отрезка или неотрезка при чеках/отчётах настраивается в принтере. После печати чека должно резать автоматически, это заложено в программе регистратора и настраивается в нём самом.

2.2.2. Эмулятор принтера, подразумевающегося к использованию в BGBilling

driver: ru.bitel.frk.driver.emu.Driver

Представляет собой некую заглушку. Если нет реального устройства или оно не поддерживается/не работает, можно запустить и протестировать с этим драйвером-эмулятором. При этом некоторый вывод драйвера (вместо вывода на реальную бумагу) выкидывается в консоль (и, следовательно, попадает в cashserver.out). Дополнительной конфигурации этот драйвер не требует.

К этому драйверу прилагается визуальный "эмулятор принтера", очень грубым образом отображающий возможный вид "напечатанных" чеков. Этот эмулятор интерпретирует консольный вывод драйвера-заглушки и рендерит чеки, отдалённо напоминающие чеки регистраторов Штрих. Может применяться для оценки работы сервера печати и системы в целом.

Приложение виртаульного принтера запускается из папки сервера печати: virtualprinter.sh(.bat). Параметры можно увидеть при запуске.

Использование: <virtualprinter>[.bat|.sh] [--noskipexist] [--encoding=<encoding>] <logfilename>

где --noskipexist - не пропускать уже существующие на момент запуска виртуального принтера строки в выводе драйвера-эмулятора;

--encoding=<encoding> - указание кодировки исходного файла (вывода эмулятора);

logfilename - путь к файлу 'cashserver.out'. Например:

./virtualprinter.sh ./log/cashserver.out

2.2.3. Любой системный принтер для печати на нём XSL-FO шаблонов.

driver: ru.bitel.frk.driver.fop.Driver

Представляет собой FO-транслятор, который действует так:

  1. формирует из приходящих данных (текстовые строки) xml;

  2. обрабатывает с помошью этой xml указанный заранее xsl:fo шаблон;

  3. выводит его на печать на указанном принтере.

Необходимая конфигурация сервера печати:

# Название принтера в системе (если не указан, то возьмётся принтер по умолчанию, прописнный в системе, если и такого нет, будет ошибка)
printer=pdf

# Шаблон xsl. Прямой путь к файлу (можно, конечно, положить его в xsl сервера
# биллинга, тогда сервер печати, конечно, не стартует без старта последнего)
#xsl=http://127.0.0.1:8080/bgbilling/xsl/cashcheck_fop.xsl
#xsl=file:///home/dimon/workspace/bgbilling/modules/cashcheck/server/server_files/xsl/cashcheck_fop.xsl
xsl=file:///usr/local/BGCashcheckServer/xsl/cashcheck_fop.xsl

# Имя задания печати (произвольное), может быть "не задано"
jobName=fop driver printing

# Количество копий, может быть "не задано"
jobCopies=1

К этому драйверу нужны две сущности: скрипт поведения, который формирует нужные строки для драйвера, и xsl-шаблон, который преобразуется с помощью xml, сформированной драйвером, в готовый документ для печати. Пример скрипта поведения см. ниже, в разделе "настройка внешнего вида чеков". Смысл скрипта состоит в заполнении набора строк с помощью конструкций вида

check.addString( "строка" );

порядок строк важен для шаблона, там они выбираются по номерам. Список строк драйвер преобразует в xml такого вида:

<?xml version="1.0" encoding="UTF-8"?>
<data clientsumma="10.0" summa="10.0">
    <line n="1" text="120,00р."/>
    <line n="2" text="строка2"/>
    <line n="3" text="строка3" summ="10.0" dep="15"/>
</data>

Такую xml и надо иметь ввиду при создании и редактировании xsl-шаблона. Последняя, третья, строка получена с помощью метода addPayment в скрипте обработки, а не addString. Сам шаблон представляет собой любой валидный FO-документ. Получить в этом шаблоне значения строковых параметров из драйвера можно таким кодом (см. исходную xml выше):

<!-- Сумма платежа: 120,00р. -->
<xsl:variable name="param_summ" select="line[@n='1']/@text" />

Таким образом, в xsl-переменной окажется значение аттрибута "text" из первой строки ("n"=1).

Замечание

При правке или замене XSL-FO шаблона при необходимости видеть результат внесённых изменений необходимо перезагрузить CashCheck-сервер, т.к. шаблон загружается и распознаётся при инициализации драйвера во время старта сервера. Для оптимизации по скорости.

2.2.4. Устройства с протоколом от компании АТОЛ

driver: ru.bitel.frk.driver.atol.Driver

Драйвер реализует поддержку протоколов, основанных на разработках компании АТОЛ. В данный момент это следующие устройства:

Триум-Ф эталонной версии 01, «Меркурий-140Ф» АТОЛ, ФЕЛИКС-Р Ф эталонная версия 02, ФЕЛИКС-02К эталонная версия 01, ТОРНАДО (МЕРКУРИЙ-114.1Ф эталонная версия 04), Меркурий MS-K эталонная версия 02, ФЕЛИКС-Р К эталонной версии 01, ФЕЛИКС-3СК эталонная версия 01, FPrint-01K эталонная версия 01, FPrint-02K эталонная версия 02, FPrint-03K эталонная версия 01, ККМ BIXOLON-01K, PayPPU-700K, PayVKP-80K, PayCTS-2000K, FPrint-88K, FPrint-5200K

Параметры для этого драйвера такие:

portName - имя порта, например, в Windows COM<X>, в Linux /dev/ttyS<X>;

baudRate - скорость порта. По протоколу заявлены следующие возможные значения: 1200, 2400, 4800, 9600, 14400, 38400, 57600, 115200.

Остальные параметры порта по умолчанию заявлены в протоколе следующими: 1 стартовый бит, 8 битов данных, 1 стоповый бит, без проверки на четность, 3 линии (TXD, RXD, GND);

type - так как драйвер поддерживает несколько принтеров, разновидностей и их платформ, то необходимо указать тип принтера заранее. В конфигурации приведены все возможные значения;

accessPassword - пароль доступа к ККМ (не пароль кассира/админа/сисадмина!). 4цифры, по умолчанию "0000", согласно протоколу.

Имеются дополнтельные параметры драйвера (использовать по ситуации):

# запрет прямого использования команды отрезки (позволяет избежать проблем с отрезчиком в некоторых случаях)
# по умолчанию - 0 (отрезчик используется)
cutterDisabled: 1

# насильное использование резчика после каждой операции печати (если вдруг авторезка не работает)
# по умолчанию - 0 (отрезчик руками не включается, срабатывает только, если авторезка)
#cutterForceManual: 0

2.3. Запуск сервера печати

Подготовка службы (для Windows-системы) и запуск сервера печати аналогична подобной процедуре при запуске сервера биллинга. Скрипты с аналогичными названиями присутствуют.

Внимание

Некоторыми пользователями утверждается, что бывают проблемы при маппинге последовательных портов на тонких клиентах в определённых средах. См. предостережение в главе 1.

2.4. Запуск двух копий сервера

Запуск двух копий сервера может понадобиться, например, при подключеннии двух разных или одинаковых устройств к одному компьютеру. Часто такое бывает при запуске клиентов кассиров через терминальную архитектуру или в каких-то других случаях.

Чтобы запустить два сервера на одной машине, вам придётся сделать две копии папки программы и две разных переменных окружения, например, %BGCASHCHECK_SERVER_DIR_1% и %BGCASHCHECK_SERVER_DIR_2%. Соответственно, все используемые файлы запуска (bat,sh,server.ini) тоже надо соответствующим образом подправить на эти разные переменные. Не забудьте указать разные порты в конфигурации серверов.

В итоге, файлы запуска будут выглядеть примерно так (для Windows):

set CLASSPATH=%BGCASHCHECK_SERVER_DIR_1%;%BGCASHCHECK_SERVER_DIR_1%\lib\*
java -cp %CLASSPATH% ru.bitel.frk.server.CmdTcpServer %1 %2 %3 > %BGCASHCHECK_SERVER_DIR_1%\log\cashserver.out 2>&1

Для запуска двух серверов, как Windows- служб надо соответсвенно поправить файлы server_install.bat, server_uninstall.bat, server.ini. Необходимо заменить в них переменные окружения %BGCASHCHECK_SERVER_DIR% на разные, а также изменить названия службы (параметры appname, servicename, displayname в конфиге server.ini). Не забывайте про корректное указание двух соответствующих переменных окружения, которые должны прописываться как системные переменные окружения (см. установка и запуск BGBilling-сервера).

2.5. Тестирование

В сборке сервера имеется скрипт testserver.bat(.sh) для запуска программы самотестирования принтера и сервера печати. Производится проверка:

  1. физического доступа к serial-портам;

  2. прямого доступа к железной части устройства принтера;

  3. сетевого доступа к принтеру, эмулируется работа клиента (в данном случае - сервера биллинга);

  4. доступа к серверу для получения статуса;

  5. всех драйверов, которые физически нашлись в сборке сервера, для каждого проводится процедура самотестирования (процедура driver touch).

Результаты работы скрипта выводятся в stdout и stderr, при необходимости можно самостоятельно перенаправить вывод в лог файл (например, ./log/testserver.out) для анализа. Пример строки запуска можно увидеть ниже. Нормально отработал или нет - видно по отсутствию ошибок в логе и надписи TEST COMPLETED в конце вывода скрипта. Эта строка не означает, что всё закончилось успешно, а просто что всё закончилось! Также там могут быть, например, следующие ("технические") ошибки:

  • java.lang.NoClassDefFoundError: gnu/io/PortInUseException

    Причина: RXTXcomm.jar не видится в путях той java, от которой запускается приложение. Внимательно проверьте JAVA_HOME (если вы ей пользуетесь) и/или пути к java в .bat/.sh-скриптах. Например, у вас может стоять две Java-машины, либо JDK, которая содержит внутри себя вложенную JRE. Обратите внимание: это очень распространённые ошибки.

  • Exception in thread "main" java.lang.UnsatisfiedLinkError: no rxtxSerial in java.library.path

    Причина: отсутствует соответствующая (операционной системе, её версии, разрядности и т.д.) бинарная библиотека rxtxSerial. См. комментарии к предыдущей ошибке.

Если сервер запустился и скрипт testserver выдаёт приличные результаты, то серверная сторона печати чеков готова принимать команды и работать с принтером.

Программа testserver также использует log4j, настройки находятся в том же конфиге, но под меткой "testserver".

В программу testserver опционально передаётся пароль для кассира/администратора. То есть тот, что передаётся в драйвер, при логине кассира. Пароли доступа, если они нужны - будут браться из конфига.

При запуске приложения необходимо указать некоторые параметры, при этом делается либо тест, либо touch, либо всё вместе. Параметры запуска:

testserver[.bat|.sh] [--dotest] [--dotouch] [--passwordXXX] [--driversDRIVER1,DRIVER2,...]

где --dotest делать тесты;

--dotouch делать тач драйверов;

--password(пароль) задать пароль оператора для некоторых тестов (без пробелов и скобок), иначе не задан (равен нулю);

--drivers(драйвер1),(драйвер2)... задать драйвер(ы) для теста (без пробелов и скобок), иначе выбраны все.

Также, как сказано выше, при необходимости надо перенаправить вывод в лог, к примеру, так:

./testserver.sh --dotest --dotouch > test.log 2>&1

Так, к примеру, выглядит тест драйвера штриха с созданием файла testserver.log для анализа (под Linux и Windows соответственно):

./testserver.sh --dotouch --driversru.bitel.frk.driver.shtrih.Driver,ru.bitel.frk.driver.shtrih2.Driver > testserver.log 2>&1
./testserver.bat --dotouch "--driversru.bitel.frk.driver.shtrih.Driver,ru.bitel.frk.driver.shtrih2.Driver" > testserver.log 2>&1

2.6. Анализ ошибок и логгирование

Сервер печати CashCheck логгирует большинство своих действий. Для вывода используется библиотека log4j. Также в некоторых местах используется прямой вывод в консоль. В основном это специальный консольный вывод и незалоггированные ошибки сервера. По умолчанию основной лог пишется в файл ./log/cashserver.log, а консольный вывод - в ./log/cashserver.out.

В разных режимах работы логгера log4j может выводиться разная информация. Примерное распределение информации по уровням логгирования:

  • error: ошибки сервера, потоков команд, работы драйверов;

  • warn: ошибки протокола (неверные пропущенные заголовки итд), ошибки, возвращенные драйвером и переданные вызывающему;

  • info: старт, стоп, получение команд;

  • debug: получение сервером запросов, старт/стоп каждого потока команд;

  • trace: содержимое команд и ответов на них, низкоуровневый вывод драйверов и устройств.

Полный вывод может понадобиться для отладки конкретного устройства. Например, когда возникает ошибка соединения, с помощью подробной трассировки можно понять на каком этапе была авария. Часто подобная информация нужна разработчикам при дописывании программы для поддержки какого-либо устройства. Чтобы сменить режим, поменяйте значение параметра в конфигурации log4j-cashcheck.xml:

priority value="DEBUG"

Для более полного понимания логики работы логгера читайте документацию по log4j.

3. Настройка плагина

3.1. Настройка плагина в биллинге

После стандартной установки и подключения плагина требуется настроить печать уже в самом биллинге. Это делается в конфигурации плагинов для соответствующего плагина. Конфигурация состоит из нескольких частей:

  • настройки регистраторов — указывается адрес и порт сервера печати и заголовок для отображения наименования в биллинге;

  • настройки привязки типов платежей к регистраторам отделам — указывается на каких регистраторах разрешена печать;

  • некоторые флаги.

Пример конфигурации (отражён весь набор параметров/флагов):

# настройки регистраторов
# fr.<номер принтера>.connector=<адрес сервера печати>:<порт сервера печати>
# fr.<номер принтера>.title=<смысловое название принтера>

fr.1.connector=127.0.0.1:9876
fr.1.title=первый регистратор (локальный)

fr.2.connector=192.168.0.1:9876
fr.2.title=второй регистратор

# маппинг типов платежей на регистраторы
# pt.<id типа платежа>.fr=<список регистраторов, на которых разрешена печать платежа>

pt.1.fr=1
pt.25.fr=2
pt.37.fr=1,2

# отключение "привета" при логине на ККМ (по умолчанию false), имеет смысл при fop-драйвере, например
disable.login.hello=0

Отдел не привязывается к типам платежей в конфигурации плагина - это делается в скрипте поведения для события "формирование вида чека". Отдел тут подразумевается в контексте отдела продаж в понятиях фискального регистратора, по ним можно будет дополнительно делать отчёт на регистраторе. Подробнее о том, как использовать эту возможность см. ниже.

Тип платежа идентифицируется по его ID - числовому номеру, который можно узнать в справочнике платежей. Не привязанные никуда платежи вообще нельзя будет напечатать на принтере, также они не будут попадать в очередь готовых/возможных для печати платежей.

Если при попытке печати чека у вас выдаётся сообщение "Платеж(и) не содержатся в очереди, печать невозможна...", то это указывает на проблему с настройкой маппинга. Такая ошибка возникает, а) когда платежа, который пытается быть превращён в чек, нет в настройках; б) когда этот платёж уже есть в таблице лога распечатанных платежей. Платёж либо можно сразу распечатать, либо он окажется в "очереди печати". Туда попадают ВСЕ платежи, тип которых назначен на текущий регистратор. После распечатки платежи регистрируются в логе распечатанных платежей.

3.2. Настройка внешнего вида чеков (скрипты, устаревший метод)

Имеется возможность настраивать внешний вид печатаемых чеков. Это делается с помощью скриптов поведения. Возможности и способы работы с ними читайте в соответствующих разделах документации.

Скрипты служат для настройки внешнего вида чеков.

  • Позиция - это несколько строк, представляющие одну позицию в чеке, добавляются в объект check с помощью addPayment/addString;

  • один раз должна присутствовать установка платежа addPayment( ) - это будет "фискальная" строка, которая, собственно, представляет собой продажу; в этой строке может быть ещё одна строка, типа наименование продажи и отдел. Теоретически может не быть фискальной строки, но тогда в печать не выведется платёж, но, внимание!, по всем остальным признакам платёж пометится напечатанным. Замечание касается работы с фискальным оборудованием. При печати на произвольном принтере (термопринтере или обычном) возможно формирование с помощью скриптов любых данных для вывода;

  • в остальных строках - по одному параметру String, которая выведется;

  • или: прямой текст указан, так и выведется;

  • или: просто ничего (пробел), это будет пустая строка, типа вертикальная табуляция (например, для красоты при отделении блоков текста друг от друга и т.д.).

Скрипты и примеры кода:

  • [Чек: добавление позиции], по умолчанию будет только платёж и строка с предупреждением об отсутствии скрипта:

    check = event.getCheck();
    payment = event.getPayment();
    
    // 1) строка сумма-контракт, плюс отдел (если надо, то вычисляется в этом же скрипте)
    check.addPayment( payment.getSumma(), payment.getContractTitle(), paymentDep );
    // 2) строка с комментарием
    check.addString( payment.getContractComment() );
    // 3) пустая строка
    check.addString( " " );
  • [Чек: завершение формирования], по умолчанию - ничего к низу чека не прибавляется:

    check = event.getCheck();
    
    check.addString( "footer 1" );
    check.addString( "footer 2" );
    check.addString( "footer 3" );

Замечание

Как известно, скрипты поведения привязаны к договорам. Если скрипт не привязан договору, то на чеке будет печататься предупреждение. Обратите на это внимание, если вдруг вы меняете формат чека в скрипте, а он при печати остаётся старым или с предупреждением. Итак, для печатаемого чека обязательно должен сработать скрипт формирования его вида!

Замечание

Обратите особое внимание, что в каждом скрипте формирования внешнего вида чека (а именно происходит формирование каждой отдельной позиции чека) обязательно должна присутствовать ровно одна команда addPayment для всех устройств, являющихся ККМ. Дополнительно может быть любое количество addString. Для устройств, представляющих обычный принтер, для FOP-устройств (см. ниже) и т.п. команда addPayment не нужна, так как там не происходит добавление продажи во внутреннюю память.

Далее приведём пример скрипта "добавление позиции" для формирования FO-документа, для FOP-драйвера. Эти строки соответствуют шаблону cashcheck_pko.xsl, находящемуся в стандартной поставке сервера печати.

import bitel.billing.common.*;
import bitel.billing.server.admin.bean.*;

check = event.getCheck();
payment = event.getPayment();

//Сумма платежа: "120,00р."
check.addString( String.valueOf(payment.getSumma()) + "р." );

//Номер договора
check.addString( payment.getContractTitle() );

//Фамилия клиента: "ИВАНОВ И.И."
check.addString( payment.getContractComment() );

//Дата платежа: 20-04-2009
check.addString( TimeUtils.format( payment.getDate(), "dd-MM-yyyy" ) );

//Организация: ООО "ПРОВАЙДЕР"
check.addString( "ООО \"ПРОВАЙДЕР\"" );

//ФИО кассира (пользователя биллинга)
UserManager um = new UserManager( con );   
User user = um.getUserByID( payment.getUserID() );
check.addString( user.getName() );

//Тип платежа: "СПД  №"
check.addString( "СПД  №" );

//Сумма прописью: "Сто двадцать рублей 00 коп"
check.addString( SummaToString.summaToString( String.valueOf(payment.getSumma()), true ) );

В данном случае мы формируем 8 строк с произвольной информацией, которая передаётся в FOP-драйвер сервера печати, который напрямую передаёт их в FO-шаблон обычной линейной xml. Это позволяет формировать документ из любых строк, подготовленных в скрипте, и из любого написанного шаблона.

Также в событиях устанавливается поле "printer" - объект "принтер", на который производится печать. Это может понадобиться, например, при наличии двух разных принтеров и желания печатать на них разного вида информацию и на разные принтеры использовать разные скрипты (например, для FOP и ККМ скрипты всегда разные будут). Например, можно получить ID принтера (такой, какой он в конфигурации плагина):

int printerId = event.getPrinter().getId();

3.3. Настройка внешнего вида чеков (динамический код)

Для формирование вида чеков используется динамический код. Чтобы использовать динамический код для формирования вида чека, в конфигурацию плагина прописывается следующий (или любой другой подходящий) класс:

# динамический класс для формирования вида чека
checkbuilder=ru.bitel.bgbilling.cashcheck.SimpleCheck

Пример класса идёт в комплекте с плагином. Подразумевается, что класс обязательно должен быть и должен сработать. О работе с динамическим кодом можно прочитать в соответствующем разделе справки. Внутри можно проверить любые условия и сформировать чек любой формы для каждой позиции/платежа, добавляемой в чек.

Методы динамического класса служат для настройки внешнего вида чеков.

  • Позиция - это несколько строк, представляющие одну позицию в чеке, добавляются в объект check с помощью addPayment/addString

  • один раз должна присутствовать установка платежа addPayment( ), это будет "фискальная" строка, которая собственно представляет собой продажу, в этой строке может быть ещё одна строка, типа наименование продажи и отдел. Теоретически может не быть фискальной строки, в печать не выведется тогда платёж, но внимание - по всем остальным признакам платёж пометится напечатанным. Замечание касается работы с фискальным оборудованием. При печати на произвольном принтере (термопринтере или обычном) возможно формирование с помощью скриптов любых данных для вывода.

  • в остальных строках - по одному параметру String которая выведется

  • или: прямой текст указан, так и выведется

  • или: просто ничего (пробел), это будет пустая строка, типа вертикальная табуляция (например, для красоты при отделении блоков текста друг от друга и т.д.)

Примеры кода:

  • добавление позиции

    public void addPayment( Payment payment, Check check, Printer printer )throws BGException
    {
    // 1) строка сумма-контракт, плюс отдел (если надо, то вычисляется в этом же скрипте)
    check.addPayment( payment.getSumma(), payment.getContractTitle(), 0 );
    // 2) строка с каментом
    check.addString( payment.getContractComment() );
    // 3) пустая строка
    check.addString( " " );
    }
  • завершение формирования

    public void endCreate( int cid, Check check, Printer printer )throws BGException
    {
    check.addString( "footer 1" );
    check.addString( "footer 2" );
    check.addString( "footer 3" );
    }

Замечание

Обратите особое внимание, что в каждом скрипте формирования внешнего вида чека (а именно происходит формирование каждой отдельной позиции чека) обязательно должна присутствовать ровно одна команда addPayment для всех устройств, являющихся ККМ. Дополнительно может быть любое количество addString. Для устройств, представляющих обычный принтер, для FOP-устройств (см. ниже) и т.п. команда addPayment не нужна, так как там не происходит добавление продажи во внутреннюю память. Но сумма платежа будет считаться только для позиций, добавленных через addPayment.

Далее приведём пример кода "добавление позиции" для формирования FO-документа, для FOP-драйвера. Эти строки соответствуют шаблону cashcheck_pko.xsl, находящемуся в стандартной поставке сервера печати.

import bitel.billing.common.*;
import bitel.billing.server.admin.bean.*;

//…
//Сумма платежа: "120,00р." (делаем одну строку addPayment, чтобы общая сумма посчиталась)
check.addPayment( payment.getSumma(), String.valueOf(payment.getSumma()) + "р.", 0 );
//Номер договора
check.addString( payment.getContractTitle() );
//Фамилия клиента: "ИВАНОВ И.И."
check.addString( payment.getContractComment() );
//Дата платежа: 20-04-2009
check.addString( TimeUtils.format( payment.getDate(), "dd-MM-yyyy" ) );
//Организация: ООО "ПРОВАЙДЕР"
check.addString( "ООО \"ПРОВАЙДЕР\"" );
//ФИО кассира (пользователя биллинга)
UserManager um = new UserManager( con );   
User user = um.getUserByID( payment.getUserID() );
check.addString( user.getName() );
//Тип платежа: "СПД  №"
check.addString( "СПД  №" );
//Сумма прописью: "Сто двадцать рублей 00 коп"
check.addString( SummaToString.summaToString( String.valueOf(payment.getSumma()), true ) );
//…

В данном случае мы формируем 8 строк с произвольной информацией, которая передаётся в FOP-драйвер сервера печати, который из напрямую передаёт в FO-шаблон обычной линейной xml. Это позволяет формировать документ из любых строк, подготовленных в скрипте и из любого написанного шаблона.

Также в методы класса передаётся объект "printer" - объект "принтер", на который производится печать. Это может понадобиться, например, при наличии двух разных принтеров и желания печатать на них разного вида информацию и на разные принтеры использовать разные скрипты (например, для FOP и ККМ скрипты всегда разные будут). Например, можно получить ид принтера (такой, какой он в конфиге плагина):

int printerId = printer.getId();

3.4. Разделение по отделам в ККМ

Этот раздел относится логически к предыдущему про настройку внешнего вида чеков, так как затрагивает использование тех же скриптов. При желании разделять некоторые платежи по разным отделам можно использовать такую возможность, предоставляемую большинством ККМ. Для этого при добавлении в скрипте "формирование позиции чека" очередной позиции с помощью команды addPayment надо третьим параметром передать номер отдела.

Замечание

Имейте ввиду, что для каждого ККМ номера отделов имеют какой-то диапазон. Следует уточнить это в документации по устройству.

Вычислить номер отдела можно на основании любых данных, например, типа платежа, номера принтера и т.д. и т.п. Пример использования:

   int paymentDep = 0;
   switch( payment.getPaymentTypeID() )
   {
   case 1:
      paymentDep = 1;
   break;
   case 2:
      paymentDep = 2;
   break;
   // .... итд 
   }
   check.addPayment( payment.getSumma(), payment.getContractTitle(), paymentDep );

Можно просто отдавать в метод 0 (ноль), если вам не нужна эта возможность.

4. Использование плагина

4.1. Очередь печати

"Очередь платежей для печати" отображает все платежи, подходящие для печати по ним чека, но по которым чек напечатан ещё не был. Вызывается через Плагины->CashCheck, вкладка Очередь.

Очередь отображается для текущего выбранного (данным залогиненным пользователем биллинга) принтера. Для одного или нескольких платежей из очереди можно из этой таблицы напечатать чек.

Обратите внимание - запуск (или не запуск) сервера печати с каким-либо драйвером (реальным или виртуальным) никак не влияет на добавление или не добавление платежа в очередь. Сервер биллинга ничего об этом аспекте не знает - он посылает команды, которые не зависят от активированного драйвера. Можно ли платёж напечатать — зависит только от того, прописана ли соответствующая строка с типом платежа в конфиге плагина. Конечно, если указана принудительная печать чека, а сервер печати не запущен или настроен некорректно - будет выведена ошибка печати, но в очередь чек всё равно попадёт, если не был напечатан при добавлении платежа.

Не разрешено печатать платежи разных договоров на одном чеке. Это сделано специально - может возникнуть недоразумение, тем более, что у чека один подвал, куда передаётся код договора, чтобы там можно было печатать какие-то интересные сведения, вроде баланса договора. Да и потребности печатать в один чек разные договоры не бывает.

Подразумевается, что в этой очереди скапливаются платежи, которые забыли напечатать или не хотели. Рассматривать как справочную информацию и/или удобный поиск заглючивших при распечатке платежей. Двойным кликом можно перейти к договору.

4.2. Лог распечатанных платежей

Всё что уже напечаталось находится здесь. Можно перейти к договору. Печати чека нет. Есть фильтр по принтерам, в независимости от текущего выбранного. Рассматривать, как справочную информацию для истории.

4.3. Выбор принтера, отчёты, сервис

Для того, чтобы можно было работать с каким-либо регистратором, его надо предварительно выбрать для пользователя. Это можно сделать во вкладке Сервис диалога Плагины->CashCheck.

Выбирается из списка принтер, вводится пароль пользователя и нажимается Выбрать.

Для не выбранного принтера нельзя выполнять никакие операции. В этих случаях при первой попытке использовать принтер появится окошко с предложением залогиниться на принтер.

На этой же вкладке Сервис можно снимать отчёты, делать возвраты и производить другие действия (см. скриншот).

Также имеется кнопка "привет", по которой на выбранном в списке принтере печатается приветствие. Это было добавлено по просьбам пользователей, у которых много принтеров и кассиров - так проще контролировать тот ли принтер находится рядом с текущим рабочим местом.

4.4. Печать чека

Помимо печати чека из очереди печати (см. выше) имеется возможность печатать чеки прямо из списка платежей в договоре или сразу же при добавлении платежа.

В первом случае надо выбрать один или несколько платежей в таблице платежей (в части, соответствующей платежам-приходам), и в контекстном меню по правой кнопке мыши выбрать пункт Печать чека.

Во втором случае можно при добавлении платежа поставить внизу "Редактора приходов" галочку Печатать чек. В этом случае в момент добавления платежа инициируется печать чека.

Обратите внимание, если вы добавляете платёж с галочкой "напечатать", то платёж не добавится в очередь при успешной печати - предполагается, что он сразу ушёл на принтер. Если же не ушёл, то тогда он будет в очереди печати. Образно можно повторить сказанное выше: очередь печати - это очередь ещё не распечатанных платежей.

Если при добавлении платежа происходит распределение средств, то напечатается чек с несколькими позициями.

4.5. Настройка галочки в диалоге прихода платежа

Имеется возможность настроить галочку "печатать чек" в диалоге прихода платежа. По умолчанию она снята и доступна для изменения. Возможно, вы захотите запретить всем пользователям, кроме некоторых менять её состояние. Или наоборот. Для этого предусмотрены следующие настройки в конфигурации сервера (sic!).

# настройка для cashcheck, для клиента
# режим галочки "печатать чек" для каждого пользователя в диалоге прихода 
# defaultoff - по умолчанию снята галка, можно сменить (default)
# defaulton - по умолчанию установлена галка, можно сменить
# off - навсегда снята галка, сменить нельзя
# on - навсегда установлена галка, сменить нельзя
client.gui.cashcheck.user.dimon.checkbox.mode=defaultoff
# аналогично общая настройка для всех пользователей
# применится только тогда, когда явно не прописано для пользователя
# по умолчанию значение "defaultoff"
client.gui.cashcheck.default.checkbox.mode=defaultoff

Таким образом, можно задать общее поведение чекбокса, а также перекрывающее его поведение для каждого отдельно взятого логина. Например, запретить всем и отдельно навсегда назначить её кассирам.

Глава 42. Плагин КЛАДР

1. Назначение плагина

Плагин позволяет синхронизировать базу улиц с Классификатором адресов России (КЛАДР), предоставляемым Федеральной Налоговой Службой. http://www.gnivc.ru/downloads/kladr.aspx

2. Установка и настройка плагина

Плагин устанавливается с помощью утилиты bg_installer. После установки плагин должен быть активирован в меню Плагины=>Настройки плагинов и у него должна быть установлена конфигурация.

В конфигурации должно быть определено место на диске, где у клиента храниться база данных КЛАДР

driver.class.name=com.hxtt.sql.dbf.DBFDriver
db.url=jdbc:DBF:////home/billing/KLADR/base
сharset=Cp866

3. Использование плагина

После установки плагина в клиенте появиться меню Плагины=>Загрузка КЛАДР

Кнопка Создать (пересоздать) индекс используется для создания индексов базы КЛАДР при первом обращении к базе, либо при обновлении базы КЛАДР.

Для загрузки нужного Вам населённого пункта используется поиск по названию. Перед загрузкой необходимо создать населённый пункт в справочнике городов. После завершения поиска выводятся населённые пункты, совпадающие по названию с выбранным городом. При выборе населённого пункта в списке слева в правой верхней части отображаются его данные. Кнопка Показать улицы позволяет увидеть список улиц.

При загрузке настраивается какие части включать в название города. В частности, можно включить регион и район в прямом или обратном порядке. По умолчанию сокращение "ул." в названии улицы игнорируется, но можно отменить данное ограничение. При нажатии кнопки Обновить базу начнётся обновление базы.

При обновлении базы происходит синхронизация названий улиц с базой КЛАДР. Для улиц, не имеющих синхронизации по коду, предлагается сделать выбор вручную. Есть возможность выбрать из списка с какой из похожих улиц ассоциировать улицу из КЛАДР, также есть возможность пропустить улицу (оставить в базе как есть) и удалить улицу из базы.

Глава 43. Плагин CRM

1. Введение

Замечание

Данный плагин предоставляет лишь простейший функционал CRM-системы и в дальнейшем не будет развиваться. В будущих версиях поддержка плагина будет удалена. Вместо него предлагается специализованная CRM-система BGCRM, имеющая функционал интеграции с BGBilling. Настоятельно не рекомендуется использование плагина новым клиентам. Для уже использующих плагин клиентов предлагается постепенный переход на BGCRM.

Плагин CRM позволяет учитывать звонки клиентов, вести учёт и разбор проблем, а также имеет гибкую подсистему выдачи, отслеживания, выполнения и обработки выполненных задач.

Журналы задач и звонков доступны как в глобальном контексте в меню Плагины=>CRM, так и в контексте одного договора на вкладке CRM. Журнал проблем только глобальный.

Данные вкладки доступны только после установки и активации плагина CRM.

2. Настройка плагина

В конфигурации плагина вы можете поменять темы писем с отчётами по звонкам, проблемам и задачам. Другие опции описаны ниже.

register.task.call.subject=Отчет по звонку
register.problem.mail.subject=Отчет по проблеме
register.task.mail.subject=Отчет по задаче
#возможность закрытия задачи будущим периодом
#close.task.future=1 

#Код параметра договра  ФИО. Задавать нужно через запятую,
#из перечисленных параметров берется ТОЛЬКО последний не пустой параметр
#это сделано для случаю если например нужно в задачах показать ФИО или название органицации
#contract.fio.param.id=10, 20 

#Код параметра договора  Телефон. устарел, обозначет параметр типа текст.
#register.param.phone=10

#Код параметра договора  Телефон. Возможно указание нескольких значений, значения объединяются в одну строку.  
#Напрмер, 49 и 50 параметры типа phone, 24 параметр типа text.
#contract.phone.param.id=49,text:24,50

3. Справочники

Справочники Журнала проблем расположены в меню Справочники=>Другие , их названия начинаются с префикса "CRM -". Для начала работы необходимо указать:

- типы звонков клиентов и группу по умолчанию, на которую переводится проблема по каждому типу звонка;

- группы решения проблем и задач и e-mail адреса, на которые слать информацию по проблемам/задачам/звонкам при нажатии кнопки ОК+E-Mail (несколько адресов вводятся через запятую);

- исполнители, каждый из которых может входить в несколько групп;

- категория - характеристика, которая назначается проблеме после её разрешения (конечная причина), используется для отчётности;

- тип задачи - характеристика, которая назначается задаче.

4. Журнал звонков

Звонки обладают только одной настраиваемой характеристикой: тип и могут быть привязаны к какой-либо не закрытой на данный момент проблеме. При этом проблема может быть создана автоматически и привязана к данному звонку.

При привязке к звонку проблемы и нажатию ОК+Mail письмо отсылается на группу решения проблемы. Шаблон письма - файл register_call.xsl

Внимание

Не допускайте скопления большого количества не закрытых проблем в журнале проблем! Это может привести к очень медленному открыванию редактора в журнале звонков.

Если звонок добавлен в договоре на вкладке CRM, то он привязывается к данному клиенту, иначе звонок считается не клиентским.

Начиная с 4.3 версии звонок может быть привязан к объекту договора.

Редактирование звонка разбито на 3 вкладки .

Вкладка "Тип Звонка" : Тут можно выбрать тип звонка.

Вкладка "Группа": Здесь выбирается группа звонка.

Вкладка "Проблема": Тут можно привязать звонок к проблеме. Для этого необходимо выбрать либо одну из уже существующих проблем, либо создать новую.

5. Журнал проблем

Проблема глобальна, но к ней могут быть привязаны звонки клиентов. Проблема обладает следующими характеристиками:

  • текущая группа решения;

  • текущий список исполнителей;

  • список привязанных к проблеме звонков;

  • комментарий - исходное описание проблемы;

  • участвовавшие группы - список групп, между которыми переходила проблема (по ходу разбора);

  • ход решения - текстовое описание процесса решения проблемы;

  • категория - характеристика, назначающаяся проблеме после её разрешения (конечная причина), используется для отчётности.

В ходе решения проблема проходит следующие состояния: открыта - принята - закрыта. При этом принятие проблемы обычно означает назначение ей конкретной группы решения и исполнителей. Кроме этого можно добавлять свои статусы. Для настройки статусов нужно в добавить в конфигурацию плагина:

# список статусов проблемы, по умолчанию "0:открыта;1:принята;2:закрыта"
register.problem.status.list=0:открыта;1:принята;2:закрыта;3:отложена
# код статуса присваеваемый проблеме при создании
register.problem.status.default=0
# код статуса для закрытой проблемы
register.problem.status.close=2

Для большего удобства проблема имеет характеристику "срочность", в зависимости от которой меняется цветовая индикация в таблице проблем.

В ходе решения проблема может переходить между различными группами; все участвовавшие группы запоминаются. В поле Комментарий вносится изначальное описание проблемы, Ход решения - описание процесса разбора. В столбце "Договора" показыны договоры, звонки которых привязаны к данной проблеме. Их можно также увидеть во всплывающем меню по нажатию правой кнопокой на конретной проблеме, и, если выбрать в этом меню конретный договор, то он откроется.

Также как и звонок проблема может быть отправлена на почту текущей группе решения, шаблон письма - файл register_problem.xsl Также возможно создание отчёта по списку проблем с отправкой его в файл/на печать, либо на почту. Шаблон отчёта находится в файле register_problems.xsl. С помощью кнопки "OK+печать наряда" можно отправить конретную проблему на печать (шаблон register_print_problem_order.xsl).

Доступна история изменения проблемы. Для просмотра истории щелкните правой кнопкой мышки по проблеме в таблице и выберите пункт "История изменений".

6. Журнал задач

Задача - конкретное мероприятие, которое нужно провести с конкретным клиентом. В зависимости от проблемы для задачи заранее определены группа решения и характер работы. Примером задач могут быть подключения и отключения клиентов.

В ходе решения задача проходит следующие состояния: открыта - принята - закрыта.

Как уже упоминалось, задача привязана к конкретному договору и может быть добавлена только в контексте договора на вкладке CRM. Кроме того, для удобства задача привязывается к адресу клиента и в ней выводятся ФИО и Телефон клиента. Для этого необходимо добавить в конфигурации плагина:

#параметры договора для задачи  
#значения кодов параметров, содержащих ФИО клиента (берется последний не пустой параметр из перечисленных) 
contract.fio.param.id=<код параметра 1>[,<код параметра 2>]  
#код(ы) параметра, содержащего телефон(ы) клиента (параметры склеиваются)
contract.phone.param.id=<text:код_параметра_типа_ТЕКСТ>[,<phone:код_параметра_типа_ТЕЛЕФОН>]

Задача проходит статусы: открыта - принята - закрыта.

В отличие от проблем задачи поддерживают блочную обработку - возможно принятие, открытие и закрытие сразу нескольких выбранных задач. Таким образом можно быстро раздавать наряды группам решения.

Также возможна процедура обработки задачи - при этом всем договорам будет прислано сообщение о завершении обработки задачи, которое может быть обработано скриптом BGBS. Например, возможно автоматическое включение абонплаты после подключения клиента.

Для того, чтобы печатать отчёты или отправлять их на почту возможно добавление одной или нескольких форм отчёта. Для этого добавьте в конфигурацию плагина строку, аналогичную приведённой ниже:

register.task.report.format=register_tasks.xsl:Отчет по подключению;register_tasks_1.xsl:Отчет по обслуживанию;register_tasks_2.xsl:Отчет по должникам

Здесь перечислены файлы с форматом отчёта и названия отчётов, выводимые в выпадающем списке в левом нижнем углу фильтра. Файл register_tasks.xsl идёт с дистрибутивом и может быть использован в качестве примера.

Для получения краткой сводки о задаче необходимо нажать на строку правой кнопкой и выбрать пункт меню Скопировать в буфер. Шаблон краткой сводки - register_task_short.xsl.

При печати наряда по конкретной задаче можно настроить отдельные шаблоны для них. Для этого следует добавить в конфигурацию плагина строки, аналогичные приведенным ниже:

#Требуется ли в итоговую XML для наряда включать параметры договора
order.print.add.contract.params=<true|false>
#файл xsl-шаблона наряда для определенного типа задач
register.print.task.order.<id>.xslt=connecting.xsl

Где <id> - это id задачи в справочнике "CRM - типы задач".

Редактирование задачи выглядит следующим образом:

С помощью кнопки "OK+печать наряда" можно отправить конретную задачу на печать (шаблон register_print_task_order.xsl).

Есть возможность выделить задачи определенным цветом в зависимости от количества часов, оставшихся до поставленных сроков выполнения. Для этого следует добавить в конфигурацию плагина строки, аналогичные приведенной ниже:

task.hour=24,48,96

Где цифры 24,48,96 - это часы оставшиеся до выполнения задач. По умолчанию они будут закрашиваться градациями серого цвета. Чем ближе задача к наименьшему интервалу, тем темнее она будет выделена.

Но есть так же возможность вместо градации серого задавать свои цвета. Для этого помимо добавления предыдущей сроки следует добавить в конфигурацию плагина строки, аналогичные приведенным ниже:

task.color.24=00FFFF
task.color.48=80CC80
task.color.96=00FF00

Где 00FFFF - цвет, которым будут выделены задачи, у которых оставшееся часы до выполнения менее 24, 80CC80 - оставшиеся время лежит в пределах 24-48 часов и 00FF00, если 48-96.

7. Журнал работ.

Функционал работ в текущий момент не доведен до конца и поэтому тут не описан . Пока можете их не использовать.

Глава 44. Плагин Dispatch

1. Назначение плагина

Плагин рассылок предназначен для управления пользовательскими рассылками. Данным плагином предоставляется единый интерфейс управления как новостными рассылками (т.е. рассылками, отправка сообщений которых происходит по мере поступления новой информации), так и периодическими рассылками о балансе, трафике, наработке и т.п.

2. Настройка плагина

Перед началом настройки плагина необходимо его установить при помощи утилиты bg_installer аналогично другим модулям и плагинам.

После установки необходимо настроить задачу Задача отправки рассылок на выполнение каждую минуту! Это важно, поскольку в противном случае возможны пропуски отправки по расписанию определённых рассылок.

В конфигурации плагина возможно использование следующих опций:

# задание названия пункта меню в личном кабинете для управления рассылками, none - скрыть пункт меню (по умолчанию показывать)
#web.menuItem1=Подписка на рассылки | none
#префикс для сообщений отправляемых по электронной почте
#message.title.prefix=PROVIDERNAME - 

3. Использование плагина

3.1. Общий обзор

Основным понятием плагина является Рассылка. Рассылка представляет из себя, по сути, контейнер для шаблонов сообщений (или просто: сообщений) с определённым набором характеристик: названием, расписанием отправки (или его отсутствия), способом отправки, типом контактов, которые могут осуществлять подписку на рассылку, набором условий отправки рассылки.

На данный момент системой поддерживаются следующие типы отправки сообщения:

  • по E-mail;

  • по SMS (через шлюзы smsc.ru, enterix.ru и smsaero);

  • через скрипт.

Сообщение рассылки представляет из себя шаблон, который перед отправкой конечному подписчику преобразуется в конкретное сообщение путём подстановок данных вместо различных макросов, например, номера договора, фамилии клиента, баланса на счёте и т.п. К сообщению также можно прикреплять файлы (однако их отправка может не поддерживаться какими-либо отправителями). Также имеется возможность задать собственное тело сообщения с помощью соответствующих макросов.

Рассылки можно функционально разделить на новостные и периодические рассылки:

  • Новостные рассылки - это рассылки, отправка сообщений которых происходит на каждой итерации срабатывания задачи отправки рассылок. При этом для отправки выбираются ещё неотправленные сообщения, время отправки которых уже пришло. После отрабатывания задачи они помечаются как "отправленные".

  • Периодические рассылки - это рассылки, у которых есть фиксированное расписание отправки, задаваемое аналогично расписанию выполнения задач планировщика (об этом ниже). Отправка сообщений таких рассылок происходит по указанному расписанию, причем при каждой отправке конечному пользователю отправляются все сообщения данной рассылки! В периодических рассылках, как правило, заводится одно сообщение.

Рассылки могут быть глобальными или персоналными:

  • Глобальные рассылки - по умолчанию для новых рассылок. Сообщения таких рассылок приходят всем подписчикам в одном и том же виде, в одно и то же время. Время отправки устанавливается для всей рассылки в целом.

  • Персональные рассылки - это рассылки, для которых подписчики могут указать дни недели, в которые они хотят получать сообщения. Также подписчики персональных рассылок могут указывать дополнительные условия, при которых нужно присылать сообщения, например, диапазон баланса для рассылки баланса или логин модуля, для получения детализации по нему.

Каждая рассылка характеризуется также типом контактов, которыми возможно подписаться на эту рассылку. Типы контактов заводятся администратором биллинга вручную, при этом указывается их описание и регулярное выражение для проверки корректности вводимых данных.

Каждый пользователь может заводить неограниченное количество контактов определённого типа. Каждый пользователь может создавать неограниченное количество подписок на рассылки. Подписка на рассылки характеризуется самой рассылкой, на которую была осуществлена подписка, списком контактов, а также (опционально) набором индивидуальных условий отправки сообщений рассылки.

Основное окно плагина расположено в меню Плагины => Рассылки.

На нем расположены три вкладки: Менеджер рассылок, Менеджер контактов и Методы отправки.

3.2. Типы контактов

Настройка типов контактов происходит в Менеджере контактов.

Для создания нового типа контакта необходимо указать его название, описание (которое будет видно пользователям) и регулярное выражение (шаблон), которым будет проверяться валидность введённых данных. Существует ряд предустановленных шаблонов типов контактов, это:

  • E-mail, которому соответствует шаблон ^[A-z0-9._%+-]+@[A-z0-9.-]+\\.[A-z]{2,4}$

  • Пользовательский шаблон, необходимо указать его вручную, пользовательское регулярное выражение должно начинаться с ^ и оканчиваться $.

3.3. Поиск по контактам

Поиск можно производить по названию и типу контакта.

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

3.4. Методы отправки

Метод отправки - это серверная логика реальной фактической отправки конечного сообщения подписчику. Настройка методов отправки происходит во вкладке Методы отправки. На данный момент существуют следующие встроенные механизмы отправки сообщения:

  • Email - отправка сообщения осуществляется на почтовый ящик подписчика, при этом отправляются также все приложенные файлы.

              
  • SMS (smsc.ru) - отправка сообщения осуществляется на мобильный телефон подписчика, посредством смс сообщения.

    sender.sms.smsc.login=
    sender.sms.smsc.sender=
    sender.sms.smsc.password=
  • SMS (enterix.ru) - отправка сообщения осуществляется на мобильный телефон подписчика, посредством смс сообщения.

    sender.sms.enterix.login=
    sender.sms.enterix.sign=
    sender.sms.enterix.password=
  • SMS (smsaero.ru) - отправка сообщения осуществляется на мобильный телефон подписчика, посредством смс сообщения.

    sender.sms.smsaero.login=
    sender.sms.smsaero.password=D06071FC526EA03696 - ваш пароль в md5.(можно воспользоваться Утилиты->Вычисление Digest)
    sender.sms.smsaero.sign=SiGnAtUrE  - ваша подпись(предварительно заведення в л/к smsaero.ru ).

Помимо встроенных способов отправки сообщения существует возможность реализации пользовательских способов отправки. Для реализации этой возможности необходимо воспользоваться механизмом динамически загружаемых Java-классов. Необходимо создать динамический класс, реализующий интерфейс ru.bitel.bgbilling.plugins.dispatch.server.sender.Sender, а затем создать метод отправки нажатием на кнопку Добавить в панели инструментов, указав этот класс в выпадающем списке.

3.5. Создание и редактирование рассылки

Создание новой рассылки осуществлять через кнопку Добавить в панели инструментов во вкладке Менеджер рассылок. При этом откроется редактор рассылки.

В редакторе рассылки необходимо указать следующие параметры:

  • Название - название рассылки, его будут видеть и пользователи, и операторы биллинга;

  • Тип рассылки - выпадающий список выбора способа отправки сообщений;

  • Тип контактов для подписки на рассылку;

  • Активна - если не отмечено, рассылка отправляться не будет;

  • Персональная - позволяет пользователям через личный кабинет самим устанавливать дни недели, в которые они хотят получать рассылку. Время отправки сообщений (часы и минуты), устанавливаются для самой рассылки. При создании подписки на персональные рассылки пользователи также могут указывать условия, при которых им нужно отправлять сообщения рассылки (напр., условия по балансу, для модулей Inet и VoiceIP - выбирать логин).

  • Не помечать сообщения отправленными - позволяет не отмечать сообщения отправленными для глобальных непериодических рассылок. Это можно использовать, к примеру, когда нужно отправлять одно и то же сообщение, в теле которого присутствуют макросы, а само сообщение должно отправляться по событию (например, сообщение о пополнении баланса договора или о занесении расхода). Данный параметр автоматически устанавливается для персональных и периодических рассылок.

  • Только один контакт - если отмечено, будет позволено выбрать только один контакт;

  • Отправка по расписанию - это флаг, обозначающий наличие или отсутствие расписания отправки у рассылки;

  • Минуты, Часы, Дни, Дни недели и Месяцы, когда происходит отправка рассылки, данные в этих полях заполняются аналогично расписанию задач в планировщике заданий. Для пользовательских рассылок доступны для изменения только поля Часы и Минуты. Дни недели для отправки в этом случае определяются настройками подписки для конкретного договора.

По кнопке Показать условия отправки откроется окно условий отправки, которые накладываются на данную рассылку глобально для всех подписок. Подробнее об условиях отправки см. здесь.

По кнопке Показать сообщения откроется окно редактирования сообщений, подробнее о редакторе сообщений см. далее. При создании новой рассылки сообщения не будут созданы.

После заполнения необходимых полей нажмите на кнопку ОК.

3.6. Подписка на рассылки

Настройка подписок договора осуществляется на вкладке Рассылки в договоре.

3.6.1. Контакты

Для заведения контактов определённого типа необходимо перейти на вкладку Контакты. Далее нажать на кнопку Добавить в панели инструментов. После этого необходимо выбрать тип заводимого контакта и указать его значение.

3.6.2. Рассылки

Для подписки на рассылки необходимо перейти на вкладку Рассылки. Здесь можно увидеть таблицу осуществлённых подписок. Для создания новой подписки необходимо нажать на кнопку Добавить в панели инсрументов.

В открывшейся слева панели необходимо выбрать вид рассылки в выпадающем списке сверху, затем указать необходимые контакты из списка контактов и заполнить комментарий к рассылке. Для персоналных рассылок необходимо проверить наличие условий отправки и, по необходимости, заполнить их данными. Для персональных рассылок можно также изменить дни недели, в которые будет приходить рассылка.

3.6.3. Автоматизация подписки на рассылки с помощью групповой операции

Для автоматизации создания подписок на одни и те же рассылки для большого числа договоров, отфильтрованных по определенным условием, есть возможность использовать групповую операцию. Для этого необходимо предварительно отфильтровать список договоров, для которых необходимо добавить подписку, после этого перейти в меню Сервис->Администрирование->Групповые операции, активировать групповую операцию плагина Dispatch: Подписка на рассылки, нажать кнопку Договоры в левой верхней части окна и выбрать из появившегося списка необходимые договоры.

Для приведения групповой операции в действие необходимо нажать кнопку Все или Следующий для выполнения всех выбранных групповых операций в автоматическом или пошаговом режиме соответственно.

3.7. Создание и редактирование сообщений

Для просмотра сообщений конкретной рассылки откройте вкладку Плагины => Рассылки => Менеджер рассылок, нажмите кнопку Редактировать в панели инструментов и далее нажмите кнопку Показать сообщения.

На панели справа можно увидеть список сообщений. Для редактирования\добавления\удаления сообщений необходимо воспользоваться соответствующими кнопками в панели инструментов редактора сообщений. При редактировании или создании сообщения откроется редактор сообщений.

Для создания сообщения необходимо указать заголовок сообщения и тело сообщения. Для загрузки в тело сообщения данных из файла, необходимо нажать кнопку Загрузить содержимое из файла и выбрать файл.

Внимание

Кодировка содержимого в файле должна быть UTF-8.

Также есть возможность прикрепления файлов к сообщению. Для этого в окне справа нажмите кнопку ... и выберите файл. После этого нажмите кнопку Загрузить.

Для сообщения также есть возможность указания времени отправки сообщения для отложенной отправки сообщения. Будут отправлены только те сообщения, время которых уже пришло.

В теле сообщения могут присутствовать макросы, вместо которых при отправке этого сообщения конечному подписчику будут подставлены соответствующие данные этого подписчика. На данный момент системой поддержаны следующие макроподстановки:

  • $${title} - номер договора;

  • $${comment} - комментарий договора;

  • $${parameter:<PID>} - параметр договора, здесь <PID> - это код параметра договора, например $${parameter:5};

  • $${balance} - баланс договора на момент отправки;

  • $${saldo} - сальдо договора на момент отправки;

  • $${module:<MID>:<FUNCTION>} - вставка модульных данных, здесь <MID> - код модуля, <FUNCTION> - название функции запрашиваемых данных, например, $${module:10:detail};

  • $${class:<FULLY.QUALIFIED.CLASS.NAME>} - глобальная макроподстановка, позволяющая полностью изменять тело сообщения с помощью пользовательских динамических классов рассылок, здесь <FULLY.QUALIFIED.CLASS.NAME> - полное имя пользовательского класса. Пользовательский класс должен наследовать абстрактный класс ru.bitel.bgbilling.plugins.dispatch.server.bean.message.CustomDispatchMethod и переопределять метод String getMessageBody(). Возвращаемое значение и будет телом сообщения. В классе доступен объект java.sql.Connection для соединения с БД, а также код договора, для которого предназначено данное сообщение.

Далее описаны поддерживаемые модули и их функции.

3.7.1. Модуль Inet

В плагине рассылок есть возможность вставки Отчёта по сессиям пользователя модуля Inet в рассылку. Для этого используется имя функции session. При этом в сообщение будет прикреплена детализация в формате HTML, а на месте макроса будет фраза "Детализация по сессиям во вложении".

3.7.2. Модуль VoiceIp

В плагине рассылок есть возможность вставки Отчёта по направлениям модуля VoiceIp в рассылку. Для этого используется имя функции direct. При этом в сообщение будет прикреплена детализация в формате HTML, а на месте макроса будет фраза "Детализация по направлениям во вложениях".

3.7.3. Модуль DialUp

В плагине рассылок есть возможность вставки Отчёта по сессиям модуля DialUp в рассылку. Для этого используется имя функции session. При этом в сообщении будет прикреплена детализация в формате HTML, а на месте макроса будет фраза "Детализация по сессиям во вложениях".

3.8. Условия отправки

Условия отправки представляют из себя набор ограничений, условий или настроек, которыми обладает рассылка.

Только выполнение требований этих условий в каждый момент отправки конечному подписчику позволяет выполнить отправку. Каждое условие отправки состоит из трёх составных частей:

  • интерфейса настройки условия отправки для всей рассылки глобально (в простейшем случае может иметь только флаг включено\отключено);

  • интерфейса настройки условия отправки для конкретной подписки на рассылку (в простейшем случае может отсутствовать);

  • логики проверки выполнения условия на сервере.

Ниже перечислены все условия отправки, поддерживаемые системой.

3.8.1. Отправка по событию

Данное условие представляет собой универсальный способ отправки рассылки. Настройка данного условия в меню настройки рассылки заключается только во включении\отключении условия. Настройка данного условия в меню настройки подписки отсутствует.

Для успешной проверки на выполнение данного условия перед отправкой конечному подписчику в настройках конкретной подписки на рассылку должен присутствовать флаг "событие произошло". Предполагается, что данный флаг устанавливается из какого-либо скрипта поведения, среагировавшего на то или иное событие. Например, если у клиента изменился статус на "Отключён", то соответствующий скрипт, обработавший данное событие, устанавливает соответствующий флаг в настройках его (клиента) подписки на рассылку, информирующую об отключении абонента за долги. Тогда задача отправки рассылок на очередной итерации отправки при проверке условия данной подписки установит, что данное условие выполнено и отправка уведомления об отключении произойдет.

Пример части скрипта, обрабатывающего событие Статус изменён, который устанавливает флаг в настройках подписки:

//код рассылки "уведомление об отключении"
int dispatchId = X;
//код договора, для которого сработало событие
int contractId = Y;
//получаем список всех подписок на эту рассылку для данного договора
List<Subscription> subscriptions = service.getSubscriptions( dispatchId, contractId );
//каждой рассылке устанавливаем флаг условия отправки по событию в 1
for( Subscription subscription : subscriptions )
{
    subscription.getPreferences().set( DispatchEventCondition.EVENT_OCCURED_FLAG, "1" );
    service.updateSubscriptions( subscription );
}

3.8.2. Отправка по балансу

Данное условие выполняется только тогда, когда баланс договора на момент отправки находится в указанных в условии пределах. Настройка данного условия в меню настройки рассылки заключается в установке диапазона баланса, для которого происходит отправка. Настройка данного условия в меню настройки подписки отсутствует.

3.8.3. Ограничение частоты отправки

Данное условие выполняется только тогда, когда последняя отправка той же рассылки произошла не ранее, чем через указанное количество дней в настройках. Настройка данного условия в меню настройки рассылки заключается в установке количества дней между отправкой рассылки. Настройка данного условия в меню настройки подписки отсутствует.

3.8.4. Ограничение по группе договора

Условие по группе договора выполняется только тогда, когда подписчик состоит хотя бы в одной из выбранных групп договоров. Настройка условия в настройках подписки отсутствует.

3.8.5. Ограничение по адресу подписчика

Данное условие позволяет ограничить рассылку с учетом адреса подписчика. Корректная работоспособность данного условия гарантируется только в том случае, если адреса абонентов представляют собой параметр договора с типом Адрес. В настройках условия сперва необходимо выбрать тип адресного параметра, по которому будет включено ограничение. Далее из справочника адресов биллинга подгружается список стран. Выбрав страну, подгружается список городов. Для выбранного города загружается список улиц, а для выбранной улицы подгружается список домов на этой улице.

Принцип работы ограничения:

  1. Если вы выбираете только город, то рассылка будет отправляться всем абонентам из этого города.

  2. Если вы выбираете город и улицу, то рассылка будет отправляться всем абонентам, проживающим на выбранной улице выбранного города.

  3. Если вы выбираете город, улицу и дом, то рассылка будет отправляться всем абонентам по указанному адресу.

Настройка условия в настройках подписки отсутствует.

3.8.6. Указание сервиса модуля Inet

Данное условие актуально только при наличии установленного модуля Inet. Активация данного условия обязательна для рассылок детализаций модуля Inet.

Данное условие выполняется только тогда, когда в настройках подписки будет указан какой-либо сервис модуля Inet. Настройка данного условия в меню настройки рассылки заключается во включении\отключении данного условия. Настройка данного условия в настройках подписки заключается в установке необходимого сервиса модуля Inet из списка.

3.8.7. Указание логина модуля VoiceIP

Данное условие актуально только при наличии установленного модуля VoiceIP. Активация данного условия обязательна для рассылок детализаций модуля VoiceIP.

Данное условие выполняется только тогда, когда в настройках подписки будет указан какой-либо логин модуля VoiceIP. Настройка данного условия в меню настройки рассылки заключается во включении\отключении данного условия. Настройка данного условия в настройках подписки заключается в установке необходимого логина модуля VoiceIP из списка.

3.8.8. Указание логина модуля DialUp

Данное условие актуально только при наличии установленного модуля DialUp. Активация данного условия обязательна для рассылок детализаций модуля DialUp.

Данное условие выполняется только тогда, когда в настройках подписки будет указан какой-либо логин модуля DialUp. Настройка данного условия в меню настройки рассылки заключается во включении\отключении данного условия. Настройка данного условия в настройках подписки заключается в установке необходимого логина модуля DialUp из списка.

3.9. Пользовательские классы сообщений

В случае, если простых макроподстановок не достаточно для получения нужного вида сообщения отправляемой рассылки, можно использовать специальную макроподстановку, позволяющую настроить тело рассылаемого сообщения под свои нужды.

3.10. Web-интерфейс

Осуществлять подписку на рассылки может как оператор биллинга, так и непосредственно сам пользователь. Плагин добавляет в меню пользователя пункт Подписка на рассылки. Данное меню содержит две "вкладки": Мои контакты и Мои подписки. По умолчанию открывается вкладка с контактами.

3.10.1. Мои контакты

На вкладке с контактами отображается таблица текущих контактов.

Для удаления ненужных контактов используется кнопка Удалить. Для добавления нового контакта необходимо нажать кнопку Новый.

Далее необходимо указать тип добавляемого контакта и ввести его значение.

3.10.2. Мои рассылки

Здесь отображается таблица с подписками на рассылки. Для отказа от рассылки необходимо нажать на кнопку Удалить.

Для редактирования рассылки необходимо нажать кнопку Редактировать. Для добавления новой рассылки необходимо выбрать её из выпадающего списка снизу и нажать кнопку Новая подписка. В обоих случаях откроется редактор подписок.

Для осуществления подписки необходимо выбрать контакты и указать условия отправки, если таковые имеются. Также при подписке можно добавить к ней комментарий.

3.11. Конвертирование рассылок с версии 5.1

На данный момент реализована возможность переноса данных о рассылках баланса с версии 5.1. Для этого нужно запустить следующую команду в директории сервера:

${JAVA_HOME}/bin/java -Xmx256m -cp .:./lib/*:lib/jms/*:classes:./lib/ext/bgcommon-boot.jar ru.bitel.common.bootstrap.Boot ru.bitel.bgbilling.plugins.dispatch.server.utils.Converter arg1 arg2

Конвертер принимает на входе 2 параметра:

  • arg1 - имя базы данных, в которой находятся таблицы с данными по старым рассылкам. Если база данных текущая, нужно указать пустую строку (в кавычках);

  • arg2 - id контакта типа e-mail. Тип контакта можно добавить вручную в меню Плагины=>Рассылки=>Менеджер контактов и указать id этого типа контакта при запуске скрипта. Другой вариант - при запуске указать "-1" (без кавычек), при этом этот тип контакта будет создан автоматически.

После выполнения конвертации будет создана рассылка "Рассылка баланса" со стандартным сообщением рассылки, которое можно будет в дальнейшем редактировать. Для договоров, которые были подписаны ранее на рассылку баланса будут созданы соответствующие подписки.

Глава 45. Плагин Documents

1. Назначение плагина

Плагин предназначен для хранения документов, привязанных к договору клиента, отслеживания их версий и предоставления клиенту возможности загрузки документов через страницу Web-статистики, а также возможность генерации документов по заранее сформированному шаблону.

2. Установка и настройка плагина

Плагин устанавливается с помощью утилиты bg_installer. После установки плагин должен быть активирован в меню Плагины=>Настройки плагинов и у него должна быть установлена конфигурация.

В конфигурации должно быть определено место на диске, где сервер биллинга будет хранить документы и шаблоны документов. Каталог должен быть доступен для записи пользователю, под которым запускается сервер биллинга. Также имеется возможность открытия файлов напрямую с расшаренной папки без скачивания, в случае необходимости.

# серверный путь, куда складируются файлы (корень)
file.storage.root.path=/var/billing_doc
# серверный путь, где будут расположены файлы шаблонов
file.storage.pattern.path=/var/billing_pattern
# путь, из которого могут открываться файлы
file.net.share.root.path=/var/billing_files

Также стандартно может задаваться название пункта меню

# наименование пункта меню в Web-интерфейсе
web.menuItem1=Документы

Для задания статуса, который будет присваивается сгенерированным документам по умолчанию используется следующая опция:

#статус по умолчанию для сгенерированных документов
default.status=<код статуса из справочника статусов>

В случае использования в качестве шаблона документов файла в формате odt, необходимо указать полный путь до исполняемого файла LibreOffice

#путь до исполняемого файла
libre.path=

Для различных типов договоров возможно указать папку, которая будет открываться при выгрузке/загрузке файлов документа через клиент биллинга. Папка должна быть доступна с единым именем на всех машинах, где запускается клиент.

contract.type.<type_id>.prefix=<prefix>
contract.type.<type_id>.dir=<dir>
contract.type.<type_id>.extract.regexp=<regexp1>
contract.type.<type_id>.compare.regexp=<regexp2>
#автоматическое создание поддиректорий, если они не существуют
contract.type.<type_id>.dir.auto.create=<true|false>

Где:

<type_id> - уникальный числовой идентификатор типа договора в пределах конфигурации;
<prefix> - префикс номера договора;
<dir> - доступный с клиентской машины общий каталог с подкаталогами договоров;
<regexp1> - регулярное выражение для извлечения из номера договора ключевой последовательности;
<regexp2> - регулярное выражение для определения подкаталога, с ключевым словом <EXTRACT>, заменяемым на извлечённую ключевую последовательность.

Например, файлы договоров x<номер> размещаются в каталогах /tmp/TT<номер>.

contract.type.1.prefix=x
contract.type.1.dir=/tmp
contract.type.1.extract.regexp=x(\d+)
contract.type.1.compare.regexp=TT<EXTRACT>

3. Использование плагина

После установки и активации плагина в каждом договоре появляется вкладка Документы. В редакторе справочников, доступном через меню Плагины=>Документы, должны быть определены перечни статусов документов, типы документов и журналы документов.

В договоре на вкладке Документы отображаются документы договора. Для добавления нового документа выберите Новый элемент на стандартной панели инструментов.

Далее введите название документа, выберите его тип, журнал и текущий статус. Для статуса можно ввести комментарий. История изменений статуса документа отображается в соответствующей таблице справа.

Нажмите ОК для сохранения документа.

На вкладке Файлы выберите файл, соответствующий текущему статусу документа, и загрузите его на сервер, нажав кнопку .

В дальнейшем вы можете загружать новые версии документа и выгрузить любое его состояние, выбрав строку в таблице и нажав на кнопку . Для удаления документа нажмите кнопку

Нажав кнпоку , можно открыть документ в приложении операционной системы, с которым ассоциирован данный тип файлов. Также открыть документ можно щелкнув дважды на строке в таблице.

4. Шаблоны документов

Для автоматизации заполнения типовых форм документов предназначена функция генерации документов по шаблону. Шаблон документа заводится в редакторе шаблонов, доступном через меню Плагины=>Документы=>Шаблоны документов.

Для создания нового шаблона документа щелкните на кнопку Новый элемент на стандартной панели инструментов. В появившемся редакторе заполните необходимые поля, выберите файл шаблона - документ в формате docx (предпочтительный формат), odt (на сервере должен быть установлен пакет LibreOffice), xlsx.

На представленном выше рисунке отображены следующие поля:

  • Имя шаблона - имя шаблона документа;

  • Имя выходного документа - название документа, который будет сгенерирован и привязан к договору;

  • Файл шаблона - загружаемый шаблон документа в формате docx, odt, xlsx;

  • Комментарий к файлу - комментарий к загружаемому файлу шаблона;

  • Имя выходного файла - имя сгенерированного файла;

  • Комментарий к шаблону - комментарий шаблона;

  • Динамический класс - Java-класс, в котором возможно определить логику получения данных для шаблона;

  • Видимость шаблона в плагине - флаг того, что шаблон будет отображен на вкладке Документы в договоре;

  • Переменные - список переменных, содержащихся в файле шаблона документа;

  • Таблицы - список таблиц, которые требуется сгенерировать в файле шаблона документа.

Файл шаблона представляет собой текстовый документ, содержащий в своем тексте специальные последовательности, на место которых будут подставлены данные. Формат таких последовательностей имеет вид:

{имя_переменной} или {имя_переменной(значение_по_умолчанию)}

где имя_переменной - название этой последовательности; в тексте шаблона данное название должно совпадать с именем переменной в таблице Переменные;

значение_по_умолчанию - то значение, которое будет подставлено вместо последовательности в случае, если по имени перменной возвратится пустое значение (н-р, если в договоре отсутствует какой-либо заполненный параметр, то на его место можно поставить прочерк или какую-нибудь фразу ).

Новая переменная заводится с помощью редактора переменных, который вызывается нажатием на кнопку . Кнопками и можно отредактировать и удалить переменную соответственно.

В диалоговом окне редактора переменной задается имя переменной, ее тип и значение. Тип переменной выбирается в соответствующем выпадающем списке. Доступны следующие варианты:

  • Константа - значение переменной данного типа подставится в тело шаблона документа как есть. Данный тип переменной поддерживает макроподстановки, о которых речь пойдет ниже.

  • Параметр договора - как следует из названия, значение переменной данного типа берется из параметра договора. Для этого необходимо выбрать тип параметра договора и непосредственно сам параметр.

  • Дата - значение переменной данного типа можно выбрать из календаря (статическая дата, например, дата принятия устава), либо выбрать одно из предустановленных значений получения даты (динамическая дата. Возможные варианты: текущая дата, дата создания договора). Для переменной типа дата возможно ввести формат даты, который отформатирует дату требуемым образом. Подробнее о форматах дат см. SimpleDateFormat.

  • URL - предполагается, что значение переменной данного типа расположено на каком-то удаленном узле;

  • SQL - получение значения переменной данного типа осуществляется путем выборки из БД с помощью SQL-запроса.

В переменных типа Константа возможны следующие макроподстановки:

  • ${contract_title} - название договора, для которого генерируется документ;

  • ${contract_comment} - комментарий договора;

  • ${current_user} - имя пользователя, который генерирует документ;

  • ${user_<userId>} - имя пользователя с кодом <userId>. Код пользователя можно посмотреть в редакторе пользователей биллинга (Сервис=>Администрирование=>Пользователи и права), выбрав интересующего пользователя в таблице и нажав комбинацию клавиш Ctrl+i.

В переменных типа SQL возможны следующие макроподстановки:

  • ${cid} - код договора, для которого генерируется документ.

Если в шаблоне документа задан динамический Java-класс, то значения, возвращаемые данным классом, имеют бОльший приоритет и перетирают значения одноименных переменных в списке переменных.

Динамический Java-класс реализует интерфейс ru.bitel.bgbilling.plugins.documents.server.bean.pattern.PatternDataExtractor, содержащий метод extractData( Connection con, int contractId, DocumentPattern pattern, DocumentType type, DocumentJournal journal, Map<String, String> apiMap ), который должен возвращать объект типа Map<String, String> - список переменных в формате "ключ=>значение переменной". Здесь в качестве ключа выступает название переменной, соответствующей переменной в файле шаблона документа.

Простой пример реализации метода extractData(Connection con):

public Map extractData( Connection con, int contractId, DocumentPattern pattern, DocumentType type, DocumentJournal journal, Map<String, String> apiMap ) throws BGException
{
  Map<String, String> result = new HashMap<String, String>();
  result.put("param1","value1");
  result.put("param2","value2");
  return result;
}

Если в файле шаблона документа есть таблицы, которые необходимо сгенерировать, то в редакторе шаблонов необходимо добавить соответствие между таблицей в файле шаблона и таблицей в шаблоне, создаваемом в клиенте биллинга. Это осуществляется на вкладке Таблицы редактора шаблонов путем нажатия кнопок Добавить , Редактировать и Удалить .

В представленном редакторе задается символьное имя таблицы, ее уникальный идентификатор в файле документа, метод получения данных и, соответствующее методу получения данных, значение для таблицы. На данный момент поддерживается 2 метода получения данных:

  • SQL - полученная SQL-запросом таблица как есть попадет в тело сгенерированного документа. В SQL-запросе возможно использование макроподстановки ${cid} - код договора, для которого производится генерация документа;

  • Динамический класс Java - класс на Java, который возвращает данные для генерируемой таблицы.

Для генерации содержимого таблицы необходимо в файле шаблона создать заголовок таблицы и первую строку-шаблон, содержащую образец форматирования текста и ячеек. В этой строке-шаблоне также необходимо прописать названия столбцов, которые будут выступать в качестве ключей при получении данных (только для метода получения данных - Динамический класс). Если названия столбцов не заданы, то используются названия по умолчанию (col1...colN). В методе получения данных SQL по умолчанию используется нотация col1...colN, следовательно, задавать названия столбцов не обязательно.

Следует отметить, что для поиска таблицы в тексте документ необходимо задать уникальный идентификатор, который должен соответствовать идентификатору, заданному в редакторе таблицы клиента биллинга. Этот идентификатор можно поместить в любую ячейку таблицы, но рекомендуется поместить ее в самую первую ячейку заголовка - потребуется меньше времени для поиска нужной таблицы. Формат идентификатора соответствует формату переменных в шаблоне - {уникальный_идентификатор} . В редакторе таблиц этот уникальный идентификатор должен быть без фигурных скобок.

Динамический класс должен реализовывать интерфейс ru.bitel.bgbilling.plugins.documents.server.bean.pattern.TableDataExtractor и метод extractData( Connection con, int contractId, List<Map<String, String>> apiRowList ), который возвращает List<Map<String, String>>, т.е. список строк и содержимое столбцов в виде "ключ->значение". В качестве ключа выступает название столбца в строке-шаблоне.

Замечения:

  1. Рекомендуется использовать в качества шаблона документа файл Microsoft Office с расширением docx.

  2. При использовании в качества шаблона документа файл с расширением odt необходимо, чтобы на сервере был установлен пакет LibreOffice. Также необходимо учитывать, что при использовании данного формата файла возможно искажение форматирования документа из-за преобразований форматов (при генерации odt-файл преобразуется в docx).

  3. При использовании в качестве шаблона документа файл с расширением xlsx будет производиться подстановка ТОЛЬКО переменных в таблице на всех листах книги.

Для генерации документа необходимо открыть договор, для которого требуется сгенерировать документ по шаблону, выбрать вкладку Документы, выбрать Шаблон документа из выпадающего списка, Тип генерируемого документа и Журнал и нажать кнопку Сгенерировать. Сгенерированный документ появится в списке документов договора.

5. Web-Интерфейс

В Web-интерфейсе клиент может посмотреть все связанные с ним документы в меню Документы и загрузить все версии.

Любую версию документа клиент может загрузить себе.

Глава 46. Плагин HelpDesk

1. Назначение плагина

Плагин предназначен для работы с клиентами через Web. Клиент в случае возникновения проблемы пишет на сервере статистики (которая может быть доступна ему даже, если у него нет счета ). По запросу клиента создаётся отдельное сообщение и в дальнейшем вся переписка с клиентом по этой проблеме идёт в рамках этого сообщения. Клиент может вести обсуждение с провайдером, прикреплять файлы к обсуждению.

2. Алгоритм работы

Пользователь заходит на страницу статистики и может создавать новую тему, может оставить сообщение в одну из созданных им тем . Пользователь видит только те, темы, которое созданы от его имени . Провайдер ведёт обсуждение с пользователем.

Активные темы - темы на которые не было ответов со стороны провайдера.

Закрытые темы - темы, по которым обсуждение уже завершено.

Новые темы - темы , которые не помечены как прочитанные.

Менеджеры могут просматривать сообщения от пользователей и отвечать на них . Менеджер может назначить себя ответственным за конкретную тему.

Информация о новых темах и сообщениях рассылается на почту провайдера . Оповещения о новых сообщениях от менеджеров приходят на почту клиента.

Темы могут автоматически закрываться по прошествии некоторого периода.

Опционально можно включить поддержку платных обращений. Она реализуется в пакетном режиме. Пакет - это некоторый набор обращений на определённый срок. Указывается стоимость пакета . Клиент через Web-интерфейс может активировать определённый пакет, если у него на счёте достаточно средств для оплаты этого пакета . При этом ему начисляется расход, равный стоимости пакета .

3. Установка и настройка плагина

Плагин устанавливается стандартным образом. В настройках плагина (Плагины->HelpDesk->Конфигурация ) задайте конфигурацию :

# папка для хранения вложенных файлов
file.storage.root.path=/home/bill/BGBillingServer/filestorage/helpdesk
# Список режимов для договоров
mode.list=off:выключено;on:включено;package:пакетный
# Режим по умолчанию
mode.default.id=on
# Проверка на присутствие статуса при закрытии темы (не действует, если у договора пакетный режим): 0 - не проверять, 1 - проверять
state.mode=0
# режим по умолчанию: 0 - отключено; 1 - по телефону; 2 - по e-mail
default.comm.mode=0
# доступность режима оповещения по телефону (true/false)
default.comm.phone.enable=false
# доступность режима оповещения по e-mail (true/false)
default.comm.email.enable=true
# Тема письма с оповещением
default.comm.email.subject=HelpDesk => Опубликован ответ на Ваше сообщение в теме: [{id}] {title}
# Параметр "Закрывать автоматически" по умолчанию при открытии темы (true - да, false - нет)
topic.avto.closed.default=false
# наименование пункта меню в Web-интерфейсе (опционально)
web.menuItem1=HelpDesk
# код расхода, начисляемого пользователю в непакетном режиме
topic.charge.type.id=51
# шаблон комментария для расхода по обращению в непакетном режиме
topic.default.comment=Работы по обращению номер {topicId}
# стоимость обращения по умолчанию в непакетном режиме
topic.default.cost=2000.0

Для рассылки оповещений нужно настроить задачу планировщика "Рассылка уведомлений о приходе новых сообщений" для менеджеров. В параметрах запуска задачи надо указать:

#адрес провайдера
mail.to=billing@zzz.ru
#шаблон номера договоров, если его задать, то будут присылаться только сообщения из договоров, удовлетворяющих этому шаблону 
#contract.title.regexp=
#битовая маска группы договоров, если её задать, то будут присылаться только сообщения из договоров, принадлежащих этим группам
#contract.group.mask=
# тема сообщений о приходе новых сообщений в helpdesk
mail.subject=HelpDesk => Не отвеченные сообщений  -  {countAll}/{countDay}/{countHour} (всего/сегодня/за час)
# текст сообщения о приходе новых сообщений в helpdesk
mail.body={countAll} - всего не отвеченных\n{countDay} - новых сообщений за сегодня\n{countHour} - новых сообщений за последний час

Для автоматического закрытия старых тем, на которые нет ответов менеджеров, нужно настроить задачу "Автозакрытие тем через заданный интервал". Параметры запуска это задачи :

# через сколько дней после последнего сообщения от пользователя закрывать тему в случае отсутствия сообщений от клиента
topic.avto.closed.period=5
#куда слать оповещение о закрытых темах 
mail.to=billing@zzz.ru

Для рассылки персональных оповещений надо настроить задачу "Рассылка персональных уведомлений о новых сообщениях", она позволяет настроить для каждого менеджера уведомления на e-mail и/или на jabber о появлении новых ответов в его теме, а также в темах, которые ещё не закреплены за менеджером. Пример конфигурации:

# В конфигурации задачи можно ставить параметры (шаблоны):
mail.body=Ваши темы:\n{youNews}\nНичейные:\n{unmanagedNews}
mail.subject=HelpDesk => {youCountAll} новых сообщений (и {unmanagedCountAll} новых ничейных)
mail.bodypart={title} (ID {id}) - {count} новых\n

# В конфигурации задачи нужно ставить параметр - каким пользователям и куда слать.
user.dimon.mail=dimon@mail.ru
user.dimon.jid=dimon@jabber.ru
user.test1.mail=test1@bitel.ru
user.test2.jid=test2@jabber.ru

Для того, чтобы работали оповещения на jabber, в конфигурации СЕРВЕРА должны быть прописаны данные jabber-аккаунта (бота), например:

# Параметры jabber
# логин@сервер/ресурс
jabber.jid=bgbilling@jabber.***.ru/helpdesk
# пароль
jabber.password=***

Также есть "Рассылка персональных уведомлений о новых сообщениях" и у клиентов. При выборе уведомления по e-mail в конфигурации плагина следует добавить url сервера биллинга, чтобы в письмо добавлялась ссылка на топик. Пример конфигурации:

url.reference.topic=http://localhost:9580/bgbilling/webexecuter?

4. Работа с сообщениями

Для работы с сообщениями клиентов надо открыть вкладку Плагины->Helpdesk->Сообщения:

Здесь вы может просмотреть все темы, созданные пользователями. Кнопка Активные - фильтрация активных тем. Архив - закрытые темы . Только новые - новые сообщения. Незанятые - выводит темы, которые на связаны с менеджером . Мои - сообщения текущего менеджера. Кнопка Расширенный открывает дополнительный фильтр тем по ID, названию, содержанию сообщений, дате и статусу.

При двойном клике на теме открывается договор , там уже показаны только темы данного договора:

Двойным кликом на теме открывается редактор этой темы. Там отображается уже список сообщений внутри это темы. Двойным кликом на конкретном сообщении можно открыть его для просмотра:

Здесь можно менять состояние темы - открыта/закртыта . Можно установить себя менеджером данной темы. Можно установить дополнительный статус темы. Статусы выбираются из справочника "Helpdesk - Статус тем". При использовании пакетного режима обращений можно указать входит ли данная тема в пакет. Так же можно указать закрывается или нет данная тема автоматически. При просмотре конкретного сообщения можно на него ответить, есть возможность прикреплять файлы к своему сообщению и скачивать файлы.

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

5. Работа с пакетами обращений

Для просмотра пакетов надо открыть вкладку Плагины->Helpdesk->Пакеты:

Здесь создаётся пакет , для которого задаётся период его действия, его стоимость, количество обращений, которое входит в данный пакет, тип расхода (тут можно выбирать из нередактируемых типов расходов, заданных в справочнике ). Статус - может ли клиент использовать данный пакет.

6. Web-интерфейс клиента

На сайте статистки клиент выбирает helpdesk. Там по умолчанию ему показываются активные сообщения :

С помощью кнопки "Новая тема" клиент может добавить новую тему . Кнопка "Активные" - отображает активные темы, "Архив" - закрытые темы.

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

Клиент может выбрать одну из уже созданных тем и увидеть переписку по ней :

С этой же страницы он может посылать новые сообщения в текущую тему .

При выборе "Параметры" клиент может задать то, как он будет получать уведомления о новых сообщениях :

"Пакеты" :

Здесь можно увидеть активированные пакеты и пакеты, которые клиент сам может себе активировать.

Глава 47. Плагин Organizer

1. Назначение плагина

Часто возникают ситуации планирования задач непосредственно внутри биллинга. Особенно затруднительно помнить о необходимости выполнения каких-либо действий через достаточно большой промежуток времени (месяц, квартал, код). Например, действие договора было приостановлено по просьбе клиента, и, в случае, если клиент самостоятельно не сообщит о необходимости возобновления договора в течение двух месяцев, необходимо закрыть договор. Для планирования таких (или подобных) задач внутри клиента биллинга можно воспользоваться плагином Organizer.

2. Настройка плагина

В конфигурации плагина можно указать временной диапазон (в годах), который будет отображаться в календарном дереве (см. далее) при поиске заданий и при просмотре журнала заданий.

calendar.year.from=<год начала>
calendar.year.to=<год конца>

Здесь <год начала> и <год конца> - это годы (например, 2009 и 2011 соответственно).

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

3. Использование плагина

3.1. Общий обзор

Основная сущность, с которой работает плагин, - это задание. Задание - это некоторое предписание конкретному пользователю биллинга или целой группе пользователей со ссылкой на некоторый договор или без неё, которое необходимо выполнить в установленные сроки. Задания могут, фактически, иметь четыре статуса:

  • не наступили сроки выполнение задания - это означает, что задание уже создано в системе, но период его выполнения ещё не наступил;

  • к выполнению - это означает, что задание создано, и наступил срок выполнения этого задания;

  • просрочено - это означает, что время выполнения задания уже истекло;

  • выполнено.

Ответственность за корректное выполнение заданий целиком лежит на самих пользователях. Только пользователь, выполнивший (по его мнению) задание, решает - помечать ли его как выполненное. К слову, выполнять задания могут и пользователи, которым изначально они не были предписаны. Выполненные же задания можно вновь помечать как невыполненные. При каждом снятии или установке пометки о выполнении задания в журнал заданий заносится соответствующая запись. Это позволяет отслеживать историю задания, а также попытки "переоформить" выполнение задания на себя.

Как уже было сказано выше, основными характеристиками задания являются непосредственно текст задания, назначение некоторому пользователю или группе пользователей, сроки выполнения, а также договор, с которым связано задание. Например, если нужно будет выполнить какие-либо действия с некоторым договором, то сразу после прочтения текста задания можно перейти во вкладку этого договора.

Основное окно плагина находится во вкладке Плагины->Органайзер.

Здесь расположены три вкладки: Текущие, Поиск и Журнал. Вкладка Текущие позволяет просмотреть задания, время выполнения которых уже наступило (в том числе и просроченные задания). Вкладка Поиск позволяет искать задания (как выполненные, так и невыполненные) по различным критериям. Вкладка Журнал отображает журнал изменения заданий. Данный функционал более подробно будет рассмотрен ниже.

В статусной панели клиента биллинга при включении плагина появляются кнопка "+" (добавить новое задание) и кнопка, уведомляющая пользователя о текущем состоянии назначенных ему заданий (в случае, если на данный момент отсутствуют задания, необходимые к выполнению или просроченные, то кнопка скрыта).

3.2. Добавление задания

Создать новое задание можно двумя способами:

  • нажатием на кнопку +;

  • нажатием на кнопку "Добавить", находясь во вкладках Текущие или Поиск.

Замечание

Полезное примечание: если нажать на кнопку "+" находясь непосредственно на вкладке некоторого договора, то он автоматически добавиться в поле связанного с заданием договора.

В обоих случаях откроется Редактор задания.

Здесь Тема - краткое описание задания, Комментарий - полное описание задания, Договор - связанный с заданием договор (для добавление договора в это поле откройте вкладку этого договора, а затем нажмите на кнопку >>>), Кому назначено - пользователь или группа, которой (которому) назначено задание, Период - соответственно, период выполнения, и Статус - это метка о статусе договора.

После заполнения необходимых полей нажмите на кнопку ОК. Создать сразу выполненное задание нельзя.

3.3. Просмотр текущих заданий

Для просмотра текущих заданий необходимо зайти в меню Плагины->Органайзер, либо, в случае имеющихся к выполнению заданий, нажать на кнопку текущих заданий в статусной панели клиента.

Выбирая соответствующие условия показа заданий, можно просматривать как свои, так и чужие задания со статусом к выполнению, просроченные, либо и те, и другие.

Переход к договору, с которым связано задание, осуществляется выбором соответствующей опции в меню, открывающемся щелчком правой клавишей мыши по заданию.

3.4. Поиск заданий

Для поиска заданий по различным критериям необходимо перейти во вкладку Поиск. Поиск можно осуществлять по периоду, назначенному для выполнения задания, по времени непосредственного выполнения задания, по ID, по тексту внутри темы или развёрнутого сообщения, по пользователям (группам), которым предписано задание, а также по признаку выполненности и по пользователям, выполнившим задание.

1 - ID задания, 2 - текст внутри темы или комментария к заданию, 3 - кому задание было назначено, 4 - признак выполненности, 5 - пользователь, выполнивший задание, 6 - период, когда задание было выполнено, 7 - период, на который было назначено выполнение задания. 8 - календарное дерево, выбор месяца, года или всех годов автоматически заполняет поле 7.

3.5. Выполнение заданий

Ответственность за фактическое исполнение заданий лежит на самих пользователях, система только лишь распределяет задания, но не контролирует реальные его цель и статус. Для того, чтобы пометить задание как выполненное, необходимо дважды щёлкнуть на нем в списке заданий (либо выбрать его в таблице и нажать на кнопку Редактировать).

В открывшемся редакторе необходимо отметить задание как Выполненное, нажав соответствующую кнопку, и подтвердить изменения, нажав кнопку ОК.

Также можно присвоить выполнение задания себе (например, если задание выдано не конкретному человеку, а группе пользователей, то можно взять его выполнение на себя). Для этого необходимо нажать кнопку Назначить себе и подтвердить изменения, нажав кнопку ОК.

3.6. Журнал

Для просмотра журнала истории заданий необходимо открыть вкладку Журнал. Аналогично поиску заданий, здесь можно воспользоваться календарным деревом для поиска записей в журнале по периоду. Также можно искать записи в журнале для конкретного пользователя.

Глава 48. Плагин SBPilot

1. Назначение плагина

Плагин предназначен для интеграции с терминалами сбербанка через систему/утилиты sb_pilot для приёма оплаты через банковские карты на рабочих местах кассиров.

2. Структура и настройка плагина

Плагин, по большей части, работает на клиентской стороне. Взаимодействие с терминалами производится через утилиты и настройки сбербанка на компьютере, где установлен клиент биллинга (рабочее место кассира). Серверная часть плагина используется для ведения истории платежей. Работа осуществляется через обращение к утилите через командную строку. Путь до неё на текущем локальном компьютере и до файлов, которые она генерирует, прописываются в настройках. Основная конфигурация производится в файле настройки клиента биллинга (файл client[_ru_RU].properties):

# полный путь до утилиты sb_pilot (под linux или windows), который принимает параметры согласно протокола
# или же любой бинарник/скрипт его заменяющий
#sbpilot.path.bin=/home/bill/sb-pilot/sb_pilot
#sbpilot.path.bin=C:\sb-pilot\SB_PILOT.EXE
sbpilot.path.bin=/home/bill/sb-pilot/dowindow.sh
# полные пути до файлов e и p, которые создаются утилитой (см.документацию по системе sb_pilot)
sbpilot.path.e=/home/bill/sb-pilot/e
sbpilot.path.p=/home/bill/sb-pilot/cheque.txt
# коннектор к серверу печати, для печати чека
sbpilot.cashcheckserver.connector=127.0.0.1:9876
# пароль оператора к устройству для печати текста
sbpilot.cashcheckserver.oppass=30
# включить принудительную отрезку чека в конце
sbpilot.cashcheckserver.endcut=1

Для распечатки чека используется сервер печати cashcheck. Необходимо установить и настроить его согласно инструкции, приведённой в соответствующем разделе.

Замечание

Необходим лишь сервер печати — приложение BGCashcheckServer. Сам плагин cashcheck устанавливать не нужно, если вы не собираетесь использовать его функционал.

3. Настройка утилиты sb_pilot

Настройка утилиты производится сотрудниками сбербанка и в данном руководстве не рассматривается. Помимо настройки связи с банком необходимо уточнить в какие места и под каким именем сохраняются выходные файлы (см. настройку в клиенте). Также нужно попросить настроить ширину генерируемого чека в соответствии с шириной ленты в используемом вами принтере чека. Для Linux имена файлов обычно e и cheque.txt, для windows — e и p.

3.1. Донастройка в Linux

Используется консольная linux-версия утилиты. Для справки: в каталоге этой версии программы находятся файлы sb_pilot, config, upnixmn.out и прочие.

Необходимость донастройки заключается в том, что утилита работает в архаичной однобайтовой кодировке koi8-r. Потому для корректного отображения окна с приглашением ввода карты, меню и т.д. потребуется обернуть вызов утилиты в скрипт, который установит текущую локаль, шрифты, а также, при желании, размер окна, расположение, заголовок и т.п.. Предпочтительнее использовать именно скрипт вместо прописывания длинной строки запуска в параметре sbpilot.path.bin.

Скрипт можно написать совершенно любой под любой эмулятор терминала. Суть скрипта заключается в том, чтобы корректно отобразить на экране утилиту sb_pilot. Окно должно ожидать завершения каких-либо действий, а после завершения работы утилиты — закрываться. Также скрипт должен передавать не менее четырёх параметров утилите sb_pilot, т.е. необходимы переменные $1 $2 $3 $4 в командной строке утилиты.

В линуксе при использовании gnome-terminal скрипт dowindow.sh может иметь, например, такой вид:

#!/bin/sh

export LANG=ru_RU.KOI8-R; gnome-terminal --disable-factory -e "/home/bill/sb-pilot/sb_pilot $1 $2 $3 $4" --hide-menubar -t "SB-Pilot" --working-directory=. --profile=sbpilot

В этом примере в профиле с названием sbpilot (см. настройки терминала) можно указать любые размеры и цвета окна терминала.

При использовании эмулятора терминала xterm:

#!/bin/sh

export LANG=ru_RU.KOI8-R; export LC_ALL=ru_RU.KOI8-R; xterm -T SbPilot -fn -misc-*-*-*-*-*-13-*-*-*-*-*-koi8-r -e "/home/bill/sb-pilot/sb_pilot $1 $2 $3 $4"

В данном случае для отображения кириллических символов, псевдографики и т. д. в xterm в системе должны быть установлены соответствующие шрифты xorg-x11-fonts-misc , например, или/и xorg-x11-fonts-cyrillic или, возможно, пакеты с другим названием для вашей системы. Установка и настройка отображения кириллических koi8-r шрифтов в вашей системе выходит за рамки этого руководства.

Под эмулятор терминала kde не получилось написать корректный скрипт, выполняющий вышеобозначенные требования (при вызове из стороннего приложения окно закрывается сразу).

3.2. Донастройка в windows

Используется консольная win32-версия (иногда она называется у сотрудников сбербанка почему-то DOS). Работа происходит через командную строку, аналогичную командной строке linux-версии. Для справки: в каталоге этой версии программы находятся файлы SB_PILOT.EXE, pinpad.ini, updoscf.exe и прочие. Некоторая настройка также необходима для указания рабочих каталогов. Файл dowindow.bat может выглядеть так:

start /d c:\dos /wait c:\dos\sb_pilot.exe %1 %2 %3 %4

, либо каким-то другим образом. При этом обратите внимание на корректное указание рабочего каталога утилиты, без этого она не будет корректно работать (ищет свои файлы около себя) и файлы выходные тоже потеряются (пишет тоже в рабочий каталог). Кодировка выходных файлов — cp866.

После этого не забудьте прописать в файле client.properties полные пути до файлов dowindow.bat, e, p.

Имеются данные, что конкретно эта утилита не работает корректно в 64-битной версии windows.

4. Использование плагина

При установке и активации плагина в диалоге добавления платежа появляется галка "принять оплату по карте".

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

После завершения работы утилиты успешно или же с ошибкой диалог можно закрыть.

На второй вкладке "Log" можно увидеть более подробную информацию о взаимодействии с утилитой. Если работа была завершена с ошибкой, то платёж не совершается и мы по-прежнему имеем дело с диалогом добавления платежа. Если оплата проведена успешно, то платёж совершается, диалог закрывается, в историю платежей заносится запись. В истории платежей (Плагины->SbPilot) также имеется возможность совершения дополнительных действий - отмены, повторы, некоторые отчёты итп.

Также обратите внимание на одну особенность: если пользоваться распределением средств на зависимых договорах (т.е. одним платежом инициировать занесение в разные договоры), то в логе припишется только к одному из платежей, а оплата и чек пробьётся на всю сумму изначального платежа.

Глава 49. Плагин Bonus

1. Назначение плагина

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

2. Бонусные приходы

Бонусные приходы можно просмотреть во вкладке "Бонус" в дереве вкладок договора. При выборе прихода в нижней таблице будут отображены все расходы, которые списали у данного прихода, если таковые имеются.

Для добавления бонусного платежа нажмите в режиме просмотра платежей кнопку Новый элемент на стандартной панели инструментов клиента биллинга. Необходимо выбрать сумму, тип платежа и промежуток времени, на который данный платеж будет активен.

Типы платежей предварительно добавляются в справочнике, доступном через пункт меню Справочники->Другие->Bonus-приходы

3. Бонусные расходы

Бонусные расходы можно просмотреть во вкладке "Бонус" в дереве вкладок договора при нажатии на кнопку "Расход". Расходы будут отображаться только за выбранный период, который устанавливается выше. При выборе расхода в нижней таблице будут отображены все приходы, у которых данный расход списал бонусы.

Бонусные расходы создаются только при создании расходов для договора. В клиенте для этого создается расход на некоторую сумму и выбирается пункт "Оплатить бонусами (макс %)" ( в скобках указывается максимальный процент от суммы расхода, который можно оплатить бонусами, который, в свою очередь, устанавливается в настройках плагина). После чего вводится сумма, которая будет оплачена бонусами. Данный пункт будет только при условии, что плагин включен у договора.

Создание расхода договора с бонуснми, возможно только на текущий день. И изменение, при редактировании, изначальной суммы или даты у расхода будет невозможно.

Также можно расходовать бонусы для активации тарифных опций в личном кабинете Web-статистики (подробности в разделе "Web-интерфейс клиента" ) и в клиенте биллинга.

Для просмотра подробностей бонусного расхода у расхода договора необходимо нажать правой кнопкой мыши по расходу и в выпадающем контекстном меню выбрать пункт "Бонусы" (при условии, что у него был бонусный расход). Строка "Итого" равна сумме реального расхода договора, строка "Скидка [бонусы]" равна сумме скидки в рублях (в скобках указывается сумма бонусного расхода), а строка "Сумма" - это начальная сумма, которая равна сумме скидки и расхода у договора. При этом поле скидка равна сумме бонусного расхода, деленному на текущий курс (поэтому важно этот курс не изменять, так как у расходов он не хранится).

4. Бонусный баланс

Бонусный баланс можно просмотреть во вкладке "Бонус" в дереве вкладок договора при нажатии на кнопку "Баланс".

В верхней таблице отображены все расходы и приходы (активные на выбранный момент времени), из которых образовался текущий баланс. Изменив дату, можно просмотреть баланс на конкретное число. В нижней таблице отображены приходы, которые еще не активны(то есть они будут доступны для оплаты в будущем) и чуть ниже поле "Ожидаемые баллы", равное сумме этих приходов. При этом данная таблица не зависит от выбранный выше даты и отображает только текущее состояние неактивных платежей.

5. Бонусные программы

Бонусные программы позволяют начислять бонусные баллы. Изначально создается бонусная программа в плагине с заполненными параметрами ( Плагины->Bonus ), затем она может быть добавлена к конкретному договору.

Бонусные программы обладают, как минимум, следующими параметрами:

Название - символьное обозначение программы;

Тип программы - один из возможных типов бонусных программ;

Период - период, в течение которого будет учитываться данная программа и можно будет добавить программу к договору. Как минимум должна быть дата начала, а дата закрытия может быть открытой;

Тип бонусного прихода - предварительно созданный бонусный тип прихода(Справочники->Другие->Bonus-приходы);

Момент активации - устанавливает начало действия бонусного прихода; имеет следующие возможные значения:

  1. день - конкретный календарный день; если на момент начисления бонусов дата будет прошедшей, то установится датой начисления;

  2. кол-во дней - кол-во дней, через которое данными бонусными баллами можно будет воспользоваться для оплаты(с момента начисления бонусов); если оставить пустым ,то будет считаться равным 0 (будут активны сразу после начисления);

  3. начало недели - с начала следующей недели;

  4. начало месяца - с начала следующего месяца;

  5. начало года - с начала следующего года.

Завершение периода - устанавливает момент завершения действия бонусного прихода. Для всех значений, кроме первого, считается относительно момента активации. Имеет следующие возможные значения:

  1. день - конкретный календарный день; если на момент начисления бонусов дата будет прошедшей, то установится датой начисления(что приводит к тому, что срок действия бонусов = 0);

  2. кол-во дней - кол-во дней, в течении которого можно будет воспользоваться данными бонусами; если оставить пустым, то будет считаться равным 0 (будут активны только в день начисления);

  3. конец недели - до конца недели;

  4. конец месяца - до конца месяца;

  5. конец года - до конца года.

При добавлении программы к договору необходимо также выставить период действия для договора. Он может как дублировать период действия самой программы так и сужать его, либо не ограничивать дату завершения (в этом случае ограничением будет служить дата завершения программы, которую проще редактировать, чем у всех договоров с данной программой).

5.1. Операционная программа

Данная бонусная программа позволяет начислять бонусные баллы за приходы, расходы и наработку.

Для работы программы необходимо добавить задачу планировщика (Сервис->Администрирование->Планировщик заданий) "Bonus => начисление бонусов" и настроить ее запуск на каждый день в удобное вам время. Если параметр "Период начисления" будет выбран "моментальный", то наличие задачи не обязательно.

Операционная программа имеет следующие параметры:

Тип операции - приход, расход или наработка;

Период начисления - имеет следующие возможные значения: ежедневный - начисление бонусов за каждый день; месячный - за каждый календарный месяц; периодический - за произвольное количество дней; моментальный - начисление бонусов в момент прихода или расхода. Параметр для приходов и расходов;

Дни - параметр заполняется, если "Период начисления" имеет значение месячный или периодический. Для месячного - это день месяца, в который будет происходить начисление бонусов за предыдущий календарный месяц. Для периодического - это количество дней, за которое будут начислены бонусы;

Минимальная сумма операции - если сумма конкретной операции будет меньше выставленной в данном параметре суммы, то данная операция не будет учитываться;

Минимальная сумма за период - если сумма всех учтенных операций будет меньше выставленной в данном параметре суммы, то начисление бонусов не произойдет. Также этот параметр имеет значение шага в следующем параметре;

Тип начисления бонусов - имеет следующие возможные значения: процентный - начисляемая сумма равна проценту от учтенной суммы, умноженную на бонусный курс; абсолютный - сумма бонусных баллов, которое будет зачислено; пошаговый - сумма бонусов равна значению от деления без остатка суммы всех учтенных операций на минимальную сумму за период и умноженную на значение данного параметра (Пример: минимальная сумма за период = 300, сумма за период вышла = 1499, значение параметра = 500. В результате будет начислено 2000 бонусов); произвольный - сумма зачисления зависит от того в какой интервал попала сумма операции (Пример. значение параметра = " 300-1200, 400-1250,450-1800 ", сумма за период вышла = 434. В результате будет начислено 1250 ). Первым значением идет сумма учтенных операций, второй - сумма баллов.

ID операций - коды приходов, расходов или коды услуг для наработки через запятую, которые будут учитываться. Можно оставить пустым, тогда будут учитываться все операции.

5.2. Динамические программы

Динамические программы - это бонусные программы логика реализации которых основана на динамических Java классах. То есть, если вы хотите свой тип бонусной программы, то самым простым способом будет - это реализовать ее через динамические программы.

Для наглядности сейчас будет описан пример создания ДБП. Допустим нам нужна ДБП которая будет на каждый приход договора начислять бонусы, причем начисление зависит от некоторого коэффициента, который будет зависеть от кол-ва лет с момента создания договора, и начисление бонусов будем совершать только на первые два прихода сумма которых более 100р.

1) Создадим динамический класс и обязательно отнаследуем его от BonusProgramDynamicBase. Реализуем методы getTitle и accrualOfBonusImpl, первый соответственно возвращает название программы(оно будет отображаться в клиенте), а второй метод занимается начислением или/и расчетом некоторых значений(все зависет от ваших фантазий) для договоров. В нашем случае нам нужно реагировать на событие прихода платежа, потому мы еще переопределим метод onEvent.

Данный код можете использовать в качестве заготовки для вашего дин. кода( само собой изменив перед этим название класса и пакет ).

package ru.bitel.bgbilling.bonus.myPrograms;

import java.sql.Connection;
import java.sql.SQLException;

import ru.bitel.bgbilling.common.BGException;
import ru.bitel.bgbilling.kernel.event.Event;
import ru.bitel.bgbilling.plugins.bonus.common.bean.*;
import ru.bitel.bgbilling.server.util.Setup;
import ru.bitel.common.sql.ConnectionSet;

public class FirstProgram    extends BonusProgramDynamicBase
{
 @Override
 public String getTitle()
 {
  return "Первая программа";
 }

 @Override
 public void accrualOfBonusImpl( Connection con, BonusProgram program )     throws SQLException, BGException
 {
 }

 @Override
 public void onEvent( Event event, Setup setup, ConnectionSet set )     throws Exception
 {
 }

 @Override
 public List<String> getWebBonusStrings(Connection con, BonusContractProgram program )
 {
   return null;
 }

}

2) Далее заполним все методы, в результате у нас готовый дин. класс реализующий всю нашу логику. BonusProgramDynamicBase содержит основные методы для работы с бонусами, не забывайте ими пользоваться.

package ru.bitel.bgbilling.bonus.myPrograms;

import java.math.BigDecimal;
import java.sql.Connection;
import java.sql.SQLException;
import java.util.Calendar;
import java.util.Date;
import java.util.List;

import ru.bitel.bgbilling.common.BGException;
import ru.bitel.bgbilling.kernel.contract.api.common.bean.Contract;
import ru.bitel.bgbilling.kernel.contract.api.server.bean.ContractDao;
import ru.bitel.bgbilling.kernel.contract.balance.server.event.PaymentEvent;
import ru.bitel.bgbilling.kernel.event.Event;
import ru.bitel.bgbilling.kernel.module.common.bean.User;
import ru.bitel.bgbilling.plugins.bonus.common.bean.BonusContractProgram;
import ru.bitel.bgbilling.plugins.bonus.common.bean.BonusProgram;
import ru.bitel.bgbilling.plugins.bonus.common.bean.BonusProgramDynamicBase;
import ru.bitel.bgbilling.server.util.Setup;
import ru.bitel.common.Utils;
import ru.bitel.common.sql.ConnectionSet;
import bitel.billing.common.TimeUtils;

public class FirstProgram    extends BonusProgramDynamicBase
{
 @Override
 public String getTitle()
 {
  return "Первая программа";
 }

 @Override
 public void accrualOfBonusImpl( Connection con, BonusProgram program )     throws SQLException, BGException
 {
  Calendar now = Calendar.getInstance();
  // Производить расчеты будем только первого числа месяца. Это имеет смысл только если планировщик настроен на запуск каждый день.
  if( now.get( Calendar.DAY_OF_MONTH ) != 1 ) 
   return;
  
  ContractDao contractDao = new ContractDao( con, User.USER_SERVER );
  for( int contractId : bonusDao.getContractsOfThisProgram( program.getId(), new Date() ) )//пробегаемся по всем договорам с этой программой
  {
   if( !bonusDao.pluginInclude( contractId ) )// перед этим убедимся, что плагин у договора все еще включен.
   {
    continue;
   }
   map = bonusDao.getDataProgramOfContract( program.getId(), contractId );// инициализируем мап данными обрабатываемого договора.
   Contract contract = contractDao.get( contractId );
   // получим кол-во лет с момента действия договора( это не точный способ, так как високосные года не будут учтены, но думаю для примера пойдет )
   int year = TimeUtils.hourDelta( TimeUtils.convertDateToCalendar( contract.getDateFrom() ), Calendar.getInstance() ) / 24 / 365;
   int percent = 0;
   switch( year )// Тут мы выставляем процент. Более одного года = 5%, > 3 лет = 10%, > 5 лет = 15%
            {
    case 1:
     percent = 5;
     break;
    case 3:
     percent = 10;
     break;
    case 5:
     percent = 15;
     break;
   }
   if( percent > 0 )
   {// занесем посчитанный процент
    map.put( "percent", Integer.toString( percent ) );
   }
   map.put( "count", "0" );// обнулим месячный счетчик
   updateProgramData( program.getId(), contractId, map );// и сохраним изменения.
  }
 }

 @Override
 public void onEvent( Event event, Setup setup, ConnectionSet set )     throws Exception
 {
  // настоятельно рекомендую вызывать метод у родителя, в нем производятся некоторые установки.
  super.onEvent( event, setup, set );
  // Нас интересуют только события прихода платежа.
 if( event instanceof PaymentEvent && bonusDao.pluginInclude( event.getContractId() ) )
  {
   // получает все экземпляры программ
   List<BonusContractProgram> list = super.getContractPrograms( this.getClass(), new Date() );
   for( BonusContractProgram contractProgram : list )
   {
     BonusProgram program = contractProgram.getProgram();
     BigDecimal perc = Utils.parseBigDecimal( getParam( "percent", program.getId() ), BigDecimal.ZERO );
     int count = Utils.parseInt( getParam( "count", program.getId() ) );
     if( count < 3 && perc.compareTo( BigDecimal.ZERO ) == 1 )// Проверим чтобы кол-во начислений было меньше 3 раз.
     {
     // Получили сумму бонусов. Предупреждаю! Данная сумма получена без учета вашего курса бонус->валюта.
      BigDecimal sum = ((PaymentEvent)event).getPayment().getSum().multiply( perc.divide( new BigDecimal( 100 ) ) );
      updatePaymnent( sum, program );// И совершаем начисление бонусов.
      map.put( "count", Integer.toString( count + 1 ) );
      updateProgramData( program.getId() );// Увеличим счетчик кол-ва начислений и сохраним их.
     }
   }
  }
 }


  @Override
  public List<String> getWebBonusStrings(Connection con, BonusContractProgram program )
  { 
    ArrayList<String> list = new ArrayList<String>();
    contractId = program.getContractId();
    bonusDao = new BonusDao( con );
// Тут по желанию можно вывести данные, которое будут отображаться в ЛК.

    return list;
  }
}

3) Далее необходимо прописать параметр dinamicBonusPrograms( если не был прописан до этого ) в конфигураторе плагина( Плагины->Настройки ), а в качестве значения прописать полные имена ваших дин. классов используемых для дин. программ, через запятую. В нашем случае еще понадобиться наш класс повесить на событие прихода платежа( Сервис->Автоматизация->Функции скриптов поведения ).

В нашем случае оно будет имет следующий вид: dinamicBonusPrograms=ru.bitel.bgbilling.bonus.myPrograms.FirstProgram. Допустим если вы написали там же еще вторую дин. программу с названием SecondProgram, то параметр будет иметь следующий вид:dinamicBonusPrograms=ru.bitel.bgbilling.bonus.myPrograms.FirstProgram,ru.bitel.bgbilling.bonus.myPrograms.SecondProgram

4) Далее стандартным способом создаете бонусную программу, просто вместо операционного типа выберите ваш тип. Далее, так же стандартным способом, добавляете вашу программу на договора.

6. Настройка плагина

Плагин устанавливается стандартным образом. В настройках плагина (Сервис->Настройка Плагинов->Bonus ) задайте конфигурацию:

# Курс, rate = кол-во бонусов к одному рублю
rate=10
# Список кодов расходов договора, для которых установлен максимальный процент от суммы, который можно оплатить бонусами
charge=44,54,39,55
# и непосредственно сами значения для конкретных расходов
charge.percent.44=50
charge.percent.54=35
charge.percent.39=0
charge.percent.55=100
# Максимальный процент - значение по умолчанию
charge.percentDefault=20
# Ид тарифных опций которые можно оплатить только бонусами в web-e
tariffOptionsPaymentOnlyWithBonuses=10,3,5
# Дин программы
dinamicBonusPrograms=ru.bitel.bgbilling.bonus.myPrograms.FirstProgram,ru.bitel.bgbilling.bonus.myPrograms.SecondProgram

Например, пусть rate = 2 и создается расход на 100 рублей. Тогда максимальное количество бонусных баллов, которыми можно оплатить, равно 50.

Если код расхода не указан, то берется значение по умолчанию, если значение по умолчанию отсутствует, то будет возвращен 0 (то есть оплата бонусами будет запрещена).

Также необходимо настроить местоположение вкладки "Бонус" в дереве договора с ключом bonus в настройках сервера, если вы заводили данный параметр( иначе вкладка не будет отображаться в договоре).

client.gui.contract.tree.order=parameters objects hierarchy status limit mode face balance tariff modules groups web tariffGroup bonus script addAction memo 

7. Web-интерфейс клиента

На сайте статистики клиент выбирает пункт меню "Бонусы", где будет отображен его баланс и ожидаемые баллы (если токовые есть), а чуть ниже таблица, описывающая каким образом этот баланс был получен.

Для активации тарифных опций с использованием бонусов необходимо в тарифных опциях нажать на кнопку Активировать и, если тарифная опция не является бесплатной и бонусный баланс больше 0, то произойдет переход на страницу, где пользователю будет предложено оплатить часть расхода бонусами. Причем пользователю будет предложена максимально возможная сумма для оплаты бонусами, которая зависит от бонусного баланса и максимального процента для данного расхода.

В настройках плагина есть возможность указать тарифные опции которые можно оплатить только бонусами, для таких тар. опц. переход на страницу где будет предложено оплатить бонусами будет произведен, если у клиента достаточно для этого бонусов( причем не важно какой макс. процент у данного расхода, которым можно оплатить бонусами ), иначе будет выведено сообщение об ошибке.

8. Шаблоны договоров

В шаблоне договора можно указать автоматическое добавление бонусной программы и включение плагина при создании договора. Для включения плагина у договоров нужно установить галочку Включен. Для добавления бонусных программ выберите их из списка ниже (предварительно создав их через меню Плагины->Bonus ); в списке будут присутствовать только действующие на данный момент программы.

Если на момент создания договора бонусная программа будет не действующей (по истечению времени или по причине закрытия), то она не будет добавлена.

9. Групповые операции

На данный момент доступна только одна групповая операция: "Вкл/выкл плагина, добавление бонус. программ, установка периода программам".

Как следует из названия данная групповая операция позволяет включать/выключать плагин, добавлять бонусные программы и устанавливать период действия для них.

Для включения плагина у договоров нужно установить галочку Включен, для добавления бонусных программ первым делом установите период, а уже затем выберите программы из списка ниже (предварительно создав их через меню Плагины->Bonus ); в списке будут присутствовать только программы, удовлетворяющие периоду (добавление программ, дата закрытия которых уже прошла невозможно).