Bitrix Migration Tool

ЗМІСТ

CТОРІНКА ДОКУМЕНТАЦІЇ BITRIX MIGRATION TOOL

ПОСІБНИК КОРИСТУВАЧА

Версія 1.0

Травень 2023

Посилання для завантаження пакетів nuget та самотійного встановлення утіліти Bitrix Migration Tool: https://www.nuget.org/packages/IndiVision.BitrixMigrationTool

Додаткова інформація про утіліту та feedback можно залишити за поссиланням: https://www.xrmtoolbox.com/plugins/IndiVision.BitrixMigrationTool/

Відео інструкція до Bitrix Migration Tool – 1

Відео інструкція до Bitrix Migration Tool – 2

СКОРОЧЕННЯ ТА ПОЗНАЧЕННЯ

Bitrix Migration Tool (Застосунок) – застосунок для перенесення даних з хмарної CRM Bitrix 24 в базу даних Microsoft Dataverse.

Bitrix 24 (Bitrix) – хмарний сервіс, який надає набір інструментів для ведення бізнесу та побудови взаємодії з клієнтами; використовується для ведення бази даних клієнтів та зберігання інших важливих бізнес-даних.

Microsoft Dataverse (Dataverse) – хмарний сервіс для безпечного, динамічного та масштабованого збереження даних; бекенд для модель-орієнтованих додатків, включаючи лінійку готових додатків Microsoft Dynamics 365, таких як Dynamics 365 Sales, Dynamics 365 Customer Service, Dynamics 365 Field Service.

XrmToolBox – платформа для роботи з лінійкою продуктів Microsoft Dynamics 365, яка використовує механізм модулів, що підключаються або плагінів.

Атрибут – властивість, що описує окрему характеристику об’єкта; в термінології реляційних баз даних – це стовпець реляційної таблиці.

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

Сутність – об’єкт даних, або реляційна таблиця даних.

Зіставлення – індивідуальний зв’язок 1:1 між двома сутностями, атрибутами або наборами даних. Дані з однієї системи в іншу переносяться на основі встановлених зіставлень.


ЗАГАЛЬНІ ВІДОМОСТІ

Застосунок Bitrix Migration Tool призначений для міграції даних з хмарної CRM Bitrix 24 в базу даних Dataverse, яка використовується в лінійці продуктів Microsoft Dynamics 365.

Застосунок є плагіном до відомого фреймворку(платформи для плагінів) XrmToolBox та працює в контексті (та інтерфейсі користувача) цього фреймворка.

Весь базовий функціонал для підключення до цільової системи Dataverse та аутентифікації користувача надається на рівні XrmToolBox.

Взаємодія з вихідною системою Bitrix 24 заснована на використанні REST API з аутентифікацією за допомогою токена.

Облікові дані користувача Dataverse та ключ аутентифікації (зашифрований) для підключення до веб-сервісу Bitrix зберігаються на локальному комп’ютері користувача і ніколи не передаються ні до яких хмарних ресурсів.

Ключові особливості

   ✅ Забезпечення міграції даних ключових сутностей системи:

Назва сутностіІм’я сутності BitrixІм’я сутності Dataverse
Потенційний клієнт (Інтерес)LEADLead
КонтактCONTACTContact
ОрганізаціяCOMPANYAccount
Потенційна угодаDEALOpportunity
РахунокINVOICEInvoice
ПропозиціяQUOTEQuote
Телефоний викликACTIVITY CALLPhone Call
Електронна поштаACTIVITY EMAILEmail
ЗустрічACTIVITY MEETINGMeeting
ЗавданняACTIVITY TASKTask
ВалютаCURRENCYCurrency

  ✅  Забезпечення зручного інтерфейсу для генерації зіставлення атрибутів основних сутностей системи:

  • перегляд метаданих атрибута виділеної сутності;
  • швидкий пошук атрибута за логічним іменем або назвою;
  • розфарбовування за кольором в залежності від типу атрибута.
  • фільтрація атрибутів за типами;
  • генерація карти міграції атрибутів шляхом «перетягування» мишкою;
  • вбудована перевірка сумісності зіставлених атрибутів за типом.

 ✅  Зіставлення елементів наборів даних для атрибутів системи Bitrix (підтримуються типи атрибутів Crm status, Crm_enum_ownertype, Crm_enum_activitytype, Crm_enum_activitystatus

Crm_enum_activitypriority тощо) та системи Dataverse (ппідтримуються типи атрибутів Picklist, Status или Status Reason).

Тестове завантаження фрагмента даних з вибраними атрибутами з обох систем: Bitrix та Dataverse:

  • перегляд вибірки даних в табличній формі з можливістю сортування по стовпцях;
  • швидкий пошук за значенням у вибраному стовпці;
  • виключення завантаження «порожніх» рядків (при відсутності даних в вибраних атрибутах);
  • встановлення довільного фільтра у виборці даних (тільки для системи Bitrix).

✅   Збереження згенерованої карти міграції (зіставлених атрибутів вибраних сутностей) на локальному комп’ютері, з подальшим завантаження її в Застосунок для застосування.

✅   Створення атрибутів вибраної сутності, якщо їх немає в цільовій системі Dataverse.

