Внешние функции обработки СБИС для 1С 8.х

Так как код самой обработки Sbis1C.epf ни при каких условиях менять нельзя, для внесения изменений под клиента предусмотрена дополнительная внешняя обработка ВнешниеФункции_Клиент.epf. Данная обработка отсутствует в стандартной поставке и создается самостоятельно с помощью конфигуратора 1С. Внешние функции пишутся при необходимости изменить выгрузку или загрузку документов, если изменения требуют определенных вычислений и нельзя обойтись простой правкой файла настроек, а также для изменения механизма работы со статусами документов и сопоставления номенклатуры. Обработка ВнешниеФункции_Клиент.epf должна располагаться в каталоге настроек.

Внешние функции для выгрузки документов

Внешние функции в файлах настроек

Параметры в файлах настроек могут определяться через функцию. Все функции, вызываемые из стандартных файлов настроек, описаны в форме РаботаСДокументами1С обработки Sbis1C.epf. Эти функции можно переопределить в обработке ВнешниеФункции_Клиент.epf, а также для любого параметра файла настроек написать свою функцию.

Вызов функций, описанных в файлах настроек, происходит после того как рассчитаны все другие параметры, определенные НЕ через функции. То есть сначала идет одно обращение на сервер 1С, где мы получаем напрямую все данные из документа, описанные в файле настроек, а потом уже на клиентской стороне вычисляются параметры, определенные с помощью функций.

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

• Создаем внешнюю обработку ВнешниеФункции_Клиент.epf в конфигураторе 1С (меню Файл/Новый/Внешняя обработка). Имя обработки так же указываем ВнешниеФункции_Клиент:

Сохраняем файл в каталог настроек.

• В обработке создаем форму "РаботаСДокументами1С" (название можно скопировать из основной обработки)
• В модуле формы пишем экспортную функцию с одним параметром (для единообразия называем параметр "Контекст")

Параметр Контекст представляет из себя структуру, поля которой соответствуют параметрам блока мФайл в файле настроек (по которому выгружается документ), а в значениях полей - уже рассчитанные значения параметров, которые определены не через функции, то есть примерно такая структура:

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

Важно! Для управляемых форм! Для ускорения процесса выгрузки необходимо минимизировать количество обращений к серверу 1С. Получение любого реквизита документа, организации, контрагента и т.д. - это обращение к серверу. Поэтому по возможности все реквизиты, которые необходимы для вычислений во внешней функции, определяем в файле настроек, чтобы все они были рассчитаны за одно обращение к серверу.

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

<СторонаНаименованиеПолное>[Сторона].НаименованиеПолное</СторонаНаименованиеПолное>
<СторонаНаименованиеСокращенное>[Сторона].НаименованиеСокращенное </СторонаНаименованиеСокращенное>
<Сторона_Наименование>{сбисНаименованиеОрганизации()}</Сторона_Наименование>

В этом случае внешняя функция может исполняться на клиенте (не забываем указать соответствующую директиву) и не дергать лишний раз сервер. В Контексте уже будут лежать рассчитанные значения параметров СторонаНаименованиеПолное и СторонаНаименованиеСокращенное:

&НаКлиенте
Функция сбисНаименованиеОрганизации(Контекст) Экспорт
	Если ЗначениеЗаполнено(Контекст.СторонаНаименованиеПолное) Тогда
		Возврат Контекст.СторонаНаименованиеПолное;
	Иначе
		Возврат Контекст.СторонаНаименованиеСокращенное;
	КонецЕсли;
КонецФункции

Внешние функции, вызываемые из обработки

В стандартном механизме формирования электронного документа есть два места для "встраивания", то есть для внесения изменений в выгружаемый документ:

1. Функция сбисПослеФормированияСтроки(НоваяСтрока, Кэш, Контекст, Стр) - предназначена для внесения изменений в строки табличной части, а также определяет, нужно ли добавлять данную строку в документ.

Возвращает Истину - в этом случае строка добавляется в документ, или Ложь - в этом случае строка не добавляется в документ (см. пример)

