На зимней партнерской конференции 1C-Битрикс 2016г Олег Строкатый и Алексей Кирсанов показывали мастер-класс, в ходе которого разработали кастомную активити для бизнес-процесса под облачный Битрикс24. Информация по данной теме есть так же в курсе «Разработчик Bitrix Framework» (ссылки — в конце поста).
Изучив указанные материалы и опробовав их на своих проектах, мы составили для себя простую и подробную памятку действий по разработке активити для облачного Битрикс24, включающую в себя так же некоторые мелочи, которые в вышеуказанных источниках были недосказаны, видимо, в расчете на то, что у разработчика, изучающего их, уже есть определенный базис знаний. Этой памяткой я и хочу поделиться в данном посте.
Кастомная активити для облачного Битрикс24 реализуется как приложение так называемого «второго типа». То есть php-файл с обработчиком активити и с ее установщиком должен лежать где-то на внешнем web-сервере, а Битрикс24 будет обращаться к нему по определенному адресу, например,
https://ваш_домен/b24/название_активити/index.php
Именно этот адрес и используется для добавления приложения в портал, и для публикации приложения в маркетплейс Битрикс24.
1 С чего начать
1.1 SSL сертификат
Для корректной работы такого приложения домен должен обладать SSL сертификатом (минимум Domain Validation (DV) Certificate). Вести разработку и тестирования приложения можно и без SSL сертификата, но он понадобится для реальной работы приложения, поэтому о нем стоит позаботиться заранее.
1.2 Структура приложения
В самом файле-приложении, прежде всего, необходимо сформировать скелет — структуру страницы приложения.
<?php $protocol=$_SERVER['SERVER_PORT']=='443'?'https':'http'; $host=explode(':',$_SERVER['HTTP_HOST']); $host=$host[0]; define(‘BP_APP_HANDLER',$protocol.'://'.$host.$_SERVER['REQUEST_URI']); header('Content-Type: text/html; charset=UTF-8'); ?> <br/><br/> <!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8"> <title></title> </head> <body> <script src=«//api.bitrix24.com/api/v1/"></script> </body> </html> Данный скелет сразу можно подключить в тестовом портале как будет описано ниже и начать наращивать и отлаживать. Когда мы будем менять что-то в коде приложения на нашем сервере — переподключать приложение на стороне Битрикс24 не нужно — достаточно просто перезагрузить страницу приложения.
2 Какие данные мы получаем и как их проверить
Когда наша кастомная активити будет вызвана в составе бизнес-процесса — нашему приложению что-то придет в массиве $_REQUEST.
Значения параметров активити, заданные в ходе выполнения бизнес-процесса, будут доступны нам в $_REQUEST[‘properties’].
В массиве $_REQUEST[‘auth’] будут данные для авторизации, которые нужно будет использовать, посылая запросы к REST-апи Битрикс24.
Естественно, нужно проверять содержимое массива $_REQUEST на предмет соответствия пришедших данных формату данных, которые мы ожидаем получить. Какую-то минимальную проверку данных можно организовать, используя нехитрые функции:
<?php function clean($value = "") { $value = trim($value); $value = stripslashes($value); $value = strip_tags($value); $value = htmlspecialchars($value); return $value; } ?> <br/><br/> <?php function check_length($value = "", $min, $max) { $result = (mb_strlen($value) < $min || mb_strlen($value) > $max); return !$result; } ?> Можно (и нужно) использовать и более сложные проверки с использованием регулярных выражений, но данный пост не о них.
3 Использование REST-api Битрикс24 на php
Далее нам понадобится php-функция, которая посредством curl будет посылать запросы к Битрикс24:
<? function callB24Method(array $auth, $method, $params){ $c=curl_init('https://'.$auth['domain'].'/rest/'.$method.'.json'); $params["auth"]=$auth["access_token"]; curl_setopt($c,CURLOPT_RETURNTRANSFER,true); curl_setopt($c,CURLOPT_POST,true); curl_setopt($c,CURLOPT_POSTFIELDS,http_build_query($params)); AddMessage2Log($c, "demo_user_info"); $response=curl_exec($c); AddMessage2Log($response, "demo_user_info"); $response=json_decode($response,true); return $response['result']; } ?> Если нам нужно будет вызвать rest-апи Битрикс24 из php-кода — мы далее можем использовать данную функцию:
<?php $user_info=callB24Method($auth,'user.get',array( ‘ID’=>$ID ) ); //в данном примере user.get - rest-апи для получения данных о пользователе //в массиве $auth данные для авторизации - пример: //'auth' => // array ( // 'access_token' => 'numdjpxul1o8o5atfj5td4z73o8hhlds', // 'expires_in' => '3600', // 'scope' => 'user,bizproc', // 'user_id' => '1', // 'status' => 'L', // 'member_id' => '59f6a44727c5c05ae6f53b9dbea88c4f', // 'domain' => 'какое_то_имя.bitrix24.ru', // ), ?> 4 Метод отладки приложения
Сразу встает вопрос: а как отлаживать наше приложение? Оно же выполняется у нас на сервере — значит мы можем смело все логировать в какой-то файл. Можно, например, использовать функции php fopen, fwrite, fclose. Ну а у нас на сервере тоже стоит Битрикс, поэтому нам нравится использовать функцию AddMessage2Log из битрикс-фреймворка (предварительно подключив заголовок).
<?php define("LOG_FILENAME", $_SERVER[«DOCUMENT_ROOT»].»/__log_castom1_".date("Ymd").".txt»); AddMessage2Log($user_info, "demo_user_info"); ?> 5 Использование REST-api Битрикс24 на javascript
Мы можем вызывать rest-апи битрикс24 и через javascript. Следующим образом:
BX24.callMethod( 'bizproc.activity.add', //REST-api для добавления активити в БП params, function(result) { if (result.error()) alertify.alert('Error: '+result.error()); else alertify.alert('Installation successfully completed'); } ); 6 Создание и удаление простого активити
В частности нам нужны 2 javaскрипт обработчика для установки и удаления нашей активити (в данном примере мы создаем для облачного Битрикс24 активити, которая запрашивает идентификатор пользователя и возвращает бизнес-процессу его данные: телефон, skype и должность):
BX24.init(function() { }); function installActivity1() { var params={ 'CODE':'user_additional_info', //уникальный в рамках приложения код 'HANDLER':'<?=BP_APP_HANDLER?>', 'AUTH_USER_ID':1, 'USE_SUBSCRIPTION':'Y', //Y - если бизнесс-процесс должен ждать ответа приложения, N - если не должен ждать 'NAME':'Additional information from users card', 'DESCRIPTION':'Aktiviti gets information from the user cards', 'PROPERTIES':{ //Входные данные для активити 'User':{ 'Name':'User', 'Type':'user', 'Required':'Y', 'Multiple':'N', }, }, 'RETURN_PROPERTIES':{ //данные, которые активити будет возвращать бизнес-процессу 'PERSONAL_MOBILE':{ 'Name':'Users_PERSONAL_MOBILE', 'Type':'string', 'Required':'N', 'Multiple':'N', }, 'WORK_POSITION':{ 'Name':'Users_WORK_POSITION', 'Type':'string', 'Required':'N', 'Multiple':'N', }, 'UF_SKYPE':{ 'Name':'Users_UF_SKYPE', 'Type':'string', 'Required':'N', 'Multiple':'N', }, } } BX24.callMethod( 'bizproc.activity.add', params, function(result) { if (result.error()) alertify.alert('Error: '+result.error()); else alertify.alert('Installation successfully completed'); } ); } function uninstallActivity1(){ var params={ 'CODE':'user_additional_info' } BX24.callMethod( 'bizproc.activity.delete', params, function (result) { if (result.error()) alertify.alert('Error: '+result.error()); else alertify.alert('Uninstallathion successfully completed'); } ); } 7 Логирование запросов и ответов на javascript
Если мы планируем размещать наше приложение в Маркетплейс Битрикс24, мы обязаны логировать все запросы и все ответы от Битрикс24 — не только те, которые посылаем из php-кода, но и те, которые мы посылаем из javascript
Если у нас на сервере тоже стоит Битрикс, можно использовать функции js библиотеки битрикс-фреймворка.
BX.ajax.get('/b24/ajax/js_request_log.php', { params }); Скрипт-логгер, который мы дергаем по аяксу из нашего javascript может выглядеть так:
<?php require($_SERVER['DOCUMENT_ROOT'].'/bitrix/modules/main/include/prolog_before.php'); define('LOG_FILENAME', $_SERVER['DOCUMENT_ROOT'].'/ajax/js_error.txt'); $request = \Bitrix\Main\Context::getCurrent()->getRequest(); if ($request->get('data')) { AddMessage2Log(print_r($request->get('data'), true)); } ?> 8 Не забыть вернуть ответ бизнес-процессу
Если объявляя активити, мы задали параметр ‘USE_SUBSCRIPTION’:’Y’ мы обязаны вернуть бизнес-процессу ответ, соответсвующий описанному для активити массиву выходных параметров RETURN_PROPERTIES. Для этого используем rest-api bizproc.event.send
<?php callB24Method($auth,'bizproc.event.send',array( "EVENT_TOKEN"=>$event_token, "RETURN_VALUES"=>array( 'PERSONAL_MOBILE'=>$user_info[0]['PERSONAL_MOBILE'], 'WORK_POSITION'=>$user_info[0]['WORK_POSITION'], 'UF_SKYPE'=>$user_info[0]['UF_SKYPE'], ), "LOG_MESSAGE"=>'OK' )); ?> 9 Добавление приложения в портал
Чтобы добавить приложение в портал Битрикс24, его не обязательно публиковать в Маркетплейсе — можно добавить его только в свой портал — для использования только в этом портале. Для этого в левом меню облачного Битрикс24 выбираем пункт «Добавить приложение», далее выбираем «Для личного использования».
В открывшейся форме указываем название приложение, название пункта меню, указываем, права на доступ к каким подсистемам необходимы приложению. Если наше приложение добавляет активити в бизнес-процесс, то необходимо отмечать галку Бизнес-процессы. Указываем ссылку на файл приложения, лежащий на нашем сервере.
Добавленное приложение появляется в списке локальных приложений и в меню приложений.
На странице приложения в портале Битрикс24 у нас 2 кнопки, обработчики которых описаны в посте ранее. Одна кнопка устанавливает нашу кастомную активити, вторая — удаляет.
После установки активити появлется в редакторе бизнес-процесса.
Кастомную активити можно включить в бизнес-процесс, задать ей те входные параметры, которые мы определили, как входные, и она будет работать.
10 Что будет, если удалить кастомную активити, которая включена в бизнес-процесс?
В этом случае бизнес-процесс перестанет отрабатывать корректно, а в редакторе бизнес-процесса данная активити будет подсвечена красным цветом.
Использованные материалы:
1) Видеозапись мастер-класса по созданию БП с использованием REST;
2) Учебный курс «Разработчик Bitrix Framework», глава «Маркетплейс Битрикс24»;
3) Пост в Блоге Антона Долганина «Логирование JS-ошибок на сервере».
ссылка на оригинал статьи https://habrahabr.ru/post/279477/
Добавить комментарий