Внешняя обработка для документа: как подключить и вызвать

Чтобы обработка появилась на документе, не нужно лезть в Конфигуратор и снимать конфигурацию с поддержки. В типовых базах на БСП (Бухгалтерия, ЗУП, Управление торговлей, ERP) внешнюю обработку .epf подключают через механизм «Дополнительные отчёты и обработки» — раздел Администрирование → Печатные формы, отчёты и обработки. А если код должен срабатывать сам при записи или проведении документа 1С, подключение делают подпиской на события или вызовом из модуля.

То есть «подключить обработку к документу» означает три разные вещи: показать пользователю кнопку (заполнение, печать, выгрузка), запустить логику автоматически при событии документа либо вызвать обработку из другого кода по пути к файлу. Способ выбирают по тому, кто и когда её запускает.

Подключение без программирования: «Дополнительные обработки»

Это основной способ в типовых конфигурациях. Обработка хранится в справочнике внутри базы, а не в конфигурации, поэтому обновления типовой её не затирают и поддержка не снимается.

Порядок действий:

1. Откройте Администрирование → Печатные формы, отчёты и обработки и включите флажок Дополнительные отчёты и обработки. Без него список подключаемых обработок недоступен.
2. По ссылке Дополнительные отчёты и обработки в том же разделе откройте список и нажмите Добавить из файла….
3. Выберите файл .epf. Платформа прочитает служебную информацию из обработки и сама заполнит поле Вид — заполнение объекта, создание связанных объектов, печатная форма, команда заполнения или отчёт.
4. В поле Размещение укажите документ (или несколько), на котором обработка должна появиться.
5. На закладке с командами проверьте, что нужная команда включена, и запишите карточку.

После этого кнопка обработки появляется в командной панели формы документа или списка. Точное место зависит от вида: заполнение обычно попадает под кнопку Заполнить, печатная форма — под Печать, остальные команды — отдельной кнопкой в панели.

Минимальный состав структуры, которую возвращает функция:

• Вид — чем является обработка (заполнение, печатная форма, создание связанных объектов и т. д.). От вида зависит, под какой кнопкой появится команда.
• Назначение — массив полных имён документов и справочников, для которых обработка предназначена. По нему платформа предлагает значения в поле Размещение.
• Наименование и Версия — отображаются в карточке и помогают отличать редакции обработки.
• Команды — таблица значений: идентификатор команды, представление для пользователя, вариант использования (открытие формы, вызов серверного метода, формирование печатной формы).

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

Безопасный режим

По умолчанию добавленная обработка запускается в безопасном режиме — ей запрещены работа с файлами, запуск внешних компонент и COM. Если обработке действительно нужны такие операции, снимите флажок безопасного режима и настройте профиль безопасного режима с нужными разрешениями. Отключать безопасный режим без разбора у чужих обработок опасно: вы даёте коду полный доступ к системе от имени пользователя.

Вызов обработки из кода по пути к файлу

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

// Загружаем внешнюю обработку из файла и запускаем её метод
Обработка = ВнешниеОбработки.Создать("C:\Обработки\ЗаполнениеСкидок.epf");
Обработка.ЗаполнитьСкидки(ДокументСсылка);

Метод ЗаполнитьСкидки здесь — это процедура с ключевым словом Экспорт в модуле объекта самой обработки. ВнешниеОбработки.Создать() возвращает объект обработки, у которого доступны все её экспортные методы и реквизиты.

Если тот же метод вызывается многократно за одну операцию, создавайте объект обработки один раз и переиспользуйте его. Каждый вызов ВнешниеОбработки.Создать() заново читает и компилирует файл — в цикле это заметно замедляет работу.

Обработка = ВнешниеОбработки.Создать(ПутьКФайлу);
Для Каждого Строка Из ТаблицаДокументов Цикл
    Обработка.Обработать(Строка.Ссылка);
КонецЦикла;

Этот вариант удобен для разовых и служебных задач, но для постоянной работы лучше подключить обработку через справочник «Дополнительные обработки» — тогда файл хранится в базе, а не на диске, и его не нужно раскладывать по серверам вручную.

