Миграция абонентов из CSV файла

Skip to end of metadata
Go to start of metadata
Время выполнения инструкции: до 30 секунд на одного абонента и до 1 минуты инициализацию скрипта, общее время прямо зависит от количества мигрируемых абонентов

Пошаговая инструкция по миграции

CSV и конфигурационный файл должны быть в кодировке UTF-8. Расширение файлов .csv для файла с абонентами и .conf для файла с настройками.

1. Допустим csv файл выглядит в нашем случае вот так:

Фильчаков Андрей Петрович;33.1;Белгород;Ленина;3;1;115;89221100331;15J34;Безлимит512;10.0.0.8;AA:BB:CC:DD:11:22;по ip static
Иванов Павел Сидрович;22.5;Москва;Сталина;4;2;8;89991112233;HGJ34;Безлимит1024;192.168.31.5;11:22:33:44:55:66;по vpn pptp, pppoe
Козлов Роман Алексеевич;78.4;Омск;Хрущева;5;3;45;89123336677;B389D;Безлимит5120;172.25.3.7;11:AA:22:BB:33:CC;любая через RADIUS

В табличном виде вот так:

Фильчаков Андрей Петрович 33.1 Белгород Ленина 3 1 115 89221100331 15J34 Безлимит512 10.0.0.8 AA:BB:CC:DD:11:22 по ip static
Иванов Павел Сидрович 22.5 Москва Сталина 4 2 8 89991112233 HGJ34 Безлимит1024 192.168.31.5 11:22:33:44:55:66 по vpn pptp, pppoe
Козлов Роман Алексеевич 78.4 Омск Хрущева 5 3 45 89123336677 B389D Безлимит5120 172.25.3.7 11:AA:22:BB:33:CC любая через RADIUS

2. Создаем конфигурацию для вашего csv файла т.е какие поля из CSV соответствуют полям в бд биллинга. Первое поле в csv считается 0-вым. Далее в конфигурации Вы указываете имя поля в биллинге и значение столбца в csv файле, которое запишется в это поле биллинга

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

Пример конфига для нашего csv файла (описания столбцов не заканчивается запятой, она вызовет ошибку миграции).

{
    "fields": {
        "Название/ФИО": 0,
        "Баланс": 1,
        "Город": 2,
        "Улица": 3,
        "Номер дома": 4,
        "Корпус": 5,
        "Номер квартиры": 6,
        "Логин": 7,
        "imported_id": 7,
        "Номер договора": 7,
        "Номер SMS для оповещений": 7,
        "Сгенерированный пароль": 8,
        "Тариф": 9,
        "IPv4": 10,
        "MAC": 11,
        "Тип авторизации": 12
    },

    "options":{
        "Папка для импорта": "Миграция",
        "Разделитель csv": ";",
        "Формат даты": "%d.%m.%Y",
        "Наследовать параметры от родительской папки": "True",
        "Следующее списание": "16.07.2016",
        "Тип списания":"Предоплата",
        "Метод списания":"Ежемесячно равными долями в день"
    }
}
Обязательно прочтите описание полей ниже

imported_id - уникальный идентификатор записей в вашем CSV файле(ах) при миграции. Не может быть пустым!
Папка для импорта - имя папки в списке абонентов биллинга, в которую попадут все абоненты из csv-файла после миграции. Если требуется разделить абонентов на подпапки (по тарифам или по месту подключения), тогда до миграции необходимо произвести разделение общего csv-файла на отдельные файлы, в которых абоненты уже сгруппированы по нужному признаку. Также для каждого csv-файла нужен будет свой файл .conf, в котором поле "Папка для импорта" будет иметь соответствующее значение.
Названия остальных полей совпадают с их описанием в интерфейсе управления абонентами:

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

NAS/BRAS - к какому маршрутизатору требуется привязать учетную запись - писать текстом в CSV. Просто название NAS'а без IP в скобках. NAS предварительно должен быть создан в биллинге.

Тип авторизации - тип авторизации пользователей (общий для всех добавляемых пользователей)

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

Список типов авторизации:

по vpn pptp, pppoe
по ip static
по CarbonAgent
по ip+CarbonAgent
через веб
через ip+веб
любая через RADIUS

3. Копирование файлов на сервер.

  • IP адрес сервера биллинга 10.0.0.1
  • Файл конфигурации abonents.conf
  • CSV-файл с данными абонентов abonents.csv

Производим копирование программой scp

scp -P 22 abonents.conf abonents.csv root@10.0.0.1:/app/asr_billing/var/root/
Все файлы должны быть в кодировке utf-8, для проверки введите команду в консоли сервера
 file /app/asr_billing/var/root/abonents.csv
abonents.csv: UTF-8 Unicode text, with CRLF line terminators

Если в выводе Вы получите 'UTF-8 Unicode (with BOM)' выгрузка работать не будет.
Для исправление выполните команду.

sed -i '1s/^\xEF\xBB\xBF//' /app/asr_billing/var/root/abonents.csv

4. Заходим в контейнер биллнг

chroot /app/asr_billing

5. Запускаем скрипт миграции без параметров

python2.7 /usr/lib/python2.7/site-packages/carbon_migration_scripts/file_client/import_csv_v2.pyc

будет выведена инструкция к дальнейшим действиям.

6. Запускаем миграцию абонентов командой

python2.7 /usr/lib/python2.7/site-packages/carbon_migration_scripts/file_client/import_csv_v2.pyc /var/root/abonents.conf /var/root/abonents.csv migrate_abonents
Внимание: Первым аргументом обязательно нужно передавать конфигурационный файл, а вторым обязательно файл csv. Если поменять местами аргументы скрипт не заработает.

7. Проверяем миграцию

Логи миграции/Скорость миграции

Оценить скорость прохождения миграции, запущенной с другой машины, можно в логе миграции /var/log/import_csv.log

Разделы файла конфигурации

  • fields - содержит поля доступные для редактирования в карточке абонента, а также у учётной записи пользователя;
  • options - отвечает за параметры csv файла, такие как разделитель, дату следующего списания и тому подобное;
  • dynamic_attributes содержит список реквизитов, которые не были созданы в биллинге, при этом для каждого абонента будет создан отдельный реквизит.

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

Нужно отвязать процесс от терминала, и делается это сразу при запуске. Например:

setsid python2.7 import_csv_v2.pyc IntercomConverted.config.json IntercomConverted.csv migrate_abonents  2>&1  >import_csv_v2.`date +%Y-%m-%d_%H%M%S`.log & disown -a

