Интеграция с 1С:Документооборотом. Интегрируй меня полностью

Меня зовут Никита Перевозчиков, я руководитель направления по внедрению систем на базе 1С:Документооборот в компании Programming Store.

Хочу рассказать про подсистему «Библиотека интеграции с 1С:Документооборотом»:

• Рассмотрим, что такое библиотека интеграции.

• Расскажу про популярные проблемы, которые часто встречаются с этой подсистемой.

• Расскажу про расширение функциональности – то, что я добавляю обычно в базовую функциональность библиотеки интеграции, чтобы расширять круг решаемых задач.

• И в конце немного поговорим про проблемы пользовательского интерфейса – расскажу, каким образом их нивелировать.

Что такое библиотека интеграции

Библиотека интеграции – это подсистема, которая может быть встроена в типовые решения 1С на основе БСП (например, в ЗУП или в Бухгалтерию предприятия).

Библиотека интеграции обеспечивает программный интерфейс для обмена данными с 1С:Документооборотом. Она позволяет просматривать объекты 1С:Документооборота и работать с ними, не выходя из основной учетной системы. Это так называемый принцип «единого окна» – основная фишка этой подсистемы.

Вот так выглядит принцип единого окна – мы прямо из документа основной учетной системы создаем и просматриваем документ в 1С:Документообороте.

Работает все это довольно просто:

• У нас есть 1С:Документооборот, для которого на веб-сервере публикуется сервис DMService, раздающий API по протоколу SOAP.

• Есть интегрируемая система (это может быть ЗУП или Бухгалтерия предприятия), куда внедрена «Библиотека интеграции».

• Интегрируемая система через DMService выполняет запросы к 1С:Документообороту.

• DMService эти запросы обрабатывает, подготавливает ответы и возвращает эти ответы обратно в интегрируемую систему. После этого система сама понимает, что с ними делать – например, может отобразить их пользователю в виде каких-то данных.

Интеграция работает следующим образом:

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

• В основных формах документов, которые подключены к подсистеме интеграции, появляется ссылка «Документооборот».

• На основании данного документа через ссылку «Документооборот» можно создать документ в 1С:Документообороте. Либо, если соответствующий документ уже существует, можно его посмотреть и выполнить с ним какие-то действия.

• После того как мы в первый раз создали объект в 1С:Документообороте, у нас происходит связка этих объектов в специальных регистрах сведений.

• И дальше подключаются регламентные задания, которые с определенной периодичностью актуализируют сведения по настроенным нами правилам.

Популярные проблемы и методы их решения

Я выделил три проблемы библиотеки интеграции с 1С:Документооборотом, с которыми я наиболее часто встречаюсь.

Первая частая проблема – это вылеты по таймауту.

Например, у нас в 1С:Документообороте создан документ на основании «Поступления товаров и услуг» учетной системы, и мы пытаемся отправить его на согласование.

Из учетной системы жмем на кнопку «Создать бизнес-процесс», ждем какое-то время, и система сообщает нам о вылете по таймауту.

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

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

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

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

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

Следующая проблема, о которой я хочу рассказать – это ошибки при обмене данными, дублирование НСИ.

Очень часто встречается ситуация, как на слайде.

Думаю, практически все встречались с ситуацией, когда у нас есть справочник «Организации» с элементами «Лютик», «Ромашка», «Меркурий». И в этом списке каждый день появляется новый элемент «Меркурий» – с теми же ИНН и КПП, но который назван как-то по-другому. Мы помечаем его на удаление, он снова появляется, мы опять помечаем его на удаление и так далее.

Эта ситуация связана с тем, что какая-то из интегрированных систем 1С:Документооборота толкает к нам внутренний документ, вместе с которым к нам тянется борода из нормативно-справочной информации – в том числе и информация по организации.

При этом на каждый элемент НСИ в 1С:Документообороте на уровне конфигуратора описано, каким образом необходимо производить поиск, что делать, если мы не нашли какой-то элемент НСИ – создавать его или пропускать в этом случае.

В 1С:Документообороте на каждый элемент НСИ, будь то организация, контрагент или физлицо, заведена специальная функция, позволяющая найти и создать: например, «НайтиСоздатьОрганизацию», «НайтиСоздатьФизлицо» и так далее.

Каждая такая функция построена примерно по одной модели:

• сначала пытается найти по наименованию;

• если по наименованию не находит, пытается посмотреть переопределяемый поиск;

• потом есть какой-то стандартный поиск;

• еще есть блок синхронизации по идентификатору и т.д.

