Как написать кастомную активити для бизнес-процесса для облачного Битрикс24

    На зимней партнерской конференции 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-ошибок на сервере».
    AdBlock has stolen the banner, but banners are not teeth — they will be back

    More
    Ads

    Comments 2

      +2
      Спасибо Юля, как всегда кратко и по существу.
        0
        Ого, официальная дока ведет на эту статью) Я думал, вы просто на тостере тусуетесь, а вы прямо официальный реферант=)

        Only users with full accounts can post comments. Log in, please.