Вызывается после формирования структуры строки стандартным механизмом в форме Файл_Шаблон. Сама функция пишется в обработке ВнешниеФункции_Клиент в форме «Файл_[Формат файла]_[Версия формата файла]». Например, при формировании накладной создается форма "Файл_ЭДОНакл_3_01". Если нужно написать данную функцию для нескольких типов документов, то для каждого создается своя форма. Нельзя выносить во внешние функции форму "Файл_Шаблон"!

Параметры Функции:

• НоваяСтрока - структура строки, которая будет добавлена в выгружаемый документ. То есть именно в нее при необходимости нужно вносить изменения.
• Кэш - общий кэш обработки (структура)
• Контекст - структура с данными по текущей выгрузке документов
• Стр - структура строки, заполненная по файлу настроек

2. Функция сбисПослеФормированияДокумента(Док, Кэш, Контекст) - предназначена для внесения изменений в сформированный документ. Также используется при необходимости добавить к пакету печатную форму документа в формате pdf.

Вызывается после формирования структуры документа стандартным механизмом в форме Файл_Шаблон. Сама функция пишется в обработке ВнешниеФункции_Клиент в форме «Файл_[Формат файла]_[Версия формата файла]».

Параметры Функции:

• Док - структура выгружаемого документа. В нее при необходимости нужно вносить изменения.
• Кэш - общий кэш обработки (структура)
• Контекст - структура с данными по текущей выгрузке документов

Пример кода в функции сбисПослеФормированияДокумента для добавления в пакет внешней печатной формы документа:

	Запрос = Новый Запрос;
	Запрос.Текст = 
 	   "ВЫБРАТЬ
 	   |    Справочник.ВнешниеОбработки.Ссылка КАК Объект
  	   |ИЗ
 	   |   Справочник.ВнешниеОбработки
	   |ГДЕ
           |   (Справочник.ВнешниеОбработки.Наименование = &НаимФормы)";
 
	Запрос.УстановитьПараметр("НаимФормы", "АктВодоканал");
	Выборка = Запрос.Выполнить().Выбрать();
	Если Выборка.Количество() = 0 Тогда
		Возврат Ложь;
	КонецЕсли;
	Пока Выборка.Следующий() Цикл
		Обработка = Выборка.Объект;
		Прервать();
	КонецЦикла;

	Обработка = Обработка.ХранилищеВнешнейОбработки.Получить();
        ВремКаталог = КаталогВременныхФайлов();
	Путь = ВремКаталог+"АктВодоканал.epf"; 
	Обработка.Записать(Путь);
	Обработка = ВнешниеОбработки.Создать(Путь);	
  	Обработка.СсылкаНаОбъект = Контекст.Документ;		
	ТабДокумент = Обработка.Печать();				
	ИмяФайла = "АктВодоканал.pdf";
	ПолноеИмяФайла = ВремКаталог+ИмяФайла;
	ТабДокумент.Записать(ПолноеИмяФайла,ТипФайлаТабличногоДокумента.pdf);
	Контекст.СоставПакета.Вложение.Добавить(Новый Структура("ПолноеИмяФайла,ИмяФайла,Название", ПолноеИмяФайла,ИмяФайла,ИмяФайла));

Переопределяемые функции выгрузки документов

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

• В обработке ВнешниеФункции_Клиент создаем форму «Файл_[Формат файла]_[Версия формата файла]»
• Переносим в нее функции ПолучитьДанныеИзДокумента1С(Кэш,Контекст) и ПолучитьТабличнуюЧастьДокумента1С(Кэш,Контекст) из формы Файл_Шаблон и пишем в этих функциях свой код формирования структуры документа.

Параметры Функций:

• Кэш - общий кэш обработки (структура)
• Контекст - структура с данными по текущей выгрузке документов

Не забываем в конце добавить свое вложение в состав пакета:

Контекст.СоставПакета.Вложение.Добавить(Вложение);

Так же есть возможность полностью переопределить отправку документов из определенного реестра. Для этого:

