Как правильно клонировать файлы в пользовательских полях смарт-процессов Битрикс24

Работая с CRM-сущностями и смарт-процессами в Битрикс24, разработчики нередко сталкиваются с задачей клонирования записей, в том числе и пользовательских полей типа файл. На первый взгляд задача тривиальна: использовать \CFile::CloneFile() и сохранить. Но на практике это приводит к ошибкам. Почему — и как сделать правильно — разбираемся ниже.

Проблема: \CFile::CloneFile() не работает как ожидалось

$newFileId = \CFile::CloneFile($fileId);

 $item->set('UF_CRM_XXX_FILE', $newFileId);

 $item->save();

Приводит к ошибке: файл не сохраняется.

Причина

Суть проблемы в поведении класса \Bitrix\Main\UserField\Types\FileType, который при сохранении выполняет строгую валидацию через onBeforeSave():

• Проверяет регистрацию файла в FileInputUtility

• Проверяет наличие файла в текущем значении поля

• Проверяет регистрацию в ManualUploadRegistry

Если файл не прошёл ни одну проверку — он игнорируется и не сохраняется.

✅ Решение: регистрация в ManualUploadRegistry

После клонирования файла его обязательно нужно зарегистрировать как вручную загруженный.

use Bitrix\Main\UserField\File\ManualUploadRegistry;

// Шаг 1: Клонируем файл
$newFileId = \CFile::CloneFile($sourceFileId);

if (!$newFileId) {

    throw new \Exception("Ошибка клонирования файла");

}
// Шаг 2: Регистрируем файл

$factory = \Bitrix\Crm\Service\Container::getInstance()->getFactory($entityTypeId);
$userField = $factory->getUserFields()['UF_CRM_XXX_FILE'];

$registry = ManualUploadRegistry::getInstance();
$registry->registerFile($userField, $newFileId);

$item->set('UF_CRM_XXX_FILE', $newFileId);
$item->save(); // ✅ Успешно

Работа с файлами в пользовательских полях CRM требует знания тонкостей внутренней логики Битрикс24. Простое клонирование \CFile::CloneFile() недостаточно — необходимо регистрировать файл вручную через ManualUploadRegistry.