Эта команда:

  • Позволит закрыть терминал и отключиться от сервера
  • Будет дублировать лог в папку, где Вы выполнили команду.
  • В названии лога укажет дату запуска миграции, например: import_csv_v2.2021-04-15_004551.log

    Список полей доступных для миграции абонентов

    • Практически все поля из веб - интерфейса можно мигрировать, указав в конфигурационном файле название поля так же, как оно написано в веб - интерфейсе.
    • В случае, если в названии поля присутствует обратный слэш - данный символ необходимо в конфигурационном файле экранировать. Пример:
      "Списать сумму\\Сделать скидку": 1
      
    • Максимальная длина пароля составляет 16 символов. Если пароль в csv файле будет длиннее - скрипт сгенерирует случайный пароль для этого абонента
    Внимательно используйте опцию "Создавать дополнительных пользователей c login=imported_id". Эта опция используется в скрипте с параметром create_users. С этой опцией в новую учетную запись не попадут никакие параметры кроме "Логин" .
{
    "fields": {
        "auth_type": 57,
        "OPT82": 56,
        "Метод списания абон.платы": 70,
        "Название/ФИО": 1,
        "Порог отключения": 2,
        "VLAN": 54,
        "Номер договора": 3,
        "Абонентка по тарифу": 71,
        "Название тарифа": 42,
        "rate_in": 49,
        "next_auto_acount": 68,
        "Добровольная блокировка, до": 21,
        "Логин": 2,
        "Номер дома": 35,
        "Номер квартиры": 37,
        "Корпус": 36,
        "iptv пароль": 64,
        "IP адрес для SNAT": 65,
        "порт коммутатора": 55,
        "Улица": 34,
        "Переход на тариф": 38,
        "Баланс": 9,
        "Дерево групп": 67,
        "IP коммутатора": 53,
        "Пул IP адресов": 27,
        "iptv ip": 62,
        "Номер SMS для оповещений": 11,
        "imported_id": 0,
        "У пользователя белый ip адрес": 22,
        "iptv мак": 63,
        "Host Пул (только для VPN)": 26,
        "Юр. лицо": 5,
        "send_act": 19,
        "NAS/BRAS": 58,
        "sync1c": 20,
        "Дата выставления Акта": 72,
        "ceil_in": 51,
        "ceil_out": 52,
        "Дата договора": 7,
        "rate_out": 50,
        "enabled": 6,
        "Переопределенная абонентская плата": 61,
        "email": 10,
        "Следующее списание": 69,
        "MAC": 8,
        "Host IP (только для VPN)": 25,
        "IPv4": 4,
        "Запретить динамическое выделение параметров": 23,
        "Формировать Акт автоматически": 12,
        "Город": 32,
        "Имя тарифа для перехода": 40,
        "Дата следующего перехода": 39,
        "Сгенерированный пароль": 15
    },
    "options": {
        "Формат даты": "%Y-%m-%d %H:%M:%S",
        "Метод списания": "Ежедневно",
        "Разделитель csv": ";",
        "Разделитель телефонов": " ",
        "Создавать дополнительных пользователей c login=imported_id": "True",
        "Наследовать параметры от родительской папки": "False",
        "Папка для импорта": "Миграция",
        "Тип списания": "Предоплата"
    },
    "dynamic_attributes": {
        "Главный бухгалтер": 87,
        "Кем выдан": 83,
        "Адрес оборудования": 80,
        "Наименование оборудования": 75,
        "Адрес": 73,
        "Когда выдан": 82,
        "Кто подключил": 77,
        "Мак адресс": 79,
        "Наименование": 85,
        "Прописка": 84,
        "Паспорт №": 81,
        "Номер порта": 76,
        "ИНН": 86,
        "Когда подключен (дата)": 78,
        "Телефон": 74
    }
}

Как мигрировать абоненту персональную стоимость услуги, не как у всех?

Укажите стоимость услуги в отдельном столбце, в конфигурационном файле в разделе fields укажите поле "Переопределенная абонентская плата".
В услугах абонента персональная стоимость будет указана в поле "Списать сумму/Сделать скидку" в настройках услуги)

Какой именно услуге тарифа будет назначена указанная стоимость?

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

  • Если услуга не одна - будет ошибка
  • Если нет ни одной - тоже ошибка

У абонента несколько IP-адресов, как их мигрировать?

Например, абонента Фильчаков Андрей Петрович три IP-адреса: 10.0.0.8, 10.0.0.9, 10.0.0.10.

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

Фильчаков Андрей Петрович;33.1;Белгород;Ленина;3;1;115;89221100331;15J34;Безлимит512;10.0.0.8;AA:BB:CC:DD:11:22;по ip static
Фильчаков Андрей Петрович;33.1;Белгород;Ленина;3;1;115;89221100331;15J34;Безлимит512;10.0.0.9;AA:BB:CC:DD:11:22;по ip static
Фильчаков Андрей Петрович;33.1;Белгород;Ленина;3;1;115;89221100331;15J34;Безлимит512;10.0.0.10;AA:BB:CC:DD:11:22;по ip static

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

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

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

На текущий момент данная возможность есть только в первой версии скрипта миграции

python2.7 /usr/lib/python2.7/site-packages/carbon_migration_scripts/file_client/import_csv.pyc

В биллинге нет полей для миграции нужных данных. Что делать?

Добавьте нужные данные в выгрузку. В конфигурационном файле укажите их в области "dynamic_attributes". Если каких-то полей нет, биллинг их создаст и отразит в карточке абонента на вкладке реквизиты.

Как сделать csv

Выгрузка запросом к базе данных

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

Из Excel