• В обработке ВнешниеФункции_Клиент создаем форму «Документ_[тип документа 1С]»
• Переносим в нее функцию ОтправитьДокументы(Кэш,МассивСтрок) из формы Документ_Шаблон и пишем свой код.

Параметры Функции:

• Кэш - общий кэш обработки (структура)
• МассивСтрок - список отмеченных строк таблицы документов, которые необходимо отправить

Внешние функции для загрузки документов

Внешние функции в файлах настроек

Если какой-то реквизит документа 1С при загрузке нужно заполнить с помощью функции, то данная функция указывается в атрибуте "Вычислить"

Чтобы заполнить реквизит документа 1С через клиентскую функцию:

• Создаем внешнюю обработку ВнешниеФункции_Клиент.epf в конфигураторе 1С
• В обработке создаем форму "РаботаСДокументами1С"
• В модуле формы пишем экспортную функцию с одним параметром (для единообразия называем параметр "Контекст")

Контекст - структура с полями:

• Ини - структура файла настроек, по которому идет загрузка
• Документ - структура документа 1С, который будет загружен
• СтрТабл - структура текущей строки табличной части создаваемого документа
• СтруктураФайла - структура файла, на основании которого создается документ
• СтрокаФайла - текущая строка файла, на основании которой заполняется текущая строка документа
• СоставПакета - структура, содержащая полный состав загружаемого пакета

Внешние функции, вызываемые из обработки

После того, как документ 1С создан стандартным механизмом, есть возможность внести в него изменения. Для этого предназначена функция ДопРасчетыПриЗагрузке(Документ1С, Контекст), вызываемая из формы Документ_Шаблон.

Функция пишется в обработке ВнешниеФункции_Клиент в форме «Документ_[Тип документа 1С]». Например, при загрузке документа ПоступлениеТоваровУслуг создается форма "Документ_ПоступлениеТоваровУслуг". Если нужно написать данную функцию для нескольких типов документов, то для каждого создается своя форма. Нельзя выносить во внешние функции форму "Документ_Шаблон"!

Параметры Функции:

• Документ1С - Загруженный документ 1С
• Контекст - структура с полями СтруктураФайла - структура загружаемого файла, СоставПакета - структура загружаемого пакета документов

Когда удобно использовать данную функцию. Например, при ручном вводе документа в 1С при выборе контрагента автоматически заполняются еще несколько реквизитов (договор, соглашение, ответственный и др.). Чтобы не писать для каждого реквизита отдельную функцию в файле настроек, мы можем написать одну функцию ДопРасчетыПриЗагрузке и из нее вызвать стандартный механизм из модуля формы документа, который реагирует на изменение контрагента - все зависимые от него реквизиты заполнятся автоматически. Не забываем сохранить результат (методом документа Записать)

Переопределяемые функции загрузки документов

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

• В обработке ВнешниеФункции_Клиент создаем форму «Документ_[Тип документа 1С]»
• Переносим в нее функцию СоздатьДокумент из формы Документ_Шаблон и пишем свой код загрузки документа.

Внешние функции для работы со статусами

В обработке присутствуют две стандартные формы работы со статусами документов: Статусы_Регистры и Статусы_ДБФ. В процессе работы используется одна из них, указанная в файле настроек конфигурации. При необходимости изменения механизма работы со статусами выносим используемую форму во ВнешниеФункции_Клиент.epf и выносим функции данной формы, которые необходимо переопределить.

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

Внешние функции для сопоставления номенклатуры

В обработке присутствуют несколько стандартных форм работы с сопоставлением номенклатуры (название формы начинается с "СопоставлениеНоменклатуры_"). В процессе работы используется одна из них, указанная в файле настроек конфигурации. При необходимости изменения механизма работы с сопоставлением номенклатуры выносим используемую форму во ВнешниеФункции_Клиент.epf и выносим функции данной формы, которые необходимо переопределить.

Данный механизм может потребоваться, если у клиента заведен свой (нестандартный) справочник или регистр сведений для номенклатуры контрагентов.