Перенос данных из облака Битрикс24 в коробку Битрикс24 при помощи REST API

1. Из облака в коробку Битрикс24: готовимся к переезду грамотно

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

Также среди наших заказчиков были запросы и на перенос бизнес-процессов и смарт-процессов.

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

Инструкцию по настройке обмена данными между облаком Битрикс24 и коробкой (создание и обновление сделок) читайте по ссылке.

Но всех их объединяет одна проблема при старте переезда - ручной перенос данных. Напомним, что бэкап облака невозможен с 1 сентября 2023 года.

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

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

Решение этой задачи - выгрузка данных при помощи интеграций Пинкит посредством REST API.

Инструкция по обмену задачами Битрикс24 (из коробки в облако) и проверка интеграции на успех здесь.

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

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

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

2. Инструкция по настройке интеграций Пинкит по переносу задач из облака в коробку Битрикс24

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

Для этого понадобится 6 интеграций.

2.1. Интеграция "Задача создана в облаке -> Задачу создать в коробке"

2.1.1. Шаг 1: Откуда

Откуда отправляем данные: Битрикс24 (Webhook), Когда - "Задача создана". Подключаем доступ к облаку.

2.1.2. Шаг 2: Инструменты

Инструмент "Сопоставление групп между облаком и коробкой"

Используем инструмент "Сопоставление данных по полю" source.groupId, чтобы сопоставить группы задач между облаком и коробкой.

Инструмент "Сопоставление Наблюдателей, Исполнителей, Постановщиков, Соисполнителей"

Сопоставление настроим по полям задач source.createdBy, source.responsibleId, source.auditors, source.accomplices.

Инструмент "Получить теги задачи"

Используем API-запрос GET-методом с указанием URL: /task.item.gettags?TASK_ID={{source.id}}.

Инструмент "Получить вложения задачи"

Используем API-запрос GET-методом с указанием URL: /task.item.getfiles.json?TASKID={{source.id}}.

Инструмент "Вложения в задаче найдены?"

Используем инструмент "Если-Иначе", название поля - step4.result, Условие - "Не пустое значение", Результат при успешной проверке - 1, Результат при неуспешной проверке - 0.

Инструмент "Получить ID Хранилища"

Используем API-запрос GET-методом с указанием URL: /disk.storage.getlist?filter[ENTITY_ID]={{step1}}&filter[ENTITY_TYPE]=group

Инструмент "Получить стадии канбана в облаке"

Используем API-запрос GET-методом с указанием URL: /task.stages.get?entityId={{source.groupId}}&isAdmin=true

Инструмент "Получить стадии канбана в коробке"

Используем API-запрос GET-методом с указанием URL: /task.stages.get?entityId={{step1}}&isAdmin=true

Инструмент "Отфильтровать стадию в облаке"

Используем фильтр элементов массива, Название поля - step7.result, Условие - "Текст содержит", Сравниваемое значение - source.stageId.

Инструмент "Найти нужную стадию канбана в коробке"

Используем фильтр элементов массива, Название поля - step8.result, Название поля внутри элемента массива - TITLE, Условие - Текст содержит, Сравниваемое значение - step9.0.TITLE.

2.1.3. Шаг 3: Куда

Куда отправляем данные - Битрикс24 (это уже будет коробка), Какое действие совершаем - "Создать задачу".

2.1.4. Шаг 4: Сопоставление данных

Сопоставляем название и описание задачи в облаке и коробке.

Указываем дополнительные сопоставления из шага 2.

Дополнительное тело запроса:

{

"fields": {

"RESPONSIBLE_ID": "{{step2.source_responsibleId|default()}}",

"MARK": "{{source.mark|default()}}",

"PRIORITY": "{{source.priority|default()}}",

"MULTITASK": "{{source.multitask|default()}}",

"NOT_VIEWED": "{{source.notViewed|default()}}",

"REPLICATE": "{{source.replicate|default()}}",

"STAGE_ID": "{{step10.0.ID|default()}}",

"START_DATE_PLAN": "{{source.startDatePlan|default()}}",

"END_DATE_PLAN": "{{source.endDatePlan|default()}}",

"XML_ID": "{{source.xmlId|default()}}",

"ALLOW_CHANGE_DEADLINE": "{{source.allowChangeDeadline|default()}}",

"TASK_CONTROL": "{{source.taskControl|default()}}",

"ADD_IN_REPORT": "{{source.addInReport|default()}}",

"TIME_ESTIMATE": "{{source.timeEstimate|default()}}",

"TIME_SPENT_IN_LOGS": "{{source.timeSpentInLogs|default()}}",

"MATCH_WORK_TIME": "{{source.matchWorkTime|default()}}",

"FORUM_TOPIC_ID": "{{source.forumTopicId|default()}}",

"FORUM_ID": "{{source.forumId|default()}}",

"SITE_ID": "{{source.siteId|default()}}",

"SUBORDINATE": "{{source.subordinate|default()}}",

"EXCHANGE_MODIFIED": "{{source.exchangeModified|default()}}",

"EXCHANGE_ID": "{{source.exchangeId|default()}}",

"OUTLOOK_VERSION": "{{source.outlookVersion|default()}}",

"VIEWED_DATE": "{{source.viewedDate|default()}}",

"SORTING": "{{source.sorting|default()}}",

"DURATION_FACT": "{{source.durationFact|default()}}",

"IS_MUTED": "{{source.isMuted|default()}}",

"IS_PINNED": "{{source.isPinned|default()}}",

"IS_PINNED_IN_GROUP": "{{source.isPinnedInGroup|default()}}",

"DURATION_PLAN": "{{source.durationPlan|default()}}",

"DURATION_TYPE": "{{source.durationType|default()}}",

"FAVORITE": "{{source.favorite|default()}}",

"ALLOW_TIME_TRACKING":"Y",

"UF_AUTO_299592262349":"{{source.ufAuto418665225732}}"

     }

}

И дополнительные сопоставления:

groupId

Тип: Тело

Название параметра: fields.GROUP_ID

Значение параметра: {{step1}}

Дата создания

Тип: Тело

Название параметра: fields.CREATED_DATE

Значение параметра: {{Дата создания}}

Дата изменения

Тип: Тело

Название параметра: fields.CHANGED_DATE

Значение параметра: {{Дата изменения}}

Статус

Тип: Тело

Название параметра: fields.STATUS

Значение параметра: {{Статус}}

Крайний срок

Тип: Тело

Название параметра: fields.DEADLINE

Значение параметра: {{Крайний срок}}

Постановщик

Тип: Тело

Название параметра: fields.CREATED_BY

Значение параметра: {{step2.source_createdBy}}

Дата начала

Тип: Тело

Название параметра: fields.DATE_START

Значение параметра: {{Дата начала}}

AUDITORS

Тип: Тело

Название параметра: fields.AUDITORS

Значение параметра: {{step2.source_auditors}}

ACCOMPLICES

Тип: Тело

Название параметра: fields.ACCOMPLICES

Значение параметра: {{step2.source_accomplices}}

TAGS

Тип: Тело

Название параметра: fields.TAGS

Значение параметра: {{step3.result|default()}}

2.1.5. Шаг 5: Запуск

Указываем название интеграции, периодичность запросов данных и запускаем.

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

2.2. Интеграция "Задача - добавить вложения"

2.2.1. Шаг 1: Откуда

Откуда отправляем данные - Пинкит, Когда - "Интеграция - успех", подключаем аккаунт Пинкит и выбираем интеграцию, настроенную нами ранее.

2.2.2. Шаг 2: Инструменты

Инструмент "Вложение было?"

Используем инструмент "Проверка", Название поля - source.int6551.step5, Условие - "ЧислоРавно", Сравниваемое значение - 1, Действие - Продолжить, если проверка пройдена.

Инструмент "Для каждого вложения"

Тип шага - "Для каждого", название поля - source.int6551.step4.result.

Инструмент "Получить развернутую информацию о вложениях"

Используем API-запрос GET-методом с указанием URL: /disk.attachedObject.get?id={{step2.ATTACHMENT_ID|default()}}

Инструмент "Скачать файл"

Тип шага - Скачать файл, для этого используем API-запрос GET-методом с указанием URL: {{step3.result.DOWNLOAD_URL|default()}}.

