Конвертация в лидах CRM Битрикс24

Конвертация, это превращение одного элемента CRM в другие элементы CRM. Элемент на котором выполняется конвертация мы будем называть конвертируемым элементом, а элементы получившиеся в результате конвертации результат конвертации.

Существует альтернативное название для конвертации создание на основании, в рамках статьи мы будем предполагать что это синонимы.

Конвертируемые элементы

На момент написания статьи конвертируемыми элементами может выступать только Лид, Сделка и Предложение, причем существуют различные модификаторы конвертации которые влияют на доступный набор результатов.

В системе зарегистрировано 3 конвертационных модификатора:

• Ограничение по сущностям
• Только для лида, специализированный модификатор на основании типа (обычный и повторный)
• Генерируемый на основании ролевой карты

Модификатор ограничения по сущностям является общим модификатором который указывает на основании конвертируемого элемента какие результаты конвертации могут быть получены.

• На основании Лида можно создать: Контакт, Компанию, Сделку
• На основании Сделки: Счет и Предложение
• На основании Предложения: Счет и Сделку

Специализированный модификатор проверяет тип лида и в случае если конвертируемый лид является повторным то на его основании можно создать только сделку.

Модификатор генерируемый на основании ролевой карты собирает максимальные права данного пользователя на создание сущностей и разрешает конвертацию только в те сущности на которые у текущего пользователя есть права добавления. Так, например, если у пользователя нет прав на создание сделки, то Лид нельзя будет конвертировать в Сделку, но будет возможность конвертировать в Контакт или Компанию и их вариации.

Если смотреть в суть вещей, то и процесс создания одного элемента на основании другого и процесс создания подобных связей без непосредственного создания новых сущностей является конвертацией и чтобы различать их в рамках статьи мы будем рассматривать как 2 независимых процесса:

• Конвертация создание результатов на основании конвертируемого элемента
• Псевдоконвертация создание связей для уже существующих элементов

Непосредственные классы отвечающие за работу конвертации располагаются в пространстве имен \Bitrix\Crm\Conversion. В дальнейшем мы будем предполагать что это пространство имен и классы из него подключены в use.

Конвертационные схемы

Теперь когда мы рассмотрели основные моменты, мы можем перейти к рассмотрению конвертационных схем — технических описания как именно нужно конвертировать конвертируемый элемент в результаты.

Конвертационные схемы хранятся в таблице b_crm_conv_map, простраство имен \Bitrix\Crm\Conversion\Entity\EntityConversionMapTable, однако работать напрямую с таблицей не рекомендуется.

Конвертационная схема состоит из следующих полей:

Отдельно стоит остановиться на нововведениях: механизм Смарт-процессов позволяет привязывать созданный Смарт-процесс к элементам. Для реализации этой возможности были добавлены столбцы RELATION_TYPE и IS_CHILDREN_LIST_ENABLED.

1. RELATION_TYPE — тип связи конвертационной схемы. В настоящий момент допустимы только 2 значения: \Bitrix\Crm\Relation\RelationType::CONVERSION (конвертация) и \Bitrix\Crm\Relation\RelationType::BINDING (связь)
2. IS_CHILDREN_LIST_ENABLED — флаг обозначающий необходимость добавить список со связанными элементами в карточку конвертируемой сущности. Отдельно стоит отметить, что при типе конвертационной схеме связь, заполнение сериализованной конвертационной карты не требуется

Сама сериализованная конвертационная карта состоит из полей:

• srcEntityTypeID индентификатор типа конвертируемого элемента \CCrmOwnerType
• dstEntityTypeID идентификатор типа результата конвертации
• time дата генерации конвертационной схемы
• items набор инструкций по конвертации поля конвертируемого элемента

Каждая инструкция по конвертации поля состоит из следующего набора полей:

• srcField код поля в конвертируемом элементе
• dstField код поля в элементе результата конвертации
• altSrcFields набор кодов полей, откуда будет произведена попытка получения значений, в случае если в srcField не будет значения
• isLocked флаг указывающий на то, что изменение элемента в публичной части при вызове формы невозможен (поле будет заблокировано)
• isRequired флаг указывающий на то, что заполнение этого поля обязательно при конвертации

При создании конвертационных схем битрикс использует автоматический механизм, который состоит из двух частей:

1. Строго определенной стандартной частью
2. Работой с пользовательскими полями

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

Для работы с пользовательскими полями битрикс использует механизм синхронизации полей, когда имеющиеся пользовательские поля в лиде будут созданы во всех результатах конвертации. Например, если работе с CRM в Лиде вы создали дополнительное поле «Тема обращения», то данное поле при конвертации в Сделку+Контакт будет создано И в сделке И в контакте, хотя семантически оно может быть там совершенно не нужно. Перенос полей происходит по принципу 1к1, т.е. если поле с таким кодом существует и в лиде и в сделке, то в сделке это поле не будет создано, а будет проставлена связь между полями.

Простой способ конвертации

Наиболее простым способом конвертации является использование средств автоматизации предоставляемых в пространстве имен \Bitrix\Crm\Automation\Converter.

Описанный класс настолько прост, что не имеет смысла описывать его возможности технически. Рассмотрим пример, кода на основании лида ID:1 от лица пользователя ID:1 должен конвертировать в сделку определенного направления ID:1 и контакт.

\Bitrix\Main\Loader::IncludeModule('crm');

/**
 * Income lead id
 * @var integer
 */
$leadId = 1;

/**
 * User id who start convertation
 * @var integer
 */
$convertUserId = 1;

/**
 * Deal category id
 * @var integer
 */
$dealCategoryId = 1;

