Интеграции: бизнес-логика

Домен интеграций объединяет внешние контуры платформы: обмен с 1С, ЭДО, почтовые/календарные провайдеры, шину сообщений и другие подключаемые сервисы. Цель домена — обеспечить предсказуемый двусторонний обмен данными между 1Формой и внешними системами без нарушения согласованности внутренних бизнес-процессов. Документ описывает основные направления, бизнес-правила, сценарии, зависимости и операционные риски. Аудитория — инженеры поддержки и разработчики, настраивающие и сопровождающие интеграции.

Основные направления

1. 1С-интеграция

• Конфигурация обмена и сценарии-конструкторы.
• Очередь событий 1С.
• Обработка входящих событий в реальном времени.

Обмен с 1С работает только в полной сборке. В сертифицируемой сборке (1F Certificate Edition, профиль UniForm.Barebone) он изъят: настройка конфигурации, приём событий и разбор очереди обмена недоступны, а маршруты обмена отвечают 404.

2. ЭДО и внешние документы

• Отправка/обработка документов через Diadoc/SBIS.
• Хранение связей и статусов документов.

3. Интеграционная очередь и шина

• Универсальная обработка событий по правилам обработки потоков.
• Повторные попытки и диагностика ошибок в MessageQueue.

4. Сервисные интеграции

• Exchange, auth providers, внешние API-коннекторы.

5. Веб-аналитика (Matomo)

Интеграция с Matomo (v2.256+) предоставляет аналитику использования системы. Требует настройки администратором (см. Интеграции — администрирование, § Matomo).

Что отслеживается:

• Типы посещений: прямые переходы, переходы с сайтов, из поиска, рекламных кампаний.
• Действия: загрузки файлов, переходы по ссылкам, длительность сессий.
• Цели и конверсии.
• Идентификаторы пользователей (связь действий между сессиями и устройствами).

Инструменты:

• Автоматические PDF/HTML-отчёты по email.
• Визуализации: круговые и столбчатые диаграммы, облака тегов.
• Экспорт: CSV, XML, PHP, Excel, JSON; REST API.
• Мобильные приложения Matomo (iOS / Android).

Представления: обзор посещений, журнал посещений, карта в реальном времени, география, устройства и ПО.

Бизнес-правила и основные сценарии

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

Бизнес-правила домена интеграций:

1. Любая интеграция должна иметь валидную конфигурацию и учётные данные.
2. Асинхронные процессы управляются политикой обработки потока (повтор / остановка / ошибка).
3. Ошибка во внешнем сервисе не должна скрыто менять внутреннее состояние как «успех».
4. Для критичных сценариев нужен операционный журнал с контекстом события.
5. Сбой необязательной части операции не отменяет уже выполненную работу: ошибка коннекторов, действий после изменения или пересчёта тегов и смарт-доступа откатывается отдельно, попадает в список некритичных ошибок и фиксируется в журнале синхронизации, а сохранение данных задачи завершается.
6. Состав интеграционных контуров зависит от сборки платформы: в сертифицируемой сборке часть контуров изъята, и недоступность такой интеграции — свойство поставки, а не сбой площадки.

Основные сценарии:

• Сохранение и валидация конфигурации интеграции.
• Приём и обработка входящего внешнего события.
• Фоновая обработка очереди и восстановление после ошибок.

Зависимости домена: tasks, ext-params, users-and-groups, calendar, mail, contracts.

Операционные риски:

• Неверное сопоставление (mapping) пользователей/объектов.
• Зависания очередей при ActionOnError = Stop.
• Ошибки сетевого доступа и истёкшие учётные данные.
• Синхронный внешний вызов из каскада «После смены ДП» выполняется с открытой транзакцией, поэтому свежие данные задачи не видны встречным запросам до её коммита. У виртуальных документов вызов 1С на переходе отложен до коммита, поэтому при недоступности 1С отправка остаётся в очереди и повторяется заданием.
• Частичный сбой при обработке события 1С не виден пользователю: данные задачи сохраняются, а сведения об ошибке остаются в списке некритичных ошибок и в журнале синхронизации.

При инцидентах проверять:

1. Сборку площадки — полная или сертифицируемая (UniForm.Barebone). В сертифицируемой сборке обмен с 1С изъят, поэтому «интеграция не работает» закрывается этой проверкой.
2. Логи интеграционного сервиса (1С/ЭДО).
3. Состояние MessageQueue, MessageQueueLog, MessageFlows.
4. Актуальность конфигурации и доступность внешнего сервиса.