Настройка стандартных схем СОРМ

Skip to end of metadata
Go to start of metadata

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

Первичные настройки

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

Основные настройки для составления и выгрузки отчетов

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

Разделитель. Разделитель будет общим на все отчёты, которые будут созданы в рамках этой схемы. Пример разделителя ;(точка с запятой)

Формат даты. Формат даты будет общим для всех отчётов, которые будут создан в рамках это схемы. Он будет распространяться на все поля, которые можно распознать как дату.
Пример формата даты %Y-%m-%d %H:%M:%S
В данном случае:
%Y - год
%m - месяц
%d - день
%H - час
%M - минута
%S - секунда
Вы можете настроить любой формат даты, используя эти переменные

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

Кодировка. utf-8 или cp1251. Файлы, выгружаемые на ftp или доступные для скачивания будут иметь указанную кодировку. Кодировка распространяется на все отчёты.

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

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

Список отчётов

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

Архив отчётов

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

Отчёт в архиве можно только восстановить, изменить его без восстановления нельзя.

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

Настройки отчётов

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

Вкладка "Основные"

К основным относятся следующие:

  • Тип отчета - метод, которым будет сформирован отчет для выгрузки данных в СОРМ;
  • Название - Название отчета для отображения в веб-интерфейсе биллинга;
  • SQL запрос - поле предназначено для указания запроса к БД при формировании отчета (работает только с "Типом отчета" - SQL)

Различие типов отчета

Тип отчета Python Тип отчета SQL
  • Работает только для стандартных схем интеграции с СОРМ, представленных в биллинге;
  • Не подлежит модификации пользователем, только через запрос к CarbonSoft;
  • Работает только при условии, когда в начальных настройках указаны
    "схема интеграции" + "Название схемы". Если условие не выполняется - отчет не будет сформирован
  • Можно применить любой корректный запрос к БД;
  • Может редактироваться пользователем;
    Примеры отчетов
Внимание: при составлении SQL отчёта обязательно добавляйте последним полем уникальный ключ для этого отчёта. Уникальный ключ при этом может быть составным, например abonent_id:user_id c помощью операции конкатенации. Последнее поле никогда не будет выгружено в окончательной выгрузке и нужно только для того, чтобы в будущем формировать периодические выгрузки. Добавляйте уникальный ключ даже тогда, когда периодические выгрузки нужно выгружать всегда целиком или не нужно выгружать вообще, т.к. последнее поле всегда не будет попадать в выгрузку