2.2.3. Шаг 3: Куда

Куда отправляем данные - коробка Битрикс24, когда: "Задача - добавить вложение".

2.2.4. Шаг 4: Сопоставление данных

Настраиваем сопоставление:

ID задачи - {{source.int6551.result.result.task.id|default()}}

Название файла - {{step3.result.NAME}}

URL файла - {{step4}}

2.2.5. Шаг 5: Запуск

Запускаем интеграцию.

2.3. Интеграция "Задача - Добавить комментарии 50 последних"

2.3.1. Шаг 1: Откуда

Откуда отправляем данные - Пинкит, Когда - "Интеграция - успех", подключаем аккаунт Пинкит и выбираем интеграцию, настроенную нами ранее.

2.3.2. Шаг 2: Инструменты

Инструмент "Получить комментарии из портала, откуда выгружаем"

Используем API-запрос GET-методом с указанием URL: /task.commentitem.getlist.json?TASKID={{source.int6551.source.id}}&order[POST_DATE]=asc.

Инструмент "Для каждого комментария"

Используем инструмент "Для каждого", Название поля - step1.result.

Инструмент "Убрать теги из комментария"

Используем инструмент "Замена по регулярному выражению", Название поля - step2.POST_MESSAGE, Регулярное выражение - /\[USER=\d+\](.*?)\[\/USER\]/.

Инструмент "Есть ли вложения"

Используем тип шага "Если-иначе", Название поля - step2.ATTACHED_OBJECTS, Условие - "Существует", Результат при успешной проверке - 1, Результат при неуспешной проверке - 0.

Инструмент "Отфильтровать файл"

Используем фильтр элементов массива, Условие выполнения - step5, Название поля - step2.ATTACHED_OBJECTS|default(), Название поля внутри элемента массива - DOWNLOAD_URL, Условие - "Не пустое значение".

Инструмент "Развернутая информация о вложениях"

Используем API-запрос GET-методом с указанием URL: /disk.attachedObject.get?id={{step6.0.ATTACHMENT_ID}}, Условие выполнения - step5.

Инструмент "Скачать файл"

Используем инструмент "Скачать файл", API-запрос GET-методом с указанием URL:{{step7.result.DOWNLOAD_URL}}, Условие выполнения - step5.

Инструмент "Загрузить файл на диск в Хранилище группы"

Используем API-запрос POST-методом с указанием URL: /disk.storage.uploadfile.

Тело запроса:

{

"id": {{source.int6551.step6.result.0.ID}},

"fileContent": ["file", "{{step8|get_http_content()|base64_encode()}}"],

"data": {"NAME": "{{step7.result.NAME|default()}}"},

"generateUniqueName": true

}

Условие выполнения - step5.

Инструмент "Закрепить файл или нет"

Используем инструмент "Если-Иначе", название поля - step5, Условие - "ЧислоРавно", Сравниваемое значение - 1, Результат при успешной проверке - n{{step9.result.ID|default()}}, результат при неуспешной проверке - {{step9.result.ID|default()}}.

2.3.3. Шаг 3: Куда

Куда отправляем данные - Битрикс24, Какое действие совершаем - "Задача - добавить комментарий", указываем пользователя, от чьего имени будут добавлены комментарии.

2.3.4. Шаг 4: Сопоставление данных

Настраиваем сопоставление:

ID задачи - {{source.int6551.result.result.task.id}}

Текст комментария - от: {{step2.AUTHOR_NAME}}

{{step4}}

И пользовательское сопоставление:

Файл в комментарий

Тип: Тело

Название параметра: fields.UF_FORUM_MESSAGE_DOC.0

Значение параметра: {{step10}}

2.3.5. Шаг 5: Запуск

Запускаем интеграцию.

2.4. Интеграция "Задача. Добавить название чек-листа"

2.4.1. Настройка 1 шага выполняется аналогично предыдущей интеграции.

2.4.2. Шаг 2: Инструменты

Инструмент "Получить чек-листы Задачи"

Используем API-запрос GET-методом с указанием URL: /task.checklistitem.getlist?TASKID={{source.int6551.source.id}}