/**
 * True if need to complete all activities after convertation process
 * @var boolean
 */
$completeActivityAfterConveration = true;

try {
    $converter = \Bitrix\Crm\Automation\Converter\Factory::create(
        \CCrmOwnerType::Lead,
        $leadId
    );

    $converter->enableActivityCompletion($completeActivityAfterConveration);

    $converter->setTargetItem(
        \CCrmOwnerType::Deal,
        ['categoryId' => (int)$dealCategoryId]
    );

    $converter->setTargetItem(
        \CCrmOwnerType::Contact,
        []
    );

    $conversionResult = $converter->execute([
        'USER_ID' => $convertUserId
    ]);

    /**
     * Register convertation relations
     */
    \Bitrix\Crm\Automation\Factory::registerConversionResult(
        \CCrmOwnerType::Lead,
        $leadId,
        $conversionResult
    );

    if (!$conversionResult->isSuccess()) {
        throw new \Exception(
            "Conversion error: "
            . implode(', ', $conversionResult->getErrorMessages())
        );
    }
} catch (\Throwable $e) {
    var_dump($e);
}

Конвертационный процесс

Технически конвертация сводится к последовательности действий выполняемых для определенной сущности:

• Создание конфигурации, наследник EntityConversionConfig
• Создание мастера, наследник EntityConversionWizard
• Установка необходимых параметров конвертации
• Запуск мастера конвертации

Конвертация лида

Выполним конвертацию ранее описанного примера явно, не используя конструкции предоставляемые автоматизацией crm:

\Bitrix\Main\Loader::IncludeModule('crm');

/**
 * Converted lead id
 * @var integer
 */
$leadId = 1;

/**
 * User id who start convertation
 * @var integer
 */
$convertUserId = 1;

/**
 * Deal category id
 * @var integer
 */
$dealCategoryId = 1;

/**
 * Execution context
 * @var array
 */
$contextData = [
    'USER_ID' => $convertUserId
];

$conversionConfig = new \Bitrix\Crm\Conversion\LeadConversionConfig();

/**
 * Disable user field check to prevent create exceptions
 */
$conversionConfig->enablePermissionCheck(false);

// For contact
$item = $conversionConfig->getItem(\CCrmOwnerType::Contact);
if ($item) {
    // Activate convertation to contact
    $item->setActive(true);

    // Enable syncronization fields
    $item->enableSynchronization(true);

    // Setup initial data. Accepted only 'defaultName'
    $item->setInitData([
        'defaultName' => 'Default contact name',
    ]);
}
unset($item);

// For deal in category
$item = $conversionConfig->getItem(\CCrmOwnerType::Deal);
if ($item) {
    // Activate convertation to contact
    $item->setActive(true);

    // Enable syncronization fields
    $item->enableSynchronization(true);

    // Setup initial data. Accepted only 'categoryId'
    $item->setInitData([
        'categoryId' => (int)$dealCategoryId,
    ]);
}
unset($item);

$conversionWizard = new \Bitrix\Crm\Conversion\LeadConversionWizard(
    $leadId,
    $conversionConfig
);

/**
 * Disable user field synchronization.
 */
$conversionWizard->enableUserFieldCheck(false);

/**
 * Disable workflow new entity check.
 * If exist workflow with autostart option and parameters
 * wizard throws an error
 */
$conversionWizard->enableBizProcCheck(false);

/**
 * If crm lead entity exist bizproc with option autostart when update
 * need start this workflows?
 */
$conversionWizard->setSkipBizProcAutoStart(true);

/**
 * Need to complete all activities after convertation process
 */
$conversionWizard->enableActivityCompletion(true);

/**
 * Process user field synchronization to prevent the fields from diverging
 */
$srcEntityTypeId = \CCrmOwnerType::Lead;
foreach ($conversionConfig->getItems() as $item) {
    $dstEntityTypeId = (int)$item->getEntityTypeID();
    if (!\Bitrix\Crm\Synchronization\UserFieldSynchronizer::needForSynchronization(
        $srcEntityTypeId,
        $dstEntityTypeId
    )) {
        continue;
    }

    if ($item->isSynchronizationEnabled()) {
        \Bitrix\Crm\Synchronization\UserFieldSynchronizer::synchronize(
            $srcEntityTypeId,
            $dstEntityTypeId
        );
    } else {
        \Bitrix\Crm\Synchronization\UserFieldSynchronizer::markAsSynchronized(
            $srcEntityTypeId,
            $dstEntityTypeId
        );
    }
}

if (!$conversionWizard->execute($contextData)) {
    /**
     * Caught some error. You can see error text (string)
     * with '$conversionWizard->getErrorText()'
     */
} else {
    /**
     * Ok. You can get result data from
     * $conversionWizard->getResultData()
     */
}

Конвертационные связи

Помимо выполнения конвертационного процесса существует и псевдоконвертация, создание связей без создания элементов. В разных сущностях этот процесс характеризуется своими особенностями.

Поле LEAD_ID является универсальным для Сделок, Контактов и Компаний, однако это совершенно не значит что механизм его обработки одинаковый. Не пытайтесь заполнить это поле в СУБД через SQL запрос! Используйте старое api для его заполнения.

Если получилась такая ситуация, что поле LEAD_ID в какой-либо сущности было заполнено прямым SQL-запросом, то для данного лида необходимо пересчитать статистические данные методом:

use \Bitrix\Crm\Statistics;

Statistics\LeadConversionStatisticsEntry::processBindingsChange($leadID);

Таким образом, для того чтобы проставить связи между существующими Контактом, Компанией или Сделкой с лидом достаточно просто обновить данный соответствующей сущности добавив в поле LEAD_ID идентификатор лида.