✅   Кероване перенесення даних на основі карти міграції:

  • установка фільтра виборки даних із бази даних Bitrix 24;
  • автоматичне виявлення дублікатів записів з можливістю налаштування дій Застосунку для вирішення конфліктів;
  • попередній перегляд завантажуваних даних (з вихідної системи);
  • перегляд завантажених даних (в цільовій системі);
  • індикатор завантаження та повідомлення про помилку в режимі реального часу;
  • ведення журналу міграції даних;
  • переривання перенесення даних за бажанням користувача.

✅   Автоматичне створення зв’язків між перенесеними записами даних у цільовій системі:

  • перенесення даних в кілька «проходів» для коректного створення зв’язків один-до-багатьох;
  • налаштуйте «прив’язки» перенесених даних до наявних записів у цільовій системі.

✅   Настроювання параметрів Застосунку та інтерфейсу користувача для ефективного використання:

  • перемикання мови системи Dataverse у Застосунку для перегляду метаданих Dataverse (імен сутностей, атрибутів, наборів даних та назв елементів наборів даних) вибраною мовою.
  • вибір мови інтерфейсу (підтримується українська, російська та англійська мови);
  • налаштування шрифту інтерфейсу (підтримується малий, середній, великий розмір шрифту).

ЗАПУСК ЗАСТОСУНКУ ТА ЙОГО ІНТЕРФЕЙС

Щоб використовувати Застосунок Bitrix Migration Tool, потрібно встановити його як плагін на платформу XrmToolBox, що є Застосунком для настільних операційних систем Windows.

Ознайомитися з Застосунком XrmToolBox та завантажити безкоштовну розповсюджувану версію цього програмного забезпечення можна за адресою https://www.xrmtoolbox.com.

Після установки на комп’ютері та запуску XrmToolBox перейдіть в бібліотеку інструментів й введіть Bitrix Migration Tool в рядку пошуку.

Встановіть знайдений плагін.

Тепер Ви можете запустити Застосунок.

Після запуску XrmToolBox запропонує вам підключитися до середовища Microsoft Dynamics 365  або розробленої Вами програми, яка використовує базу даних Dataverse.

Таке підключення не потрібно, якщо Ви будете працювати тільки з базою даних Bitrix. В іншому випадку введіть свої облікові дані, щоб підключитися до Dataverse.

Після успішного підключення в XrmToolBox з’явиться вкладка з Застосунком.

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

Центральна частина вікна розділена на дві вертикальні зони.

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

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

Права зона відображає або карту міграції у вигляді ієрархічного дерева, зіставлені сутності à зіставлені атрибути для пари сутностей, або журнал трасування процесу міграції даних. Ви можете переключити вигляд цієї зони з меню Migration.

Налаштуйте підключення до системи Bitrix. Для цього необхідно спочатку отримати ключ авторизації, як описано в розділі ОТРИМАННЯ КЛЮЧА ВЕБ-API ДЛЯ ПІДКЛЮЧЕННЯ ДО BITRIX.

Відкрийте меню Settings та виберіть Plugin Settings:

Вкажіть адресу веб-сервісу Вашої системи Bitrix 24 з отриманим ключем API (адресою вхідного вебхука) в полі Bitrix Web API Endpoint:

Збережіть налаштування, натиснувши на кнопку Set.

Перевірте чи успішне підключення до Bitrix. Для цього натисніть на  кнопку LEAD (ліва кнопка в парі зіставлених сутностей LEAD à lead) у вікні Застосунку. Переконайтеся, що відображається список полів сутності LEAD системи Bitrix.

Переконайтеся, що підключення до Dataverse успішне. Для цього натисніть кнопку lead (права кнопка у парі зіставлених сутностей LEAD à lead) у вікні Застосунку. Переконайтеся, що відображається список полів сутності Lead системи Dataverse.

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

ЗАГАЛЬНИЙ АЛГОРИТМ МІГРАЦІЇ

Щоб перенести дані з однієї системи в іншу, спочатку потрібно зіставити сутності та атрибути.

Застосунок пропонує список попередньо зіставлених сутностей (див. ЗІСТАВЛЕННЯ СУТНОСТЕЙ)

Для кожної сутності необхідно налаштувати зіставлення атрибутів (див. ЗІСТАВЛЕННЯ АТРИБУТІВ), яке складається з трьох етапів:

  1. Вибір атрибутів Bitrix для зіставлення.
  2. Вибір атрибутів Dataverse для зіставлення .
  3. Зіставлення вибраних атрибутів та формування карти міграції для сутності.

Усі налаштування зіставлення накопичуються в карті міграції, яку можна завантажити у зовнішній файл (див. КАРТА МІГРАЦІЇ). Після зіставлення атрибутів і наборів даних сутностей можна переходити до процесу міграції даних.

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

Далі виберіть режим перенесення та запустіть процес міграції (див. ВИКОНАННЯ ПЕРЕНЕСЕННЯ ДАНИХ).

Сам процес міграції може включати в себе кілька етапів.

У найпростішому випадку, коли потрібно створити нові записи в системі Dataverse, не створюючи зв’язків між даними, буде потрібний один крок міграції.

Для зв’язку записів різних сутностей між собою потрібно виконати два або більше кроків перенесення.

Технічні деталі:

У реляційних базах даних зв’язки (або відносини) між даними будуються на основі первинного і зовнішнього ключів.

