Конфигурируемое дело в Timeline crm Bitrix24

Начиная с версии 23.0.0 Bitrix24 обзавелся возможностью добавления собственных дел в элементах CRM, с возможностью конфигурирования и отображения нужной для пользователя информации. В документации сказано, что работа с данным функционалом возможна только в контексте Rest приложения, но мы попробуем добавить дело по старинке.

Я не буду в мелочах и подробностях расписывать все свойства и возможности кастомных дел, так как это есть в официальной документации с примерами и картинками(правда пока что только по Rest, но мы сильные и мы справимся). Заместо этого продемонстрирую как вывести какую-то информацию в таймлайн. Прочие фичи буду рассматривать позже, если данная тема найдёт практическое применение и откликнется в ваших сердцах.

Что, зачем и почему?

Дела в timelin’е представляют собой элементы, содержащие информацию о работе с клиентом, сделкой, лидом и т.д. К ним можно отнести встречи, сообщения и звонки. Как уже было написано в анонсе к статье, Bitrix даёт возможность создавать свои собственные типы дел, которые могут внести ясность и понимание при работе с системой. Например, отображение информации доя ознакомления при смене стадии, напоминание специфического характера или же отображение данных из внешних систем.

Конфигурируемое дело состоит из нескольких элементов. Схематично можно его представить следующим образом.

Добавление дела

Для добавления конфигурируемого дела, нужно создать activity для определенного элемента определённой сущности CRM и передать в него объект layout.

use Bitrix\Main\Loader;
use Bitrix\Crm\Activity\Entity\ConfigurableRestApp;
use Bitrix\Crm\Activity\Entity\ConfigurableRestApp\Dto\LayoutDto;
use Bitrix\Crm\ItemIdentifier;

Loader::includeModule('crm');

$layout = [];

$layoutDto = new ConfigurableRestApp\Dto\LayoutDto($layout);

if (!$layoutDto->hasValidationErrors()) {

    $ownerId = 5303;
    $ownerTypeId = \CCrmOwnerType::Lead;

    $activity = new ConfigurableRestApp(new ItemIdentifier($ownerTypeId, $ownerId));

    $activity->setLayoutDto($layoutDto);
    $activity->setRestClientId(1);

    $saveResult = $activity->save();

    if (!$saveResult->isSuccess()) {
        // Ошибки сохранения дела
        $activityErrors = $saveResult->getErrors();
    }
} else {
    // Ошибки валидации макета дела
    $layoutErrors = $layoutDto->getValidationErrors()->toArray();
}

Этот код добавить (попытается добавить) конфигурированное дело в лид с идентификатором 5303. Добавление не произойдёт, так как не заполнен массив $layout, который должен содержать в себе описание представления дела и его логику. Ошибки отображаются во вполне понятном виде. Например, данный код запишет в массив $layoutErrors следующее:

array(3) {
  [0]=>
  object(Bitrix\Main\Error)#256 (3) {
    ["code":protected]=>
    string(17) "FIELD_IS_REQUIRED"
    ["message":protected]=>
    string(68) "Поле icon в LayoutDto должно быть заполнено."
    ["customData":protected]=>
    array(2) {
      ["FIELD"]=>
      string(4) "icon"
      ["PARENT_OBJECT"]=>
      string(9) "LayoutDto"
    }
  }
  [1]=>
  object(Bitrix\Main\Error)#258 (3) {
    ["code":protected]=>
    string(17) "FIELD_IS_REQUIRED"
    ["message":protected]=>
    string(70) "Поле header в LayoutDto должно быть заполнено."
    ["customData":protected]=>
    array(2) {
      ["FIELD"]=>
      string(6) "header"
      ["PARENT_OBJECT"]=>
      string(9) "LayoutDto"
    }
  }
  [2]=>
  object(Bitrix\Main\Error)#254 (3) {
    ["code":protected]=>
    string(17) "FIELD_IS_REQUIRED"
    ["message":protected]=>
    string(68) "Поле body в LayoutDto должно быть заполнено."
    ["customData":protected]=>
    array(2) {
      ["FIELD"]=>
      string(4) "body"
      ["PARENT_OBJECT"]=>
      string(9) "LayoutDto"
    }
  }
}

Из чего становится ясно, чего не хватает, а что заполнено не корректно. Давайте попробуем собрать простенький массив layout и посмотрим, что из этого получится.

$layout = [
    "icon" => [
        "code" => "document"
    ],
    "header" => [
        "title" => "Тестовое дело",
        "tags" => [
            "status" => [
                "type" => "warning",
                "title" => "Срочно!"
            ]
        ]
    ],
    "body" => [
        "logo" => [
            "code" => "document",
            "action" => [
                "type" => "redirect",
                "uri" => "/crm/deal/details/123/"
            ]
        ],
        "blocks" => [
            "block-title" => [
                "type" => "text",
                "properties" => [
                    "value" => "Тестовое дело",
                    "bold" => true,
                ]
            ],
            "block-description" => [
                "type" => "text",
                "properties" => [
                    "value" => "Какие-то описание, которое может быть полезно.
                    			\nИли не очень полезно, но описание какое-то.",
                    "multiline" => true,
                ]
            ],
            "variable-first" => [
                "type" => "withTitle",
                "properties" => [
                    "title" => "Стоимость",
                    "block" => [
                        "type" => "text",
                        "properties" => [
                            "value" => "100 000.00 руб.",
                        ]
                    ]
                ]
            ],
            "variable-second" => [
                "type" => "withTitle",
                "properties" => [
                    "title" => "Клиент",
                    "inline" => true,
                    "block" => [
                        "type" => "link",
                        "properties" => [
                            "text" => "ООО \"Компания Какая-то\"",
                            "action" => [
                                "type" => "redirect",
                                "uri" => "/crm/company/details/1809/"
                            ]
                        ]
                    ]
                ]
            ]
        ],
    ],
];

Готово! В timline лида добавлено наше собственное дело.

Заключение

С помощью собственных дел можно организовать рабочий процесс, который будет удовлетворять потребностям бизнеса или своевременно уведомлять сотрудников о каких-либо нештатных ситуациях. В примере (как и предупреждал) рассмотрена лишь малая часть возможностей. Если тема вам интересна, то ознакомьтесь с документацией. Потребуется вам 3 вещи: умение перевести js массив в php, чтение ошибок валидации и внимательность. Если у вас появятся вопросы, задавайте их в комментариях или через форму обратной связи — разберемся вместе! 🙂