Вкладка "Дополнительно"

  1. Генератор названий - Определяет, как именно будут названы файлы при выгрузке на ftp сервер. В генераторе названий доступны те же переменные, что и в формате даты. Переменные для формата даты в генераторе названий необязательны.
    Примечание: В генераторе названий формат даты обязательно указывайте между символами | и |

    Пример генератора названий: abonents-periodic-|%y%m%d_%H%M%S|.csv
    При такой настройке в название файла будет попадать время формирования файла в указанном формате. Для даты 2021-07-28 00:01:02 название файла будет abonents-periodic-20210728_000102.csv

  2. Папка на FTP - В этом поле необходимо указать путь до папки на FTP-сервере в которую необходимо выгружать отчёт. Если данной папки не существует на FTP-сервере - выгрузка провалится.
  3. Период выгрузки - Определяет интервал через который будет запускаться данный отчёт. Доступные периоды: ежечасно, ежедневно, только вручную.
  4. Формат периодичных отчётов - Определяет, в каком именно формате будут выгружаться периодичные отчёты, сформированные по указанному SQL шаблону.
    • Всегда целиком - Означает, что каждый периодический отчёт будет сформирован полностью по всем записям, которые попадут в SQL выборку
    • Только изменения - Означает, что в каждый периодический отчёт попадет только та запись, которая изменилась с предыдущей выгрузки.
  5. Заголовок - название столбцов в отчете. Составляется обязательно через точку с запятой. ВАЖНО! В каждом отчете есть служебное поле (KEY), оно необходимо для сравнения записей при выполнении периодических выгрузок, чтобы система могла различить актуальный отчет от предыдущего.
    Пример заголовка для отчета "ABONENT_USER"
    ABONENT_ID;REGION_ID;USER_NUMBER;USER_NAME;RECORD_ACTION;INTERNAL_ID1;KEY
  6. Промежуточное имя отчёта. Если в этом поле указано какое - либо значение, тогда загрузка на FTP будет проходить сначала с именем из поле "Промежуточное имя файла", после чего скрипт переименует этот же файл в имя из поля "Генератор отчёта". Данное поле предназначено для тех случаев, когда скрипты на стороне СОРМ слишком быстро обрабатывают файлы и их нужно сначала загрузить и потом переименовать.
  7. Специальный формат периодических отчетов - опция добавляет в отчет дополнительные строки для подробного отображения изменений в биллинге по записям.
    ВАЖНО! Для каждой схемы эта опция работает по-разному. Использовать только для стандартных отчётов биллинга, сформированных на основе стандартных схем, а также включена по умолчанию у некоторых встроенных отчетах.
    Пример работы опции при формировании отчета по схеме "Специальные технологии"
    Для отчёта abonents будет сформировано 3 строки по каждому абоненту, если у него редактировали данные с момента предыдущей выгрузки.

    1. Неактуальная запись (old_string) с изменённым record action(30 поле), Record action установлен со значением 2 (означает удалить запись);
    2. Неактуальная запись (old_string), но в поле actual_to(6 поле) будет указана текущая дата, момент времени до которого запись была актуальна;
    3. Новая запись (new_string) в поле actual_from(5 поле) будет иметь текущую дату, с которой информация по абоненту актуальна.
  8. Строка с дополнительными параметрами - передаёт параметры в отчёт. Доступны:
    • translit_service_name - указывает переводить ли название услуги на транслит.
      translit_service_name=0
      
    • operator_code - указывает принадлежность IP адреса оператору связи в схеме VasExperts при совместом использовании СОРМ несколькими опреаторами.
      operator_code=2
      
    • exclude_abonents - позволяет исключить абонентов из выгрузки
      exclude_abonents=88,1374
      

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

Общая логика работы для периодической(регулярной) выгрузки

  1. Если это первая периодическая выгрузка и на биллинге нет данных о последней успешной выгрузке на FTP сервер - будут выгружены полностью все записи исходя из SQL запроса
  2. Если выгрузка на FTP прошла успешно - на биллинге будет сохранен выгруженный файл в директории /var/local/sorm/reports/abonents/actual/ где abonents - имя отчёта в веб интерфейсе.
    Внимание: В этой папке всегда должен быть только один файл, либо не должно быть файлов вообще. Если вы сохраните в эту директорию любой другой файл - выгрузка работать не будет!

    В этом файле последним полем будет указан уникальный ключ
    Пример записи из файла в папке actual:

    "1340";"BILL0000053";"Фролов Г. К.";"1340:1387"
    

    В данном случае "1340:1387" - это уникальный ключ. 1340 - id абонента, 1387 id учетной записи. Вся остальная часть до последнего разделителя это строка, которая относится к данному ключу. Именно строка будет попадать в конечную выгрузку без уникального ключа и последнего разделителя.

  3. Если происходит периодическая выгрузка и биллинг находит последний актуальный файл в папке с тем именем, которое указано у отчёта в качестве имени - начинается сравнение строк по ключам: биллинг смотрит текущий файл и последний актуальный и сравнивает строки с одинаковыми ключами друг с другом. Если в строках находятся изменения - текущая строка попадает в выгрузку. Если выгрузка на FTP проходит успешно - текущий актуальный файл заменяется.
    Внимание: Актуальный файл на биллинге меняется только для выгрузок на FTP и только в том случае, если выгрузка прошла успешно. При ручном скачивании в csv или при выводе в веб интерфейсе актуальный файл меняться на биллинге не будет!