В системі Bitrix таким ключем є ціле число. Наприклад, щоб зазначити, що запис контактної особи зв’язаний із записом компанії з ідентифікатором первинного  ключа =XXX, у записі контактної особи вказується значення зовнішнього ключа COMPANY_ID = XXX. 

В системі Dataverse первинний й зовнішній ключі представлені унікальними текстовими ідентифікаторами виду 18D613E1-5E52-47F1-B070-10DB57ED950E. Більш того, первинний ключ генерується системою автоматично при створенні запису Dataverse та не може бути ініціалізований значенням ключа Bitrix.

Тому зв’язки між перенесеними даними в  системі Dataverse  необхідно перебудувати.

На першому кроці перенесіть дані сутностей Bitrix, включаючи первинні ключі.

Оскільки системні атрибути Dataverse не містять полів для зберігання ключів Bitrix, створіть цілочисельні атрибути, як описано в розділі Реєстрація нового атрибута Dataverse. Не рекомендується вибирати з доступних атрибутів Dataverse поля, в які будуть записані ключі Bitrix, якщо Ви не володієте професійними знаннями архітектури Dataverse.

Створіть нову карту міграції та додайте зіставлення зовнішніх ключів Bitrix до полів пошуку(lookup) Dataverse.

Увімкніть режим оновлення даних, як описано в розділі ВИКОНАННЯ ПЕРЕНЕСЕННЯ ДАНИХ, та запустіть міграцію даних. Застосунок створить відсутні зв’язки між даними.

Поточна версія Застосунку підтримує автоматичне створення зв’язків 1:N для атрибутів Bitrix з типами Crm_company, Crm_contact, Crm_currency, Crm_deal, Crm_lead, Crm_quote.

ЗІСТАВЛЕННЯ СУТНОСТЕЙ

Застосунок містить список попередньо зіставлених сутностей двох систем Bitrix та Dataverse:

Цей список фіксований та не може бути змінений. Тобто Ви не можете змінити зіставлення LEAD à lead на, наприклад, LEAD à contact.

У майбутніх версіях Застосунку список зіставлених сутностей для міграції даних буде розширено.

Щоб вибрати атрибути, дані яких повинні бути перенесені з системи Bitrix, натисніть на кнопку з назвою сутності в лівій колонці. Для отримання додаткової інформації дивіться Вибір атрибутів Bitrix для зіставлення.

Щоб вибрати атрибути, на які будуть записані перенесені дані, натисніть кнопку з назвою сутності в правому стовпці. Для отримання додаткової інформації дивіться Вибір атрибутів Dataverse для зіставлення.

Щоб зіставити атрибути пари зіставлених сутностей, натисніть кнопку . Для отримання додаткової інформації див. ЗІСТАВЛЕННЯ АТРИБУТІВ.

Щоб включити обробку атрибутів пари зіставлених сутностей у процес міграції, натисніть кнопку   І навпаки, щоб виключити з міграції дані з будь-якої сутності Bitrix, зніміть відмітку (якщо вона була встановлена), натиснувши кнопку .

ВИБІР АТРИБУТІВ ДЛЯ ЗІСТАВЛЕННЯ

Вибір атрибутів Bitrix для зіставлення

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

Список показує метадані атрибутів вибраної сутності (на скріншоті вище це сутність INVOICE) у трьох стовпцях:

  • Логічне ім’я атрибута.
  • Назва атрибута.
  • Тип даних атрибута.

Різні типи атрибутів виділяються різними кольорами фону.

Можна фільтрувати лише один тип атрибутів. Для цього розгорніть список Filter by Type та виберіть потрібний тип даних.

Після закриття фільтра в таблиці залишаються тільки атрибути вибраного типу.

Щоб швидко знайти потрібний атрибут, введіть перші кілька символів логічного імені або назви атрибута, в поле Search by Name. Натисніть клавішу Enter або кнопку . У таблиці будуть показані атрибути, у яких логічне ім’я або назва починається із зазначеної послідовності символів.

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

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

Щоб скасувати фільтр пошуку, очистіть рядок пошуку або натисніть кнопку .

Атрибути Bitrix, які можуть бути використані при формуванні зіставлення сутностей, відображаються в списку праворуч від таблиці атрибутів.

Виберіть потрібний атрибут в списку за допомогою клавіш курсору або клікнувши по ньому мишкою.

Натисніть на кнопку : обраний атрибут буде перенесений в список вибраних атрибутів для зіставлення.

Швидко вибрати атрибути можна, двічі клацнувши по відповідних рядках в таблиці атрибутів.

Ще один спосіб вибору атрибутів для зіставлення – “перетягнути” за допомогою мишки атрибут з таблиці атрибутів до списку зіставлених атрибутів.

Атрибути, вибрані для зіставлення, виділяються в таблиці атрибутів сірим кольором. Ви можете виключити всі вибрані атрибути з таблиці атрибутів, встановивши прапорець Only Selected:

Щоб дізнатися ім’я вибраного атрибуту та його тип даних, наведіть курсор миші на елемент у списку; Через кілька секунд з’явиться така спливаюча підказка:

Щоб виключити атрибут зі списку зіставлених атрибутів, виберіть атрибут у списку праворуч і натисніть кнопку .

