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

Бизнес-процессы

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

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

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

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

Свое действие — это PHP-класс, описание для дизайнера бизнес-процессов и, при необходимости, форма настроек.

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

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

Где хранить

Для коробочной разработки лучше начинать с /local/activities/custom, чтобы не менять ядро Битрикса.

Путь Комментарий
/local/activities Локальные действия.
/local/activities/custom Удобное место для своих действий.
/bitrix/activities/custom Старый вариант. Лучше не использовать, если можно хранить в /local.
/bitrix/modules/bizproc/activities Ядро модуля. Не место для своих правок.

Структура файлов

Название папки должно соответствовать названию класса без префикса CBP и быть в нижнем регистре. 

/local/activities/custom/writecommentactivity/
├── .description.php
├── writecommentactivity.php
└── lang/
    └── ru/
        ├── .description.php
        └── writecommentactivity.php

Для класса CBPWriteCommentActivity папка и основной файл называются writecommentactivity.

Пример действия

Минимальное действие, которое пишет текст в журнал бизнес-процесса.

.description.php

Файл описания сообщает дизайнеру название, описание, тип, класс и категорию действия. 

<?php

defined('B_PROLOG_INCLUDED') || die();

use Bitrix\Main\Localization\Loc;

$arActivityDescription = [
    'NAME' => Loc::getMessage('WRITE_COMMENT_ACTIVITY_NAME'),
    'DESCRIPTION' => Loc::getMessage('WRITE_COMMENT_ACTIVITY_DESCRIPTION'),
    'TYPE' => 'activity',
    'CLASS' => 'WriteCommentActivity',
    'JSCLASS' => 'BizProcActivity',
    'CATEGORY' => [
        'ID' => 'other',
    ],
];

Класс действия

Основная логика выполняется в методе Execute(). Для простого действия после успешного выполнения возвращается CBPActivityExecutionStatus::Closed. 

<?php

defined('B_PROLOG_INCLUDED') || die();

use Bitrix\Main\Localization\Loc;

class CBPWriteCommentActivity extends CBPActivity
{
    /**
     * Описывает свойства действия.
     */
    public function __construct($name)
    {
        parent::__construct($name);

        $this->arProperties = [
            'Title' => '',
            'CommentText' => '',
        ];
    }

    /**
     * Выполняет действие.
     */
    public function Execute()
    {
        $comment_text = trim((string) $this->CommentText);

        if ($comment_text === '') {
            $comment_text = Loc::getMessage('WRITE_COMMENT_ACTIVITY_EMPTY_TEXT');
        }

        $this->WriteToTrackingService(
            $comment_text,
            0,
            \CBPTrackingType::Report
        );

        return CBPActivityExecutionStatus::Closed;
    }
}

Локализация

Языковые файлы лучше хранить отдельно, чтобы название действия и сообщения не были зашиты прямо в код. 

<?php

$MESS['WRITE_COMMENT_ACTIVITY_NAME'] = 'Записать комментарий';
$MESS['WRITE_COMMENT_ACTIVITY_DESCRIPTION'] = 'Записывает текст в журнал бизнес-процесса';
$MESS['WRITE_COMMENT_ACTIVITY_EMPTY_TEXT'] = 'Текст комментария не заполнен';

Для действия с настройками понадобится ещё properties_dialog.php. Этот блок лучше вынести в отдельную статью, когда понадобится полноценная форма настроек.

Источники