Задумано, что если одно не сработает, то другое подойдет, если другое не сработает, то третье подойдет и так далее.

Но в данном случае получается, что к нам поступает организация «Меркурий», которую мы по наименованию найти не можем, но при этом нас сразу заставляют создать новый «Меркурий» с абсолютно пустыми данными – даже без ИНН и КПП. И все остальные блоки, которые здесь описаны – синхронизация по ID, переопределяемый поиск, стандартный поиск и другие – уже значения не имеют.

Чтобы это исправить, нужно:

• Закинуть блок переопределяемого поиска на первое место.

• А в функции «НайтиСоответствиеДляВнешнегоОбъекта» прописать свой нормальный поиск по ИНН и КПП, чтобы это работало по-человечески.

У меня тоже нет точного представления, почему это выведено только в переопределяемый поиск, а не сделано по-нормальному с самого начала – здесь можно только догадываться.

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

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

Анализируем размер таблиц в информационной базе и оказывается, что максимально сильно набит справочник «Сообщения интегрированных систем», который хранит заранее подготовленные пакеты с сообщениями для каждой системы, подключенной к 1С:Документообороту.

По сути, каждый элемент справочника «Сообщения интегрированных систем» – это XML-ка с изменениями какого-то объекта в 1С:Документообороте. И каждое это сообщение предназначено для какого-то получателя – для какой-то интегрируемой системы.

Эти интегрируемые системы стучатся в 1С:Документооборот, ищут там подготовленные для них сообщения, забирают, читают, применяют у себя, но за собой эти элементы не подчищают – они их просто помечают на удаление как обработанные. Но в базе данных объем этих XML-ек присутствует и растет.

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

Эти обработанные сообщения можно очень смело удалить с помощью стандартной обработки «Удаление помеченных объектов», которая вшита в каждую конфигурацию, написанную на БСП – в том числе, в 1С:Документооборот.

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

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

Первое, что можно сделать – это включить автоотправку новых объектов. Такую доработку часто просит бизнес.

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

Но бизнес-то привык к классической схеме синхронизации данных, где используется конвертация, где создаешь объект, и он улетает автоматически – больше ни о чем думать не нужно. Бизнес просит нас: «Давайте сделаем так же в интеграции с 1С:Документооборотом?»

Почему бы и нет? Чтобы это реализовать, внесем изменения в интегрируемую систему – доработаем в общем модуле ИнтеграцияС1СДокументооборотОбмен две процедуры – это ПодготовитьДанныеДляОтправки() и ОтправитьДанные().

В процедуре ПодготовитьДанныеДляОтправки() мы вставляем кусочек кода, который проверяет, существует ли документ в 1С:Документообороте. Если не существует, мы записываем в xml-пакет узел со специальным тегом и сериализуем в него объект документа.

А в процедуре ОтправитьДанные() мы последовательно считываем значения узлов xml-пакета и, если натыкаемся на узел с тегом, который записали ранее, то с помощью методов стандартного интерфейса библиотеки интеграции создаем документ в 1С:Документообороте и связываем его с документом в интегрируемой системе. Благодаря этой связке данные этих документов в дальнейшем будут актуализироваться автоматически.

События «Перед записью объекта», «После записи объекта» в правилах интеграции

Далее я хотел поговорить про события «Перед записью объекта» и «После записи объекта» в правилах интеграции – это те классические события, которые мы используем в правилах конвертации объектов в «Конвертации данных».

В «Библиотеке интеграции с 1С:Документооборотом» есть довольно простой инструмент для настройки правила интеграции – с его помощью мы можем указать для различных документов, какие реквизиты как заполнять.

Но за каждой простотой у нас всегда кроется отсутствие гибкости – здесь мы можем только указать, откуда что заполнить, но дополнительных плюшек, к которым мы так привыкли в «Конвертации данных», здесь нет.

Например, задача: мы настраиваем правила интеграции, но хотим, чтобы в поле «Ответственный» создаваемого документа подставилось не значение из источника документа, а руководитель организации, рассчитанный уже на стороне 1С:Документооборота.

Понятное дело, что в момент интеграции мы довольно ограничены – про данные интегрируемой системы ничего не знаем и к контексту ее базы данных обратиться не можем. Поэтому напрашивается решение – мы делаем какой-то обработчик, который должен выполниться на стороне приемника в момент, когда объект документа уже скомпоновался, но не записался. И нужно, чтобы при выполнении этого обработчика мы могли обратиться к ответственным лицам организации, определить руководителя и подставить в созданный, но не записанный объект уже рассчитанного ответственного. В стандартных правилах интеграции такого не предусмотрено – у нас есть только список полей источника.