Автоматический запуск: подписки на события документа

Если логика должна отрабатывать сама — при записи или проведении, без участия пользователя — используют подписку на события. Это объект метаданных: он связывает событие документа с процедурой-обработчиком в общем модуле.

Что задаётся в подписке:

• 🎯 Источник — типы документов, на которые она реагирует (например ДокументОбъект.РеализацияТоваровУслуг или сразу группа через определяемый тип).
• ⚡ Событие — ПередЗаписью, ПриЗаписи, ОбработкаПроведения и другие.
• 🧩 Обработчик — экспортная процедура в общем модуле.

Первым параметром в обработчик всегда приходит Источник — сам объект документа, дальше идут параметры события. Для ПередЗаписью у документа это Отказ, РежимЗаписи и РежимПроведения:

// Общий модуль, серверная процедура
Процедура ПроверитьДокументПередЗаписью(Источник, Отказ, РежимЗаписи, РежимПроведения) Экспорт
    Если Источник.СуммаДокумента = 0 Тогда
        Отказ = Истина;
    КонецЕсли;
КонецПроцедуры

Событие выбирают по задаче. Для проверки, которая должна отменить запись, подходит ПередЗаписью — там ещё можно поставить Отказ = Истина. Для формирования дополнительных движений при проведении — ОбработкаПроведения. Для действий уже после успешной записи, не влияющих на отказ, — события записи объекта. Не вешайте на одно событие логику, которой место в другом: отмена записи из ОбработкаПроведения работает иначе, чем из ПередЗаписью.

Подписка требует изменения метаданных, но снимать типовую с поддержки не обязательно: создайте подписку и общий модуль в расширении конфигурации. Расширения появились в платформе 8.3.6, подключаются в Администрирование → Печатные формы, отчёты и обработки → Расширения и обновлениям типовой не мешают.

Передача параметров и контекста в обработку

У каждого способа свой путь передать данные.

Дополнительные обработки. Платформа передаёт в команду контекст вызова: обычно это ссылка или объект того документа, из формы которого запустили обработку. В экспортных методах обработки эти параметры принимают по именам, которые заданы в описании команды.

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

Подписка на события. Контекст — это сам Источник. Через него доступны все реквизиты и табличные части документа. Если нужно пробросить флаг между событиями одного объекта (например, из ПередЗаписью в ПриЗаписи), используйте ДополнительныеСвойства объекта — это коллекция, которая живёт в пределах одной записи.

// В одном обработчике положили, в другом прочитали
Источник.ДополнительныеСвойства.Вставить("ПроверкаПройдена", Истина);

Обработка ошибок и запись в журнал регистрации

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

Оборачивайте потенциально опасные участки в Попытка … Исключение … КонецПопытки и пишите подробности в журнал регистрации:

Попытка
    ВыполнитьВыгрузкуВоВнешнююСистему(Источник);
Исключение
    ЗаписьЖурналаРегистрации(
        "Интеграция.Выгрузка",
        УровеньЖурналаРегистрации.Ошибка,
        ,
        Источник,
        ПодробноеПредставлениеОшибки(ИнформацияОбОшибке()));
КонецПопытки;

Что это даёт:

• 📝 ПодробноеПредставлениеОшибки(ИнформацияОбОшибке()) сохраняет стек и текст исключения — без него в журнале будет только факт сбоя.
• 🔎 Четвёртым параметром передан Источник — в журнале запись привяжется к конкретному документу, и его легко найти.
• 🚦 Уровень Ошибка позволяет отфильтровать именно сбои, не утонув в информационных записях.

Решите заранее, что делает код при ошибке. Для проверок, которые должны блокировать запись, ставьте Отказ = Истина и выводите понятное сообщение пользователю. Для фоновой выгрузки — наоборот, не роняйте запись документа: запишите ошибку в журнал и повторите выгрузку позже.

Смотреть записи: Администрирование → Журнал регистрации, фильтр по имени события или по приложению.

Производительность: когда обработка тормозит документ

Чаще всего жалобы на «подключили обработку — всё повисло» сводятся к трём причинам.

Частые ошибки при подключении

Частые вопросы