На зимней партнерской конференции 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 Структура приложения
В самом файле-приложении, прежде всего, необходимо сформировать скелет — структуру страницы приложения.
Данный скелет сразу можно подключить в тестовом портале как будет описано ниже и начать наращивать и отлаживать. Когда мы будем менять что-то в коде приложения на нашем сервере — переподключать приложение на стороне Битрикс24 не нужно — достаточно просто перезагрузить страницу приложения.
2 Какие данные мы получаем и как их проверить
Когда наша кастомная активити будет вызвана в составе бизнес-процесса — нашему приложению что-то придет в массиве $_REQUEST.
Значения параметров активити, заданные в ходе выполнения бизнес-процесса, будут доступны нам в $_REQUEST['properties'].
В массиве $_REQUEST['auth'] будут данные для авторизации, которые нужно будет использовать, посылая запросы к REST-апи Битрикс24.
Естественно, нужно проверять содержимое массива $_REQUEST на предмет соответствия пришедших данных формату данных, которые мы ожидаем получить. Какую-то минимальную проверку данных можно организовать, используя нехитрые функции:
Можно (и нужно) использовать и более сложные проверки с использованием регулярных выражений, но данный пост не о них.
3 Использование REST-api Битрикс24 на php
Далее нам понадобится php-функция, которая посредством curl будет посылать запросы к Битрикс24:
Если нам нужно будет вызвать rest-апи Битрикс24 из php-кода — мы далее можем использовать данную функцию:
4 Метод отладки приложения
Сразу встает вопрос: а как отлаживать наше приложение? Оно же выполняется у нас на сервере — значит мы можем смело все логировать в какой-то файл. Можно, например, использовать функции php fopen, fwrite, fclose. Ну а у нас на сервере тоже стоит Битрикс, поэтому нам нравится использовать функцию AddMessage2Log из битрикс-фреймворка (предварительно подключив заголовок).
5 Использование REST-api Битрикс24 на javascript
Мы можем вызывать rest-апи битрикс24 и через javascript. Следующим образом:
6 Создание и удаление простого активити
В частности нам нужны 2 javaскрипт обработчика для установки и удаления нашей активити (в данном примере мы создаем для облачного Битрикс24 активити, которая запрашивает идентификатор пользователя и возвращает бизнес-процессу его данные: телефон, skype и должность):
7 Логирование запросов и ответов на javascript
Если мы планируем размещать наше приложение в Маркетплейс Битрикс24, мы обязаны логировать все запросы и все ответы от Битрикс24 — не только те, которые посылаем из php-кода, но и те, которые мы посылаем из javascript
Если у нас на сервере тоже стоит Битрикс, можно использовать функции js библиотеки битрикс-фреймворка.
Скрипт-логгер, который мы дергаем по аяксу из нашего javascript может выглядеть так:
8 Не забыть вернуть ответ бизнес-процессу
Если объявляя активити, мы задали параметр 'USE_SUBSCRIPTION':'Y' мы обязаны вернуть бизнес-процессу ответ, соответсвующий описанному для активити массиву выходных параметров RETURN_PROPERTIES. Для этого используем rest-api bizproc.event.send
9 Добавление приложения в портал
Чтобы добавить приложение в портал Битрикс24, его не обязательно публиковать в Маркетплейсе — можно добавить его только в свой портал — для использования только в этом портале. Для этого в левом меню облачного Битрикс24 выбираем пункт «Добавить приложение», далее выбираем «Для личного использования».
В открывшейся форме указываем название приложение, название пункта меню, указываем, права на доступ к каким подсистемам необходимы приложению. Если наше приложение добавляет активити в бизнес-процесс, то необходимо отмечать галку Бизнес-процессы. Указываем ссылку на файл приложения, лежащий на нашем сервере.
Добавленное приложение появляется в списке локальных приложений и в меню приложений.
На странице приложения в портале Битрикс24 у нас 2 кнопки, обработчики которых описаны в посте ранее. Одна кнопка устанавливает нашу кастомную активити, вторая — удаляет.
После установки активити появлется в редакторе бизнес-процесса.
Кастомную активити можно включить в бизнес-процесс, задать ей те входные параметры, которые мы определили, как входные, и она будет работать.
10 Что будет, если удалить кастомную активити, которая включена в бизнес-процесс?
В этом случае бизнес-процесс перестанет отрабатывать корректно, а в редакторе бизнес-процесса данная активити будет подсвечена красным цветом.
Использованные материалы:
1) Видеозапись мастер-класса по созданию БП с использованием REST;
2) Учебный курс «Разработчик Bitrix Framework», глава «Маркетплейс Битрикс24»;
3) Пост в Блоге Антона Долганина «Логирование JS-ошибок на сервере».
Изучив указанные материалы и опробовав их на своих проектах, мы составили для себя простую и подробную памятку действий по разработке активити для облачного Битрикс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-ошибок на сервере».
Diden05
Спасибо Юля, как всегда кратко и по существу.