Я делаю так: помимо реквизитного состава документа источника, я в этот список добавляю поля «Исполняемый код (перед записью объекта)» и «Исполняемый код (после записи объекта)», куда будет передаваться строка кода для ее последующего выполнения на стороне 1С:Документооборота.

Чтобы это реализовать, мы открываем в конфигураторе 1С:Документооборота XDTO-пакет DM и добавляем в его объект DMDocument свойства BeforeWriting и AfterWriting строкового типа неограниченной длины.

Затем прописываем определенную логику для работы с добавленными свойствами на стороне интегрируемой базы.

Это позволит нам при настройке правил интеграции для любых типов документов выводить в список с реквизитным составом документа поля «Исходный исполняемый код (перед записью объекта)» и «Исходный исполняемый код (после записи объекта)». В эти поля мы можем передать строку с кодом, которая написана в контексте конфигурации 1С:Документооборот.

Например, код из поля «Исходный исполняемый код (перед записью объекта)» выполнится в 1С:Документообороте в момент, когда объект собрался, но еще не записался – в случае, показанном на слайде, в поле «Ответственный» подставится уже рассчитанный ответственный.

Как пример, я создал внутренний документ 1С:Документооборота из «Поступления товаров и услуг», и в качестве ответственного подставился Федоров как руководитель «Меркурия».

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

Подробнее о расширении возможностей настройки правил интеграции через обработчики событий «перед записью» и «после записи объекта» вы можете прочитать в отдельной статье.

Разработка универсального запроса в сервис DMService

Следующая доработка похожа на предыдущую и позволяет настраивать в правилах интеграции произвольную логику заполнения реквизитов на стороне 1С:Документооборота в зависимости от различных условий.

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

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

Здесь к нам на помощь опять приходит фантазия:

• Прямо внутри написания выражения мы прокидываем прокси.

• Через этот прокси мы вызываем специальный объект УниверсальныйЗапрос, куда с помощью текстовой строки закидываем код, который будет выполняться на стороне 1С:Документооборота.

• Ответом в данном случае ответом будет количество задач по рассчитанной организации. Универсальный запрос рассчитал его в 1С:Документообороте, вернул нам, и мы использовали это уже в условии нашего выражения.

Смысл такой же – чтобы все это заработало, мы должны на стороне 1С:Документооборота:

• добавить в наш XDTO-пакет DM объекты DM_prUniversalRequest и DM_prUniversalResponse, соответствующие универсальному запросу;

• и сделать определенную доработку в общем модуле ОбработкаЗапросовXDTO, где происходит обработка всех запросов из интегрированных систем.

Пользовательский интерфейс

Напоследок хочу немного поговорить про пользовательский интерфейс «Библиотеки интеграции с 1С:Документооборотом» и его небольшие проблемки. И первая проблема интерфейса библиотеки – это «единое окно» интегрируемой системы.

Казалось бы, работа с документами 1С:Документооборота в едином окне интегрируемой системы – это основное преимущество «Библиотеки интеграции». Но со временем в 1С:Документообороте появляются все новые и новые виды документов, и для каждого вида документа мы настраиваем свой реквизитный состав, чтобы все это выглядело по-разному и отвечало разным потребностям бизнеса в том или ином случае.

Сколько видов документов – столько и представлений в 1С:Документообороте. А единое окно, которое открывается в интегрируемой системе, всегда одно – оно статичное. И чтобы интерфейс документов в едином окне и в 1С:Документообороте выглядел более-менее одинаково, все, что вы делаете в 1С:Документообороте, нужно дублировать программированием на стороне интегрируемой системы.

Либо нужно просто смириться. Но тогда у пользователей в голове может возникать диссонанс – он хочет посмотреть данные «Трудового договора» в 1С:Документообороте, а там документ выглядит совсем по-другому. И документ «Поступление товаров и услуг» тоже выглядит совсем не так, как пользователь ожидал.

Что рекомендуется?

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

• Во-вторых, используя дополнительные реквизиты, у нас более или менее стандартизируется и выравнивается представления форм – у нас как на стороне интегрируемой системы они друг за другом идут, так и на стороне 1С:Документооборота.

Использование дополнительных реквизитов

Но что же делать, если бизнес просит нас раскидать эти дополнительные реквизиты по-человечески – перенести их на страничку «Реквизиты» вместо странички «Свойства»?

