Битрикс24: Автоматизация заполнения пользовательских полей в задаче при помощи REST API

Битрикс24 - система управления взаимоотношениями с клиентами с очень широким функционалом, позволяющая держать руку на пульсе компании, выстраивать бизнес-процессы и отслеживать все, что происходит в вашем бизнесе. Стандартный спектр возможностей, которые охватывает Битрикс24 довольно широк, но иногда его не хватает. В этом случае для расширения стандартного функционала можно использовать открытый Rest API Битрикс24, который позволяет существенно расширить стандартные возможности CRM. В этой статье мы рассмотрим случай, когда необходимо расширить стандартный функционал задач, добавив в него дополнительные пользовательские поля. 

Однажды к нам обратились с просьбой расширить существующий функционал корпоративного портала Битрикс24 Энтерпрайз-250 - некоторым сотрудникам компании нужно было видеть в списке задач результат выполнения задачи и иметь возможность выгружать этот результат в Excel. Нужно отметить то, что результатов выполнения одной задачи может быть несколько, это важно для дальнейшей разработки.

Постановка задачи

Задача: сделать так, чтобы при закрытии задачи через мобильное приложение результат выполнения задачи прописывался дополнительно в пользовательское поле. Это нужно для того, чтобы в дальнейшем пользовательское поле можно было вывести в списке задач и экспортировать в Excel для внутренних нужд компании.

Решение задачи

Вебхуки в Битрикс24

Расширить стандартные возможности задач можно различными способами, один из них - использовать исходящие вебхуки. Исходящий вебхук в Битрикс24 - это механизм для расширения системных функций корпоративного портала, работа которого основана на реакции сторонних приложений при изменении событий внутри системы. Работа вебхука заключается в приёме и фиксации ключа автоматизации, который связывает корпоративный портал и внешний софт. Иными словами, вебхук позволяет получать данные о том или ином событии, происходящем в CRM почти что в реальном времени, сразу после возникновения события. Например в момент сохранения задачи срабатывает событие onupdate. Если вебхук зарегистрирован, на указанный адрес будут отправлены данные (запрос), содержащие в себе идентификатор и другие параметры задачи.

Исходящий вебхук

Создаем исходящий вебхук. Для этого в портале перейдем в раздел "Разработчикам" - "Другое" и жмем кнопку "Исходящий вебхук".

Создание исходящего вебхука в Битрикс24

В форме создания исходящего вебхука указываем URL обработчика и События, при которых данные будут отправляться на указанный URL. Выбираем только то, что нам нужно - это событие возникающее при обновлении задачи - ONTASKUPDATE.

Входящий вебхук

Входящие вебхуки в Битрикс24 - это механизм, который активируется, если к порталу был запрос по заранее сформированной ссылке. Такие вебхуки поступают в Битрикс24 и позволяют автоматизировать выполнение каких-то действий внутри портала в ответ на внешние события. В нашем решении потребуются входящие вебхуки для того, чтобы запрашивать данные по нашим задачам при дальнейшей обработке событий. Создаем входящий вебхук: в левом меню находим раздел "Разработчикам" - "Другое" и жмем кнопку "Входящий вебхук". Сохраняем в текстовый документ или заметки содержимое поля "Вебхук для вызова rest api", в настройке прав указываем Задачи (task) и Задачи (tasks).

Создание входящего вебхука в Битрикс24

Пользовательские поля в Битрикс24

Пользовательские поля в Битрикс24 - это дополнительные поля, которые можно создать и настроить самостоятельно в различных модулях системы. В них можно хранить специфическую информацию, не предусмотренную стандартными полями системы. Пользовательские поля помогают:

  • Адаптировать систему под нужды бизнеса. Каждая компания уникальна, и стандартные инструменты могут не всегда соответствовать её требованиям.
  • Оптимизировать управление данными. С помощью пользовательских полей можно структурировать и организовать данные так, чтобы они находились в быстром доступе.
  • Повысить эффективность работы. Наличие всех необходимых данных в одном месте позволяет сократить время на поиск информации и улучшить качество обслуживания клиентов.

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

Добавим пользовательское поле под наши нужды, назовем его "Отчет". Для этого перейдем в раздел "Задачи и проекты" - "Еще" - "Шаблоны".

Список шаблонов задач Битрикс24