Щоб повністю очистити список вибраних атрибутів, натисніть кнопку .

Натискання кнопки  відкриває вікно з додатковою інформацією про атрибут. Ця функція корисна для перегляду списку елементів атрибута з типом набор даних (Crm_status, Crm_enum_ownertype, Crm_enum_activitytype тощо).

Коли Ви закінчите вибирати атрибути, які ззіставляються, обов’язково натисніть кнопку Apply: всі вибрані атрибути будуть збережені в карті міграції. Навіть якщо Ви закінчите роботу з Застосунком на цьому етапі та закриєте плагін XrmToolBox, то в наступній сесії всі вибрані атрибути будуть завантажені автоматично.

Натискання на кнопку Cancel скасовує всі Ваші дії у вікні вибору атрибутів для зіставлення. Якщо список атрибутів для зіставлення раніше вже був сформований в Застосунку, він не зміниться.

Корисні поради.

Відсортувати дані за зростанням або спаданням в будь-якому зі стовпців можна, натиснувши на заголовок відповідного стовпця. Порядок сортування відображається у вигляді піктограми або

Змінити ширину таблиці можна таким чином: встановити покажчик миші на кордон між таблицею та списком атрибутів, далі натиснувши ліву кнопку «потягнуть» межу вліво або вправо.

Ви можете змінити розмір вікна зіставлення атрибутів та розширити його на весь екран монітора, як це зазвичай робиться з іншими вікнами Windows.

Вибір атрибутів Dataverse для зіставлення

Важливо! Щоб вибрати атрибути Dataverse, спочатку потрібно підключитися до середовища Dataverse.

В панелі керування зіставленням натисніть кнопку з назвою сутності в системі Dataverse  (це правий стовпець кнопок). Відкриється вікно вибору атрибутів для зіставлення.

Список містить метадані атрибута вибраної сутності (на скріншоті вище це сутність Invoice) у трьох стовпцях:

  • Логічне ім’я атрибута.
  • Назва атрибута.
  • Тип даних атрибута.

Різні типи атрибутів виділяються різними кольорами фону.

Можна фільтрувати лише один тип атрибутів. Для цього розгорніть список Filter by Type та виберіть потрібний тип даних.

Після закриття фільтра в таблиці залишаються тільки атрибути вибраного типу.

Щоб швидко знайти потрібний атрибут, введіть перші кілька символів логічного імені або назви атрибута в поле Search by Name. Натисніть клавішу Enter або кнопку . У таблиці будуть показані атрибути, логічне ім’я або назва яких починається із зазначеної послідовності символів.

Використовуйте символ узагальнення ” * “­, щоб відібрати всі атрибути, які містять введену послідовність символів у логічному імені або назві.

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

Щоб скасувати фільтр пошуку, очистіть рядок пошуку або натисніть кнопку .

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

Виберіть потрібний атрибут в списку за допомогою клавіш курсору або клікнувши по ньому мишкою.

Натисніть на кнопку : обраний  атрибут буде перенесений в список вибраних атрибутів для зіставлення.

Швидко вибрати атрибути можна двічі клацнувши по відповідному рядку в таблиці атрибутів.

Ще один спосіб вибору атрибутів для зіставлення – “перетягнути” за допомогою мишки атрибут із таблиці атрибутів до списку вибраних атрибутів.

Атрибути, вибрані для зіставлення, виділяються в таблиці атрибутів сірим кольором фона. Ви можете виключити всі вибрані атрибути з таблиці атрибутів, встановивши прапорець Only Selected:

Щоб дізнатися логічне ім’я вибраного атрибуту та його тип даних, наведіть курсор миші на елемент у списку; через кілька секунд з’явиться така спливаюча підказка:

Щоб вилучити атрибут зі списку зіставлених атрибутів, виберіть атрибут у списку праворуч і натисніть кнопку .

Щоб повністю очистити список вибраних атрибутів, натисніть кнопку .

Натискання на кнопку відкриває вікно з додатковою інформацією про атрибут.

Ця функція корисна для перегляду локалізованих міток (імен) атрибута, а також списку елементів атрибута з типом набір даних Status, Status Reason та Option Set.

Коли Ви закінчите вибирати атрибути, які будуть зіставлятися, обов’язково натисніть на кнопку Apply: всі вибрані атрибути будуть «запам’ятовані». Навіть якщо Ви вийдете з Застосунку на цьому етапі та закриєте плагін XrmToolBox, всі вибрані атрибути будуть автоматично завантажені в наступному сеансі.

Натискання на кнопку Cancel скасовує всі Ваші дії у вікні вибору атрибутів для зіставлення. Якщо список атрибутів для зіставлення раніше був сформований в Застосунку, він не зміниться.

Корисні поради.

Відсортувати дані за зростанням або спаданням в будь-якому зі стовпців можна, натиснувши на заголовок відповідного стовпця. Порядок сортування відображається у вигляді піктограми або

Змінити ширину таблиці можна таким чином: встановити покажчик миші на кордон між таблицею та списком атрибутів, далі натиснувши ліву кнопку «потягнуть» межу вліво або вправо.

Ви можете змінити розмір вікна зіставлення атрибутів й розширити його на весь екран монітора, як це зазвичай робиться з іншими вікнами Windows.