Инструмент "Чек-листы есть?"

Тип шага - "Проверка", Название поля - step1.result, Условие - "Пустое значение", Действие - "Прервать, если проверка пройдена".

Инструмент "Отфильтровать заголовок чек-листа"

Инструмент - "фильтр элементов массива", Название поля - step1.result, Название поля внутри элемента массива - PARENT_ID, Условие - "ЧислоРавно".

Инструмент "Для каждого заголовка чек-листа"

Тип шага - "Для каждого", Название поля - step3.

2.4.3. Шаг 3: Куда

Выбираем Битрикс24, действие - "Создать элемент чек-листа", подключаем доступ к коробке.

2.4.4. Шаг 4: Сопоставление данных

Сопоставляем данные следующим образом:

ID задачи - {{source.int6551.result.result.task.id|default()}}

Название - {{step4.TITLE}}

Завершено? (Y/N) - {{step4.IS_COMPLETE}}

Важное? (Y/N) - {{step4.IS_IMPORTANT}}

И пользовательское сопоставление:

PARENT_ID

Тип: Тело

Название параметра: FIELDS.PARENT_ID

Значение параметра: 0

2.4.5. Запускаем интеграцию

2.5. Интеграция "Пункты чек-листа""

2.5.1. Шаг 1 аналогичен описанному выше, только интеграцию указываем по чек-листам.

2.5.2. Шаг 2: Инструменты

Инструмент "Отфильтровать чек-листы"

Используем фильтр элементов массива, Название поля - source.int6690.step1.result, Название поля внутри элемента массива -PARENT_ID, Условие - ЧислоРавно, Сравниваемое значение -source.int6690.step3.0.ID.

Инструмент "Для каждого пункта"

Тип шага - "Для каждого", Название поля - step1.

2.5.3. Шаг 3: Куда

Выбираем Битрикс24, действие - "Создать элемент чек-листа", подключаем доступ к коробке.

2.5.4. Шаг 4: Сопоставление данных

Настраиваем сопоставление:

ID задачи - {{source.int6551.result.result.task.id}}

Название - Тест

Завершено? (Y/N) - {{step2.IS_COMPLETE}}

Важное? (Y/N) - {{step2.IS_IMPORTANT}}

Дополнительное тело запроса:

{

    "FIELDS": {

        "TITLE": "{{step2.TITLE}}"

    }

}

Пользовательское сопоставление:

PARENT_ID

Тип: Тело

Название параметра: FIELDS.PARENT_ID

Значение параметра: {{source.int6690.result.result|default()}}

SORT_INDEX

Тип: Тело

Название параметра: FIELDS.SORT_INDEX

Значение параметра: {{step2.SORT_INDEX}}

2.5.5. Шаг 5: Запуск

Запускаем интеграцию.

2.6. Интеграция "Учёт рабочего времени"

2.6.1. Шаг 1 аналогичен описанному выше, выбираем самую первую интеграцию.

2.6.2. Шаг 2: Инструменты

Инструмент "Получить тайминг по задаче"

Используем API-запрос GET-методом с указанием URL: /task.elapseditem.getlist?TASKID={{source.int6551.source.id}}

Инструмент "Для каждого тайминга"

Тип шага - "Для каждого", Название поля - step1.result.

Инструмент "Сопоставить пользователей"

Используем сопоставление данных по названию поля step2.USER_ID.

2.6.3. Шаг 3: Куда

Выбираем Битрикс24, действие - "Добавить запись учета времени".

2.6.4. Шаг 4: Сопоставление данных

Сопоставляем данные:

Идентификатор задачи - {{source.int6551.result.result.task.id|default()}}​

Длительность (секунд) - {{step2.SECONDS}}

Комментарий - {{step2.COMMENT_TEXT}}

Пользователь - {{step3}}

Время создания - {{step2.CREATED_DATE}}

2.6.5. Запускаем.

3. Резюмируем

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

Регистрируйтесь по ссылке: https://lk.pinkit.io/register в личном кабинете Пинкит и тестируйте интеграции переноса облака в коробку самостоятельно по нашей инструкции или с нашей помощью.

Алексей Окара,
основатель Пинол и продакт-менеджер Пинкит