Как выбрать уникальный ключ для отчёта.

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

  1. В отчёте abonents есть данные как об основных параметрах абонента(таблица abonents), так и о параметрах учетных записей(таблица users). Первым делом приходит на ум использовать в качестве уникального ключа просто id таблицы abonents. Однако это решение будет неверным, потому что у одного и того же абонента может быть несколько учетных записей и тогда в выборке будет несколько записей(строк), в которых ключ будет одинаковым. Это можно понять по связи модели users с abonents.
    Точно так же будет неверным использовать только id из таблицы users, потому что может быть такая ситуация, в которой у абонента нет ни одной учетной записи и таких абонентов будет несколько и в итоге в выборке будет несколько разных записей(строк), в которых будет одинаковый пустой ключ.
    В данном отчёте лучше всего подойдет составной ключ из этих двух таблиц, например abonent_id:user_id. Такой составной ключ можно добавить с помощью конкатенации и указать последним полем в отчёте следующую конструкцию:
    a.id || ':' || u.id
    

    Таким образом последнее поле в отчёте(уникальный ключ) будет составным и состоять из двух id разных таблиц, разделенных двоеточием, например "1340:1387". Такая связка будет гарантировать, что у каждой записи(строки) будет уникальный ключ.

Выгрузка данных

Ручной запуск отчётов

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

Перед запуском отчёта Вы сможете выбрать в каком именно формате необходимо запустить отчёт и за какой период.
Формат:

  • Выгрузить в формате csv - Выгружает локально на Вашу машину csv файл с указанными настройками и кодировкой.
  • Выгрузить на FTP - Выгружает файл на FTP сервер.
    Внимание: При успешной выгрузке файла на FTP сервер, на биллинге будет создан актуальный файл, с которым потом будет проходить сравнение в периодической выгрузке
  • Выполнить в веб - интерфейсе - Показывает информацию в виде таблице в веб - интерфейсе биллинга

Периодическая выгрузка отчетов

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

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


Далее, запустить выгрузку, нажав "Выполнить запрос"

Выгрузка pay_types (типы платежей)

Данная выгрузка формируется следующим образом:

  1. Добавляются типы платежей, обязательные для конкретного СОРМ
  2. Из таблицы БД FINANCE_OPERATIONS берутся уже существующие типы платежей по полю operator_name(SBERBANK_ACQ,Robokassa и т.д.), их id формируются автоматически.

Особенности отдельных СОРМ

У некоторых схем могут быть особые настройки, они описаны в отдельных статьях. Пожалуйста, обязателно ознакомьтесь со статьёй по интеграции СОРМ выбранного Вами поставщика:

Сброс настроек отчётов к стандартным

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

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

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

Переход от одного поставщика СОРМ к другому

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

Отладка

Проверить логи службы формирования отчетов вы можете в /app/asr_billing/var/log/sorm.log

Пример
2021-12-24 09:02:25,133 - worker - cron_sorm - INFO - Выполнен запуск отчёта ident_spec по крону. Результат: Выгрузка файла ABONENT_IDENT_20211224_0901.txt выполнена успешно.
2021-12-24 10:01:02,824 - worker - cron_sorm - INFO - Начинаем выгружать отчёт ident_spec по крону.
2021-12-24 10:01:02,825 - worker - cron_sorm - INFO - Начинаем выгружать отчёт ident_spec по крону.
2021-12-24 10:01:02,842 - worker - sorm_spec_tech - INFO - AbonentIdentReport: Запущена полная выгрузка
2021-12-24 10:01:02,846 - worker - sorm_spec_tech - INFO - AbonentIdentReport: Запущена полная выгрузка
2021-12-24 10:03:16,013 - worker - sorm_spec_tech - INFO - Выгрузка завершена
2021-12-24 10:03:16,064 - worker - sorm_spec_tech - INFO - Выгрузка завершена
2021-12-24 10:03:16,447 - worker - sorm_functions - INFO - Не найден абонент с ключом  19898:19635 в старом файле. Добавляем в новый файл без изменений
2021-12-24 10:03:16,448 - worker - sorm_functions - INFO - Отчёт abonent_ident. У абонента 11860 с учетной записью 11880 изменилось поле IPV4
Введите метки, чтобы добавить к этой странице:
Please wait 
Ищите метку? просто начните печатать.