ЗІСТАВЛЕННЯ АТРИБУТІВ

Після того, як Ви вибрали всі необхідні атрибути для пар зіставлених сутностей (дані яких будуть перенесені), Ви повинні явно встановити зв’язки між атрибутами сутностей двох систем.

Натисніть на кнопку  в одному з рядків з парою зіставлених сутностей. Відкриється вікно для зіставлення атрибутів сутності Bitrix з атрибутами Dataverse.

Важливо! Зіставляти можна лише сумісні типи даних. Наприклад, атрибут Bitrix з типом даних string або char може бути зіставлений  з атрибутом Dataverse з типом даних string або memo (кілька рядків тексту).

Зіставлені типи даних забарвлюються в один колір. Застосунок відстежує сумісність даних й блокує некоректні операції зіставлення.

У лівій колонці вікна зіставлення відображається список атрибутів Bitrix, вибраних для зіставлення. У правій колонці знаходиться список атрибутів Dataverse.

Списки атрибутів сортуються в алфавітному порядку.

«Перетягніть» атрибут зі списку зліва в центральну область або двічі кликніть по обраному атрибуту – він буде автоматично поміщений в стовпець Bitrix Field.

Тепер «перетягніть» мишкою відповідний атрибут Dataverse. Або двічі клацніть потрібний атрибут усписку Selected Dataverse Fields.

Зіставлені атрибути виділяються сірим кольором у списках в обох списках.

Скористайтеся швидким пошуком за назвою одного з атрибутів, щоб знайти зіставлення. Для цього введіть перші кілька символів назви атрибута в поле Search by Name та натисніть кнопку : список зіставлень буде містити тільки результати пошуку.

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

Результат Вашої роботи буде виглядати приблизно так:

Щоб скасувати неправильне зіставлення атрибутів, натисніть кнопку .

Щоб видалити всі зіставлення, натисніть кнопку Clear All.

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

Зауважте, що може бути зіставленими не всі вибрані атрибути. Ви можете зберегти проміжні результати, натиснувши кнопку Apply, потім додати відсутні атрибути Bitrix та Dataverse й знову повернутися до зіставлення. 

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

Після завершення зіставлення збережіть результати, натиснувши кнопкуApply.

ЗІСТАВЛЕННЯ ЗНАЧЕНЬ НАБОРІВ ДАНИХ

Загальні відомості

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

Набори даних в Bitrix представлені типами Crm_status, Crm_enum_activitytype, Crm_enum_activitypriority та іншими подібними типами. 

Набори даних у Dataverse представлені типами Option Set (також відомими як Choices, Picklist), State Code та Status Code.

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

У поточній версії Додатку передбачено перенесення значень наборів даних у вигляді пар Label: Value, без додаткових атрибутів.

Кількість значень у зіставлених наборах даних Bitrix та Dataverse може змінюватися, як і константи числових значень.

Наприклад, набір даних PRIORITY (Пріоритет) в Bitrix містить наступні пари Мітка : Значення: 

<пусте значення> : 0

Низкий : 1

Середний : 2

Високий : 3

Схожий набір даних Priority в Dataverse містить пари:

Low : 0

Normal : 1

Hight : 2

Зіставлення наборів даних виконується за унікальним значенням. Щоб правильно перенести атрибут з типом набір даних, необхідно вказати зіставлення:

Низкий : 1              Low : 0

Середний : 2          Normal : 1

Високий : 3             Hight : 2

Пусте значення набору даних в Bitrix відповідає нульовому значенню в наборі даних Dataverse.

Зіставлення пар значень набору даних

Зіставте атрибути Bitrix та Dataverse з типом набору даних (див. ЗІСТАВЛЕННЯ АТРИБУТІВ).

Виберіть пару атрибутів Bitrix та Dataverse з типом набір даних та натисніть кнопку  Option Set Mapping.

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

Результат зіставлення:

Щоб видалити будь-яку пару зіставлення значень, клацніть .

Щоб повністю очистити список зіставлень, натисніть кнопку Clear All.

Зауважте, що якщо значення наборів даних Bitrix та Dataverse не зіставлено для пари атрибутів з типом набір даних, дані цього атрибуту не будуть перенесені до цільової системи, навіть якщо зіставлення цих атрибутів відображається на карті міграції.

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

СТВОРЕННЯ АТРИБУТІВ ТА НАБОРІВ ДАНИХ DATAVERSE

Може виникнути потреба в перенесенні атрибутів та наборів даних Bitrix, аналогів яким в системі Dataverse знайти не вдасться.

Наприклад, сутності LEAD, CONTACT та COMPANY в Bitrix містять атрибути для зберігання акаунтів в соціальних мережах Telegram, Viber, Twitter тощо, в той час як в списку атрибутів системи Dataverse таких полів немає.

Ще один важливий випадок, коли потрібно створити нові атрибути Dataverse,  — це  «прив’язка» даних однієї сутності до іншої. Для створення зв’язків між даними потрібно перенести первинні ключі Bitrix в цілочисельні поля Dataverse  (див. ЗАГАЛЬНИЙ АЛГОРИТМ МІГРАЦІЇ ).

Не рекомендується використовувати існуючі цілочисельні системні атрибути Dataverse для запису в них значень первинних ключів Bitrix.