Шаблон задачи в Битрикс24 - это заранее созданный набор задач, который можно использовать для выполнения определённой работы. Он содержит все необходимые поля и параметры, которые позволяют ускорить процесс выполнения задачи. С помощью шаблона можно создавать однотипные задачи с уже готовым описанием, участниками, сроками и задавать периодичность их повторения.

Если шаблона нет - его нужно создать.

Как создать шаблон задачи

Для создания шаблона задачи переходим в "Задачи и Проекты" - "Еще" - "Шаблоны", нажимаем кнопку "Создать", заполняем требуемые поля и сохраняем шаблон.

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

Листаем вниз до раздела "Дополнительно", кликаем по нему и видим пункт "Пользовательские поля". Нажимаем "Добавить поле", указываем тип "Строка", называем его "Отчет" и жмем ниже кнопку сохранить.

Добавление пользовательского поля в шаблоне задачи Битрикс24

Теперь для дальнейшей разработки нам нужно узнать внутренний идентификатор созданного поля. Он генерируется на серверах Битрикс24 и изменить мы его не можем, но можем найти и использовать. Для этого воспользуемся инспектором кода, встроенным в браузер: наводим мышкой на созданное поле (только после сохранения !), жмем правой кнопкой мыши по нему, выбираем в выпадающем списке "Исследовать элемент". Ищем строчку, похожую на UF_AUTO_НАБОР_ЦИФР. Копируем это значение куда - то в блокнот или заметки. В нашем случае идентификатор поля - UF_AUTO_562334866463.

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

Поле отчета в списке задач

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

Вывод пользовательского поля Отчет в списке задач Битрикс24

Пишем обработчик входящего вебхука

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

define('WEBHOOK_URL','https://portal.bitrix24.ru/rest/1/hashkey/');  //Прописываем свой адрес входящего вебхука
$event = $_POST['event'];
if($event == 'ONTASKUPDATE') { //Условие по типу события
  $task_id = intval($_POST['data']['FIELDS_AFTER']['TASK_ID']); //Определяем идентификатор задачи
  if(!$task_id) $task_id = intval($_POST['data']['FIELDS_AFTER']['ID']); //Определяем идентификатор задачи, второй способ, если первый не сработал

  //Report resync result
  $res = bx_request(WEBHOOK_URL."/tasks.task.result.list?taskId=".$task_id); //Получаем данные по задаче
  if(isset($res['result']) && is_array($res['result']) && count($res['result']) > 0) { //Проверяем если есть зафиксированные результаты
    $results = array();
    foreach($res['result'] as $result) { //Собираем их в массив
      $results[] = trim($result['text']);
    }
    $result_string = trim(implode(",", $results)); //Через запятую из массива формируем строку, для передачи в поле Отчет

    $request = array(
      'taskId'    =>    $task_id,
      'fields'    =>    array(
        'UF_AUTO_562334866463'    =>    $result_string //Формируем запрос к API  портала, указываем что в наше поле нужно прописать строку с результатами
      )
    );
    $result = bx_request(WEBHOOK_URL.'/tasks.task.update', $request); //Отправляем запрос на обновление задачи
  }
}

function bx_request($req_url, $request = array()) { //Вспомогательная функция, для отправки запросов в Битрикс24
  $ch = curl_init($req_url);
  curl_setopt($ch, CURLOPT_URL,$req_url);
  curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
  curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 2);
  curl_setopt($ch,CURLOPT_RETURNTRANSFER,1);
  if(is_array($request) && count($request) > 0) {
    $json_request = json_encode($request);
    curl_setopt($ch, CURLOPT_POSTFIELDS, $json_request);
    curl_setopt($ch, CURLOPT_POST,1);
    curl_setopt($ch,CURLOPT_HTTPHEADER, array('Content-Length:'.strlen($json_request),'Content-Type: application/json'));
  }
  $result = curl_exec($ch);
  return json_decode($result,true);
}

Итог работы

В итоге, вот как целиком работает решение:

  1. Ответственный за задачу сотрудник в мобильном приложении, перед завершением задачи указывает результат в одноименном разделе.
  2. На указанный исходящий вебхук приходят данные о том, что задача обновлена (ONTASKUPDATE)
  3. Скрипт по идентификатору задачи получает данные задачи, проверяет, есть ли зафиксированные результаты.
  4. Если результаты есть, вытягиваем их в строку и формируем запрос на обновление созданного нами поля UF_AUTO_562334866463
  5. Данные появляются в поле "Отчет"