Тут можно сделать тоже небольшую инъекцию в саму подсистему «Дополнительные реквизиты» – добавить на стороне 1С:Документооборота в план видов характеристик «ДополнительныеРеквизиты» два строковых поля:

• «Скрипт обработки ДО»;

• и «Скрипт обработки ИС».

Смысл этих скриптов в том, что после стандартной прорисовки полей, соответствующих дополнительным реквизитам, мы дополнительно вызываем скрипт, который либо переместит куда-то наше созданное поле, либо накинет на него дополнительные свойства или обработчики «ПриИзменении».

Такое расширение подсистемы дополнительных реквизитов позволяет нам настраивать представление документов в конфигурации и в «едином окне» примерно одинаковым.

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

Результат – с помощью нашего скрипта мы в документе «Трудовой договор» переместили дополнительный реквизит «Основные обязанности» на закладку «Реквизиты».

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

А на стороне 1С:Документооборота мы вызываем выполнение наших скриптов в модуле УправлениеСвойствами в процедуре «ПриСозданииНаСервере».

Использование веб-интерфейса

Последнее, про что хочу рассказать в части пользовательского интерфейса – это про использование веб-интерфейса как замены стандартной формы, которая открывается при нажатии на ссылку «Документооборот».

Было несколько случаев, когда заказчики обращались ко мне с запросом: «Вот мы вносим изменения в 1С:Документооборот, редактируем кучу форм, у нас сотни видов документов. Нам так надоело это все переносить в интегрируемую систему, чтобы все эти доработки были продублированы. Давайте что-нибудь придумаем».

Мы вместо открытия стандартной формы обработки сделали открытие формы с полем HTML-документа. Заблаговременно прогружаем туда сеанс 1С:Документооборота, но пользователю эту форму показываем только тогда, когда он переходит из учетной системы по ссылке «Документооборот».

Мы активизируем форму и показываем в поле HTML-документа тот же самый документ, но в 1С:Документообороте. Причем эту форму можно открывать с такими параметрами, которые отсекают лишние элементы системы – панель разделов, панель открытых и другие, чтобы показывалась только форма нужного нам документа.

Таким же образом можно сделать и форму создания нового документа.

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

Но есть и минус, связанный с лицензиями. Раз мы здесь прогружаем конкретный сеанс конкретного 1С:Документооборота, он потребляет еще одну лицензию – пользователь будет одновременно работать и в своей системе, и в 1С:Документообороте. Если бы мы использовали только DMService, у нас лицензии в 1С:Документообороте не расходовались бы. Поэтому здесь приходится выбирать.

Подробно об идее открытия форм 1С:Документооборота через веб-клиент я в рамках доклада рассказать не успею – но вы можете прочитать о нем в отдельной статье.

Вопросы и ответы

Можно ли все эти доработки реализовать через расширение?

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

Вы осознаете размер дыры в безопасности, давая возможность написать скрипт в интегрируемой системе?

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

Тут приходится выбирать. Если для вас безопасность критична, нужно более аккуратно относиться к этим вопросам. Но есть компании, у которых отношение к этому менее критичное – там появляется больше гибкости.

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

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

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

Получается, что когда нужно выполнить запрос из интегрируемой системы, мы сначала под пользователями с полными правами обращаемся в 1С:Документооборот. Запрашиваем логин и пароль текущего пользователя из безопасного хранилища данных. И второй запрос делаем уже под авторизованным пользователем – авторизуемся под логином и паролем, которые нам вернул 1С:Документооборот.

Когда мы на стороне интегрируемой системы пишем много скриптов, появляется риск, что после обновления 1С:Документооборота при вызове скрипта будет ошибка. Как заранее отлавливать такие проблемы?

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

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

Главное – вовремя проинформировать ответственного человека.

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

У нас автоматической проверки нет, но реализовать ее, я думаю, можно.

Как я понял этот кейс про 1С:Документооборот второй версии. А для третьей версии это работает?

Библиотека интеграции для третьей версии ДО появилась совсем недавно, и сам я ее пока еще не пробовал (прим. ред. доклад от 6 октября 2022 года). Боюсь, что на практике мы ее пока нормально использовать не сможем, это достаточно опасно. Саму конфигурацию пробовал, она красивая, интересная, задачи прикольные, но есть ошибки.

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

У нас решение было простое. Мы просто разбивали эту работу на части, добавляли условное разделение – нужны нам изменения этого объекта или не нужны. Определяли это в коде или в настройках.

*************

Статья написана по итогам доклада (видео), прочитанного на конференции Infostart Event 2022 Saint Petersburg.