Ви можете створювати нові атрибути та набори даних Dataverse у самому середовищі Dataverse або безпосередньо в Застосунку.

Реєстрація нового атрибута Dataverse

Зареєструвати новий атрибут та локальний набір даних Dataverse можна у вікні вибору атрибутів Bitrix для зіставлення.

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

Натисніть кнопку Create Dataverse Field.

У Застосунку відкриється вікно для установки характеристик атрибута Dataverse, який потрібно створити, на основі імені та типу атрибута Bitrix.

На скріншоті вище був обраний атрибут Contact із цілочисельним типом (зовнішній ключ). Додаток пропонує створити однотипний атрибут Dataverse, логічне ім’я якого створене додаванням префікса вибраного видавця Dataverse до логічного імені атрибуту Bitrix.

Ви можете вказати додаткові налаштування для створюваного атрибута, які підтримуються системою Dataverse.

Після створення атрибута Застосунок автоматично опублікує зміни до схеми сутностей Dataverse, якщо в налаштуваннях Застосунку встановлений прапорець Publish Metadata after Creation (див. НАЛАШТУВАННЯ).

Важливо! Будьте обережні, вказуючи ім’я атрибута (назви, що відображається) для середовища Dataverse, у якому встановлено кілька мов. Назва атрибута буде розміщено в локалізованій мітці для поточної встановленої мови Dataverse. Наприклад, якщо для Вашої поточної мови середовища Dataverse встановлено англійську мову, введена Вами назва атрибута буде розміщено в мітці для англійської мови.

Перемикайте мову середовища Dataverse за потреби, як описано в розділі Перемикання мови середовища Dataverse.

Поточна версія Застосунку не підтримує роботу з локалізованими мітками атрибутів. Використовуйте плагін CRM Translator ©, щоб встановити назву атрибута для всіх мов, що встановлені в середовище Dataverse.

Перевірити результат реєстрації нового атрибута можна в провіднику (конструкторі) рішень Dataverse:

Нижче наведено скріншоти створення текстового атрибута Dataverse для зберігання облікового запису месенджера Telegram та локального набору даних для класифікації компанії за кількістю зайнятих співробітників.

Поточна версія Застосунку не підтримує створення та редагування елементів наборів даних. Всі елементи набору даних Bitrix будуть перенесені в новий набір даних Dataverse.

Також поточна версія Застосунку не підтримує створення локального набору даних на основі глобального набору даних.

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

Реєстрація нового глобального набору даних

Зареєструвати новий глобальний набір даних Dataverse можна у вікні перегляду довідників Bitrix.

Виділіть довідник Bitrix та натисніть кнопку Create Dataverse Picklist.

Застосунок відкриє вікно для встановлення характеристик глобального набору даних Dataverse, який потрібно створити, на основі назви та типу довідника Bitrix.

Після створення глобального набору даних Застосунок автоматично опублікує зміни в Dataverse, якщо в налаштуваннях Застосунку встановлено прапорець Publish Metadata after Creation (див. НАЛАШТУВАННЯ).

Важливо! Будьте обережні, встановлюючи ім’я набору даних (назви, що відображається) для середовища Dataverse, у якому встановлено кілька мов. Назву набору даних буде розміщено в локалізованій мітці для поточної встановленої мови Dataverse. Наприклад, якщо для Вашої поточної мови середовища Dataverse встановлено англійську мову, введена Вами назва набору даних буде розміщена в мітці для англійської мови.

Перемикайте мову середовища Dataverse за потреби, як описано в розділі Перемикання мови середовища Dataverse.

Поточна версія Застосунку не підтримує роботу з локалізованими мітками наборів даних. Використовуйте плагін CRM Translator ©,щоб встановити назву набору даних усіма мовами, що встановлені в середовищі Dataverse.

Також поточна версія Застосунку не підтримує створення та редагування елементів наборів даних. Всі елементи набору даних Bitrix будуть перенесені в новий набір даних Dataverse.

Перевірити результат реєстрації нового глобального набору даних можна в провіднику (конструкторі) рішень Dataverse.

ПОПЕРЕДНІЙ ПЕРЕГЛЯД ДАНИХ

Загальні відомості

Після вибору для зіставлення атрибутів Bitrix та Dataverse будь-якій сутності можна переглядати записи з даними цієї сутності. Вибірка обмежена першими 50 записами вказаної сутності. Відображаються дані лише вибраних атрибутів.

Можна шукати запис у всьому або лише у вказаному стовпці за шаблоном пошуку. Він підтримує сортування за будь-яким стовпцем даних, зміну розміру стовпця та «перетягування» стовпця за допомогою мишки.

Попередній перегляд даних Bitrix

Попередній перегляд даних Bitrix буде корисним, коли Вам потрібно вирішити, чи включати певний атрибут у карту зіставлення сутностей. Якщо в попередньому перегляді немає даних у жодному стовпці (атрибуті), то немає сенсу зіставляти цей атрибут з атрибутом Dataverse.

Для попереднього перегляду даних Bitrix спочатку виберіть атрибути, як описано в розділі ВИБІР АТРИБУТІВ ДЛЯ ЗІСТАВЛЕННЯ.

Потім відкрийте меню Data та в списку Bitrix Data Preview виберіть сутність, записи якої потрібно переглянути.

