Описание разработки.
Демо - пример работы с REST API Битрикс24. Тип - Расширение.
Назначение: создание задач Битрикс24 из данных произвольного документа "Задача" в базе 1С.
Умеет работать с описанием, содержащим вложенные картинки, заполнять пользовательские поля задач, размещать задачи в группах/проектах/коллабах; после создания задачи доступно добавление комментариев к ней из формы документа 1С.
Создание задачи производится от лица Пользователя-"робота" Битрикс24. Сопоставление остальных пользователей 1С с пользователями Битрикс производится по адресам электронной почты, указанных в Контактной информации пользователя 1С.
Поддерживаются все конфигурации 1С, основанные на БСП 3.1. Расширение разработано на основе Демонстрационной версии Библиотеки Стандартных подистем, редакция 3.1 (https://its.1c.ru/db/metod8dev/content/5856/hdoc)
Раздел 1. Настройка пользователя Битрикс24: получение токена вебхука и настройка прав
Первым этапом настройки интеграции является подготовка портала Битрикс24.
Для обеспечения безопасного и легитимного обмена данными системе 1С необходимо предоставить «ключ доступа» (токен вебхука, созданного от имени определенного Пользователя Бтирикс).
Процесс начинается с создания в Битрикс24 специального пользователя, например, «Робот 1С», которому делегируются права на выполнение строго определенных операций. Наша интеграция обращается к функционалу Битрикс с помощью вебхука.
Как создать вебхук: https://apidocs.bitrix24.ru/local-integrations/local-webhooks.html
При создании входящего вебхука обязательно должны быть отмечены следующие права (scopes):
disk(для работы с файлами),- user (для запроса данных пользователей);
sonet_group(для привязки создаваемой задачи к рабочим группам, коллабам, проектам);task(непосредственно для создания и изменения задач);user.userfield(для работы с пользовательскими полями, если потребуется расширить карточку задачи).
Полученный код вебхука (URL токена) сохраняем куда-нибудь в секретное место. Чуть позже мы его внесем в настройки пользователя "робота" обработки 1С.
2. Следующим этапом - можно создать парочку "пользовательских полей" (https://helpdesk.bitrix24.ru/open/2573061/). Можно и не создавать, впрочем.
Раздел 2. Запуск обработки «Настройка интеграции Битрикс» и ввод первичных данных
После создания технических учетных записей наступает этап Настройки. В расширение входит общая форма «Настройка интеграции Битрикс». Откроем её.
Порядок настройки:
- Вводим Адрес портала своего Битрикс24, Идентификатор пользователя Битрикс, и Токен вебхука, полученный ранее.
- Нажимаем кнопку "Обновить". После этого в табличные части будут автоматически "подтянуты" сведения о группах Битрикс, доступных пользователю, хранилищах файлов, а также - составу пользовательских полей задач. После этого:
- ТЧ "Группы": Указываем галочкой группу, в которую по умолчанию будут попадать создаваемые задачи.
- ТЧ "Пользовательские поля": галочкой указываем пользовательские поля, которые должны быть заполнены при создании задачи. При этом необходимо выбрать из списка, каким значением ("Значение заполнения") будет заполняться каждое из них. (В целях безопасности использования, значения предопределены , но никто не мешает дополнить этот список).
- ТЧ "События": указываем Состояние, которое будет назначено документу в 1С после создания задачи Битрикс. Например - "Закрыто".
- Жмём "Сохранить". Сохранение настроек производится в Безопасном хранилище конфигурации. (https://its.1c.ru/db/v8std/content/740/hdoc) Мы же не используем в коде "магические строки", ведь так? (*мем с Падме)
Раздел 3. Создание "задачи" в информационной базе на основании "обращения" пользователя.
Используем стандартную бизнес-логику: "Обращение"-"Задача".
Создаем в 1С документ «Обращение (демо)» . Для упрощения тестирования, текстовое описание будет заполнено автоматически (текстом и картинкой) при первом открытии.
Сохраняем "Обращение", и на его основании создаем документ "Задача (демо)".
Раздел 4. Создание задачи Битрикс24 из формы Документа.
В дополнительном командном интерфейсе ("Ещё") формы "Задачи" появилась кнопка "(Битрикс24) Создать задачу".
Нажимаем, подтверждаем.
Что происходит "под капотом":
// Создает задачу в Битрикс24 по исходящим данным из Задачи в Информационной Базе
// Параметры:
// ИсточникСсылка - Ссылка на документ Задачи в информационной базе
// ПараметрыАвторизации - Структура - Структура параметров пользователя. Ключи структуры:
// *АдресПортала - Строка - Адрес портала Б24
// *Идентификатор - Число - ИД пользователя Б24
// *ВебХук - Строка - токен входящего вебхука Б24
// СтруктураВозвратныхПараметров - Структура - возвратный параметр. Используется для результатов создания задачи
Процедура СоздатьЗадачуБитрикс24(ИсточникСсылка, ПараметрыАвторизации=Неопределено, СтруктураВозвратныхПараметров=Неопределено) Экспорт
// Признак, означающий, что на каком-то этапе произошла ошибка
Перем Ошибка;
Ошибка = Ложь;
ТелоЗапроса = НовыеПараметрыСозданияЗадачи(); // Формируем "пустое" тело запроса
// 0. Настройки пользователя Битрикс24 по умолчанию - Робот для создания и менеджмента Задач Битрикс
Если ПараметрыАвторизации = Неопределено Тогда
ПараметрыАвторизации = ПараметрыАвторизацииРоботаБитрикс24();
КонецЕсли;
// 1. Запросом достаем данные документа, представляем Описание как совокупность Строки и Массива присоединенных Файлов
ДанныеДокумента = ПолучитьДанныеДляСозданияЗадачиБитрикс24(ИсточникСсылка);
МассивОписанийПрисоединяемыхФайлов = Новый Массив;
ЗаполнитьПараметрыЗадачи(ТелоЗапроса, ДанныеДокумента, МассивОписанийПрисоединяемыхФайлов);
// 2. Грузим файлы в хранилище Битрикс, получаем идентификаторы файлов
ЗагрузитьПрисоединенныеФайлыЗадачиБитрикс24(МассивОписанийПрисоединяемыхФайлов, ПараметрыАвторизации, ТелоЗапроса, Ошибка);
// 3. Готовим текст Описания Задачи Битрикс с учетом загруженных файлов
ЗаполнитьИдентификаторыФайловВОписанииЗадачи(МассивОписанийПрисоединяемыхФайлов,ТелоЗапроса);
// 4. Вызываем универсальный метод "Отправить запрос". В этот раз от него требуется создать нам
// Задачу Битрикс.
МетодAPI = "tasks.task.add";
МетодHTTP = "POST";
ОтветHTTPСервиса = ОтправитьЗапрос(МетодHTTP,МетодAPI,ПараметрыАвторизации,,ТелоЗапроса);
// 5. Если запрос вернул код ошибки HTTP, отобразить ошибку сервиса Пользователю.
Если ОтветHTTPСервиса.Получить("Ошибка") Тогда
Ошибка=Истина;
ОтобразитьОшибкуHTTPСервиса(ОтветHTTPСервиса);
// 6. Если Задача создана успешно, готовим данные для отображения результата Пользователю. Например,
// разместим в документе 1С ссылку на задачу Битрикс.
Иначе
// 6.1 Собрать ссылку на созданную задачу
СсылкаНаЗадачу="";
Попытка
СсылкаНаЗадачу=СтрШаблон("https://%1/company/personal/user/%2/tasks/task/view/%3/",
ПараметрыАвторизации.АдресПортала,
ПараметрыАвторизации.Идентификатор,
ОтветHTTPСервиса.Получить("Ответ").Получить("result").Получить("task").Получить("id"));
Исключение
Ошибка=Истина;
КонецПопытки;
// 6.2 Обработчик "При создании задачи Битрикс24" вносит сведения о результатах в
// документ 1С, и устанавливает соотв. Статус
ДополнительныеПараметры = Новый Структура;
ДополнительныеПараметры.Вставить("СсылкаНаЗадачуБитрикс24",СсылкаНаЗадачу);
ДополнительныеПараметры.Вставить("УстановитьСостояниеЗадачи",ПараметрыАвторизации.УстановитьСостояниеЗадачи);
ДанныеОтветаHTTP = ОтветHTTPСервиса.Получить("Ответ");
ПриСозданииЗадачиБитрикс24(ИсточникСсылка, ДанныеОтветаHTTP, ДополнительныеПараметры);
КонецЕсли;
// 7. Вернуть ответ о статусе создания задачи
СтруктураВозвратныхПараметров.Вставить("Ошибка", Ошибка);
КонецПроцедуры
Для правильной загрузки картинок нам потребуется выполнить три подзадачи:
1. Извлечение двоичных данных картинок из Описания Задачи ИБ и замена их в тексте временными "якорями".
2. Предварительная загрузка извлеченных в п1. файлов в Битрикс24, получение их идентификаторов (Номеров).
3. Формирование текста Описания задачи Битрикс24:
- перенос текста, преобразование форматирования из тегов HTML - в BBCodes, которые используются в Б24;
- замена наших "якорей" на специальный BBCode для отображения картинок внутри текста. Так в Описании задачи Битрикс появятся привычные глазу "inline"-картинки.
4. Получение и обработка ответа API Битрикс. Создаем и отображаем на форме кликабельную гиперссылку на задачу Битрикс. Устанавливаем требуемое Состояние документа 1С.
Раздел 5. Добавление комментариев в задачу Битрикс24 из формы документа 1С.
После успешного создания задачи Битрикс, на форме документа станет видимой вкладка "Общение": страница, в которой находятся табличная часть и поле ввода комментария с кнопкой "Добавить".
Комментарии к существующим задачам добавляются методом "task.commentitem.add". Пример применения ниже:
// 0. Валидация переданных параметров
// Настройки пользователя Битрикс24 по умолчанию - Робот для создания и менеджмента Задач Битрикс
Если ПараметрыАвторизации = Неопределено Тогда
ПараметрыАвторизации = ПараметрыАвторизацииРоботаБитрикс24();
КонецЕсли;
Если НЕ ТипЗнч(СтруктураКомментария)= Тип("Структура") Тогда
ВызватьИсключение("Не передана Структура данных для комментария",КатегорияОшибки.ПрочаяОшибка);
КонецЕсли;
// 4. Вызываем универсальный метод "Отправить запрос". Пусть добавит нам комментарий.
МетодAPI = "task.commentitem.add";
МетодHTTP = "POST";
// 5. Отправить запрос
ОтветHTTPСервиса = ОтправитьЗапрос(МетодHTTP,МетодAPI,ПараметрыАвторизации,,ТелоЗапроса);
// 5. Если запрос вернул код ошибки HTTP, отобразить ошибку сервиса Пользователю.
ИдентификаторКомментария=Неопределено;
ДатаВремяКомментария = Дата(1,1,1);
Если ОтветHTTPСервиса.Получить("Ошибка") Тогда
Ошибка=Истина;
ОтобразитьОшибкуHTTPСервиса(ОтветHTTPСервиса);
Иначе
// 6. Если запрос выполнен успешно, готовим данные для отображения результата Пользователю.
СодержимоеОтвета = ОтветHTTPСервиса.Получить("Ответ");
ИдентификаторКомментария = СодержимоеОтвета.Получить("result");
ДатаВремяКомментария = СодержимоеОтвета.Получить("time").Получить("date_finish");
КонецЕсли;
// 7. Вернуть ответ о статусе созданного комментария
СтруктураРезультатМетода.Вставить("Ошибка", Ошибка);
СтруктураРезультатМетода.Вставить("ИдентификаторКомментария", ИдентификаторКомментария);
СтруктураРезультатМетода.Вставить("ДатаВремя", ДатаВремяКомментария);
Возврат СтруктураРезультатМетода;
После успешного добавления комментария, он будет отражен и в табличной части "Общение" на стороне документа 1С, при этом будет учтен и его номер, для последующих обращений и, быть может, удаления/редактирования.
6. А что мы видим на портале:
- задача помещена в определенную нами группу (коллабу)
- заполнились пользовательские поля, которые мы указали в настройках ранее;
- в наблюдатели добавились: "Робот", который создал саму задачу, и Пользователь, который создал оригинальное Обращение в 1С.
- Файлы, переданные в Обращении, приложены к задаче Битрикс.
- комментарии от лица пользователей - добавлены в задачу.
7. Заключение
В этом демонстрационном примере мы не только приятно провели 20 минут свободного времени, но и собрали несколько наиболее употребимых методов API "Битрикс24" в одной конфигурации.
Буду признателен за обратную связь в комментариях!
Проверено на следующих конфигурациях и релизах:
- 1С:Библиотека стандартных подсистем, редакция 3.1, релизы 3.1.11.461
- Управление торговлей, редакция 11, релизы 11.5.22.80
Вступайте в нашу телеграмм-группу Инфостарт