Если биллинг-источник позволяет выгрузить данные для миграции в Excel, можно воспользоваться им и пересохранить файл в CSV (меню Файл -> Сохранить как) или воспользоваться конвертером в интернете: https://convertio.co/ru/xls-csv/

Из XML

Можно воспользоваться конвертером в интернете: https://conversiontools.io/conversion/convert_xml_to_csv

Если есть CSV, но формат не совсем подходит (разделитеть, кавычки и тд)

Можно открыть файл с LibreOffice и пересохранить в нужном виде, но иногда он "ломает" даты и большие числа - например, номер банковского счёта из 16 цифр может укоротить, отразив в экспоненциальной форме (например 489089058900e17), и это испортит всю выгрузку.

Для решения, воспользуйтесь утилитой csvformat из пакета csvkit

Установить в Ubuntu 18.04 и выше можно так:

sudo apt update; sudo apt install -y csvkit

Преобразовать так:

csvformat -D '|' -Q '' -U 3 IntercomWorkbenchRaw.csv  | sed 's/NULL//g'  > IntercomConverted.csv

В качестве разделителя будет использован символ "|", все поля будут выгружены без кавычек, а поля "NULL" станут пустыми (такая проблема может быть в старых версиях MySQL Workbench).

Ошибки миграции

Попытка миграции абонента с тарифом, состоящим из одних цифр

ValueError: Cannot assign "1243": "Abonents.tarif" must be a "Tarif" instance.

Рекомендуем при миграции создавать тарифы хотя бы с одной буквой. Иначе могут возникнуть трудности при миграции.

Пропущен разделитель в конфигурационном файле

В примере пропущен разделитель "," на позиции 42 в конфигурационном файле. Сообщение об ошибке:

ERROR 2019-11-25 14:42:11,717 base 6929 140347412997888 [u'ValueError: Expecting , delimiter: line 42 column 1 (char 1326)', u'  File "file_client/import_csv.py", line 1612, in <module>', u'  File "file_client/import_csv.py", line 1564, in start_import', u'  File "json/__init__.py", line 339, in loads', u'  File "json/decoder.py", line 364, in decode', u'  File "json/decoder.py", line 380, in raw_decode']

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

delimiter: line 42

Для исправления конфигурационного файла откройте его в текстовом редакторе и перейдите на строку 42.

vim +42 /var/root/abonents.conf
Нумерация столбцов в .csv файле начинается с 0.

Конфигурационный файл содержит некорректные параметры

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

ERROR 2019-12-11 17:41:59,790 base 18056 140138050590464 [u'ValueError: Expecting property name: line 5 column 1 (char 71)', u' File "file_client/import_csv.py", line 1612, in <module>', u' File "file_client/import_csv.py", line 1564, in start_import', u' File "json/__init__.py", line 339, in loads', u' File "json/decoder.py", line 364, in decode', u' File "json/decoder.py", line 380, in raw_decode']
[u'sudo bash -c "export BOOTUP="noncolor";service worker start 2>&1"']

В указанном случае стояла запятая в конце перечисления параметров конфигурационного файла ("Номер договора": 1,)

"fields": {
"Баланс": 6,
"Номер договора": 1,
},
При перечислении в конфигурационном файле внутри { } используется символ запятая(,), как указатель на следующий параметр

Неверный тип параметра в конфигурационном файле

Пример ошибки:

ERROR 2019-11-25 19:24:36,818 base 31955 140598127302400 [u'TypeError: list indices must be integers, not unicode', u' File "file_client/import_csv.py", line 1612, in <module>', u' File "file_client/import_csv.py", line 1589, in start_import', u' File "file_client/import_csv.py", line 189, in start_import', u' File "file_client/import_csv.py", line 138, in parse_csv']

Ошибка возникает, когда в конфигурационном файле для параметра указано строковое значение вместо целочисленного. Например вместо номера столбца для тарифа указано его название:

"Тариф": "Основной тариф",

Верное значение поля "Тариф" - номер столбца в файле .csv , с названиями тарифов:

"Тариф": 8,
Введите метки, чтобы добавить к этой странице:
Please wait 
Ищите метку? просто начните печатать.