Відкриється вікно з даними перших 50 записів, завантажених з бази даних Bitrix.

Щоб знайти запис із певним значенням у потрібному стовпці, виберіть цей стовпець у списку Search in Column та введіть текст пошуку в полі by Template.

Для пошуку в усіх стовпцях використовуйте фільтр зі значенням All.

Зверніть увагу, що Ви можете переглядати дані Bitrix, коли Ви навіть не підключені до середовища Dataverse.

Визначення фільтра вибірки даних Bitrix

Змінити умови вибірки даних із системи Bitrix можна, задавши параметри фільтрації.

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

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

Відкрийте меню Data,потім перейдіть до Set Filter to Retrix Data та виберіть сутність, для якої потрібно встановити фільтр вибірки:

У вікні, що відкрилося, введіть значення фільтра. На малюнку нижче встановлено умову вибору всіх записів, в яких в контактній адресі вказано місто Київ:

Після натискання на кнопку ОК Застосунок відобразить перші 50 записів вибірки даних із застосованим фільтром; це дозволяє перевірити, чи правильно працює фільтр.

Важливо! Ви повинні знати правила побудови запитів до бази даних Bitrix за допомогою Web API, щоб правильно встановити значення фільтра. Застосунок не перевіряє синтаксис фільтра, тож якщо фільтра завданий з помилкою, Bitrix може повернути порожню вибірку даних або всі можливі дані, не застосовуючи фільтр.

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

На рисунку нижче наведено фільтр для вибірки записів із датою виставлення рахунків між 01 серпня та 30 листопада 2017 року.

Результат вибірки:

Важливо! Встановлені фільтри в попередньому перегляді даних Bitrix також можна застосувати до процесу міграції. Перед початком міграції даних Застосунок запитує підтвердження для використання вказаних фільтрів. Якщо фільтри не використовуються, дані будуть перенесені в повному обсязі. Тому немає необхідності очищати фільтри перед початком міграції.

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

Попередній перегляд даних Dataverse

Попередній перегляд даних Dataverse допоможе Вам вибрати правильний режим міграції: чи створювати нові записи або оновлювати існуючі записи Dataverse. Якщо попередній перегляд містить дані в будь-якому стовпці, Вам слід більш детально проаналізувати наявні дані безпосередньо в середовищі Dataverse, щоб уникнути «перезапису» даних. В іншому випадку, коли даних у всіх вибраних стовпцях Dataverse немає, Ви можете використовувати режим створення нових записів.

Ви також можете налаштувати у своєму середовищі Dataverse правила для виявлення дублікатів сутностей, записи яких перенесено, щоб уникнути створення записів з однаковими значеннями в полях відстеження.

Щоб попередньо переглянути свої дані Dataverse, підключіться до середовища Dataverse та виберіть атрибути, як описано в розділі ВИБІР АТРИБУТІВ ДЛЯ ЗІСТАВЛЕННЯ.

Потім відкрийте меню Data та у списку Dataverse Data Preview виберіть сутність, записи якої потрібно переглянути.

КАРТА МІГРАЦІЇ

Загальні відомості

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

Карта міграції використовується для міграції даних з вихідної системи Bitrix в цільову систему Dataverse за такими правилами:

  • Дані з сутності Bitrix переносяться в його зіставлену сутність Dataverse.
  • Дані з атрибуту сутності Bitrix переносяться в зіставлений атрибут сутності Dataverse.

Більш того, в процесі міграції можуть виконуватися додаткові перетворення даних, в залежності від їх типу.

Завантаження карти міграції

Щоб завантажити заздалегідь підготовлену карту міграції, відкрийте меню Migration та виберіть Load Migration Map.

У вікні, що відкрилося, виберіть карту міграції та натисніть кнопку Load.

Перегляньте метадані обраної карти міграції та підтвердьте її завантаження, натиснувши клавішу Enter або кнопку OK.

Схема завантаженої карти міграції буде відображена праворуч в вікні Застосунку.

Перегляд карти міграції

Щоб переглянути карту міграції, відкрийте меню Migration та виберіть пункт View Migration Map.

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

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

Карта міграції відображатиметься автоматично після її завантаження (як описано в розділі Завантаження карти міграції) або після встановлення принаймні однієї пари зіставлених атрибутів у вибраній парі зіставлених сутностей Bitrix та Dataverse.

Після видалення всіх зіставлених пар атрибутів відповідна пара зіставлених сутностей Bitrix та Dataverse більше не з’являється на карті міграції.

Збереження карти перенесення

Виконайте зіставлення атрибутів для вибраних пар сутностей Bitrix та Dataverse, як описано в розділі ВИБІР АТРИБУТІВ ДЛЯ ЗІСТАВЛЕННЯ.

Відкрийте меню Migration і оберіть Save Migration Map.

Введіть назву карти міграції та, за необхідності, опис карти.

Введіть ім’я файлу, в якому буде зберігатися карта міграції.

Натисніть на Save.

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

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

ВИКОНАННЯ ПЕРЕНЕСЕННЯ ДАНИХ

Міграція даних з вихідної системи Bitrix  в цільову систему Dataverse виконується після визначення карти міграції та вибору пар зіставлених сутностей.

Процес міграції може виконуватися в один або кілька етапів. На першому кроці виберіть режим створення нових записів у Dataverse – Create Records.

