← Назад к справке

Пользовательские действия

Общее устройство

Как устроены пользовательские действия бизнес-процессов в коробочном Bitrix24: где лежат, из каких файлов состоят и как появляются в дизайнере.

Пользовательское действие имеет смысл делать тогда, когда PHP-блок разросся, повторяется в разных шаблонах или должен выглядеть для сотрудников как обычный блок дизайнера бизнес-процессов.

Общее понимание

Пользовательское действие — это отдельный блок бизнес-процесса со своим PHP-классом, описанием, настройками и результатами выполнения.

Когда нужно своё действие

  • один и тот же PHP-код копируется в разные бизнес-процессы;
  • нужно скрыть сложную реализацию за понятной формой настроек;
  • нужен готовый блок для сотрудников в дизайнере;
  • нужно возвращать несколько результатов отдельными полями;
  • нужна динамическая форма: выбор CRM-сущности, списки полей, AJAX-подгрузка;
  • логику нужно сопровождать в одном месте, а не искать её по шаблонам процессов.

Чем отличается от PHP-блока

Вариант Где подходит Ограничение
PHP-блок Разовая проверка, короткая логика, быстрый служебный код. Код легко размножить по шаблонам и сложно потом поддерживать.
Пользовательское действие Повторяемая логика, своя форма настроек, готовый блок в дизайнере. Нужно завести структуру файлов и поддерживать совместимость свойств.

Если действие уже добавлено в реальные шаблоны, коды свойств и результатов лучше не переименовывать без необходимости. Шаблон бизнес-процесса хранит именно эти коды.

Где хранить

Для своих действий используется /local/activities. Файлы ядра в /bitrix/modules/bizproc/activities не меняются.

Путь Комментарий
/local/activities/crmadvancedfindactivity Рабочий путь для своего действия в коробке.
/local/activities/custom Вариант с общей папкой для своих действий, если так принято в проекте.
/bitrix/activities/custom Старый путь из примеров и документации.
/bitrix/modules/bizproc/activities Ядро. Для своих правок не используется.

Именование

Папка и основной файл называются по действию в нижнем регистре. Класс начинается с CBP, а в описании указывается имя без этого префикса.

Что Пример
Папка действия crmadvancedfindactivity
Основной файл crmadvancedfindactivity.php
Класс CBPCrmAdvancedFindActivity
CLASS в описании CrmAdvancedFindActivity

Рабочая схема

Минимальному действию нужны описание, PHP-класс и языковые файлы. Для сложной формы добавляются properties_dialog.php и AJAX.

Минимальная структура

/local/activities/crmadvancedfindactivity/
├── .description.php
├── crmadvancedfindactivity.php
├── properties_dialog.php
├── ajax.php
└── lang/
    └── ru/
        └── .description.php

В простом действии можно обойтись без properties_dialog.php и ajax.php. В действии с выбором CRM-сущности, фильтрами и подгрузкой полей эти файлы уже нужны.

Назначение файлов

Файл Назначение
.description.php Название, описание, категория, класс, входные свойства и результаты.
crmadvancedfindactivity.php Класс действия, Execute(), обработка настроек и результатов.
properties_dialog.php HTML и JS формы настроек в дизайнере бизнес-процессов.
ajax.php Подгрузка полей CRM, значений списков и элементов для привязок.
lang/ru/.description.php Языковые фразы для названия и описания.

Как блок появляется в дизайнере

Дизайнер читает .description.php. В этом файле задаются название, тип, класс, JS-класс и категория. 

<?php

if (!defined('B_PROLOG_INCLUDED') || B_PROLOG_INCLUDED !== true) {
    die();
}

$arActivityDescription = [
    'NAME' => 'CRM: расширенный поиск элемента',
    'DESCRIPTION' => 'Ищет первый элемент CRM или смарт-процесса с наименьшим ID по выбранным полям.',
    'TYPE' => 'activity',
    'CLASS' => 'CrmAdvancedFindActivity',
    'JSCLASS' => 'BizProcActivity',
    'CATEGORY' => [
        'ID' => 'document',
        'OWN_ID' => 'crm',
        'OWN_NAME' => 'CRM',
    ],
];

Если блока нет в дизайнере, обычно проверяют путь, имя папки, имя класса, ошибки PHP и кеш административного раздела.

Источники