На другому кроці, коли Вам потрібно зв’язати записи між собою або коли Вам потрібно оновити вже створені записи, встановіть режим оновлення записів у Dataverse – Update Records.

Для отримання додаткової інформації див. ЗАГАЛЬНИЙ АЛГОРИТМ МІГРАЦІЇ.

Важливо! Записи оновлюються тільки в тому випадку, якщо в карті міграції використовуються атрибути первинного ключа вибраної сутності Bitrix. Зазвичай ім’я атрибута з первинним ключем  має назву «ID».

Можна встановити фільтри для вибору записів з однієї або декількох сутностей Bitrix.

Щоб встановити фільтр, відкрийте меню Data, потім перейдіть  до Set Filter to Retrix Data та виберіть у списку сутність, для якої потрібно встановити фільтр вибірки даних.

У вікні, що відкрилось, напишіть текст фільтра та натисніть Ок.

Щоб скасувати будь-який з встановлених фільтрів, відкрийте меню Data, потім перейдіть в Set Filter to Retrix Data та виберіть у списку сутність, для якої потрібно очистити фільтр. 

У вікні налаштування фільтра, що відкриється, натисніть кнопку Clear, щоб очистити фільтр.

Щоб дізнатися більше про фільтри, див. розділ Визначення фільтра вибірки даних Bitrix.

Щоб почати перенесення даних, натисніть на кнопку Run в панелі керування перенесенням даних.

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

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

Перебіг міграції даних можна відстежувати в журналі трасування. Щоб відобразити дані журналу, відкрийте меню Migration та виберіть пункт View Transfer Log:

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

Щоб примусово зупинити перенесення даних, натисніть кнопку Cancel. Через короткий час процес міграції буде зупинено.

На скріншоті нижче показаний результат перенесення 55 записів з системи Bitrix в базу даних Dataverse.

НАЛАШТУВАННЯ

Вибір видавця Dataverse

Застосунок надає можливість створювати нові атрибути таблиці Dataverse. Новий атрибут отримає префікс видавця, який був вибраний у меню Settings Застосунку, пункт меню Select a Publisher.

У списку, що відкривається, відображаються імена всіх видавців, зареєстрованих в Dataverse, а в дужках – префікси видавця.

Ви можете вказати ім’я видавця в налаштуваннях Застосунку, яке буде автоматично вибрано під час підключення до середовища Dataverse.

Важливо! Видавця можна вибрати тільки після підключення до середовища Dataverse.

Перемикання мови середовища Dataverse

Застосунок підтримує перемикання мови інтерфейсу середовища Dataverse.

Оскільки Bitrix повертає назви міток російською мовою, перемикання мови інтерфейсу Dataverse може полегшити коректне зіставлення атрибутів (полів) двох систем (за умови встановлення декількох мов локалізації в середовище Dataverse).

Налаштування мови відповідає налаштуванню мови в особистих налаштуваннях користувача в середовище Dataverse.

Мова інтерфейсу змінюється лише для поточного користувача, який увійшов у Dataverse за допомогою Застосунку. Для всіх інших користувачів мова інтерфейсу користувача Dataverse не змінюється. Якщо користувач не підключився до Dataverse у Застосунку, функція перемикання мови Dataverse недоступна.

Ви можете вибрати будь-яку з встановлених мов у меню Settings. Після успішного перемикання мови ліворуч від пункту меню Dataverse Language відображається значок встановленої мови.

Важливо! Перемикання мови виконується лише для інтерфейсу Dataverse. Мовні параметри довідки та мови формату представлення даних не змінюються. Важливо! Коли Ви перемикаєте мову Dataverse, мова інтерфейсу самого Застосунку не змінюється. Використовуйте налаштування для перемикання мови інтерфейсу Застосунку (див. посилання!).

ОТРИМАННЯ КЛЮЧА ВЕБ-API ДЛЯ ПІДКЛЮЧЕННЯ ДО BITRIX

Застосунок використовує відомості про налаштування, або метадані системи Bitrix, для генерації карти міграції, а потім для зчитування даних з метою передачі їх в систему Dataverse.

Доступ до системи Bitrix здійснюється через запити REST API з авторизацією по ключу.

Важливо! Додаток використовує тільки GET-запити, тобто тільки зчитує дані системи Bitrix. Створення, редагування або видалення даних в системі Bitrix не підтримується.

Авторизуйтесь на сайті Bitrix 24  з правами адміністратора.

На вкладці Сайт відкрийте сторінку Разработчикам.

На першій вкладці Готовые сценари виберіть Другое.

Створити вхідний вебхук.

У нижній частині вікна реєстрації вебхука додайте права доступу до таблиць системи Bitrix: CRM, Списки, Чат и сообщения, Задачи, Настройки пользовательских полей.

Важливо! У майбутніх версіях Застосунку може виникнути необхідність розширити права доступу до даних через REST API. Поточна версія підтримує обмежений набір сутностей Bitrix.

Скопіюйте рядок з поля Вебхук для вызова rest api. Це значення необхідно вставити в налаштування програми, див. розділ ЗАПУСК ЗАСТОСУНКУ ТА ЙОГО ІНТЕРФЕЙС.

Збережіть налаштування вебхука.