Добавлено описание служ программного интерфейса

docs/puml/ERArchitectureIntegrationsSubsystem.puml

@@ -83,6 +83,7 @@ entity "Справочник: Интеграционные потоки" as eInt
     ТочкаВхода : строка (неогр)
     ПользовательскаяФункция : uuid <<FK>>
     ИзмененВручную : булево
+    НаправлениеПотока: uuid <<FK>>
     --
     Параметры входа 
     --
@@ -116,6 +117,12 @@ enum "Перечисление: Типы параметров интеграци
     + Дата
 }
 
+enum "Перечисление: Направления интеграционных потоков" as eIntDirections {
+    + Исходящий
+    + Входящий
+    + Служебный
+}
+
 entity "Справочник: История интеграции" as eIntHistory {
     *УникальныйИдентификатор : uuid <<generated>>
     --
@@ -134,6 +141,8 @@ entity "Справочник: История интеграции" as eIntHistor
     Пользователь : uuid <<FK>>
     ДлительностьОбмена : число (5, 0)
     ДлительностьВызова : число (5, 0)
+    ИмяФайлаСообщения: Строка (150)
+    ФайлСообщения: хранилище значений
     --
     Объекты интеграции
     --
@@ -147,6 +156,8 @@ enum "Перечисление: Статусы интеграции" as eIntStat
     + Загружено
     + ОшибкаВыгрузки
     + ОшибкаЗагрузки
+    + Служебный
+    + ОшибкаСлужебного
 }
 
 enum "Перечисление: Форматы интеграции" as eIntFormates {
@@ -187,6 +198,7 @@ eIntFlows <- eIntFlows : Родитель
 eIntFlows --> eIntSettings : НастройкаИнтеграции
 eIntFlows --> eUserFunctions : ПользовательскаяФункция
 eIntFlows --> eIntParamsTypes : Тип (параметры входа)
+eIntFlows --> eIntDirections : НаправлениеПотока
 
 eIntHistory --> eSysInt : ИнтегрируемаяСистема
 eIntHistory --> eIntStatuses : Статус

docs/УправлениеИнтеграциями.md

@@ -37,24 +37,114 @@
     - **пбп_SimpleKafkaAdapter** - содержит архив с компонентой подключения и взаимодействия с брокером сообщений Kafka (см. [Simple Kafka Connector 1C](https://github.com/NuclearAPK/Simple-Kafka_Adapter));
 
 5. Общие модули
-    - **пбп_ИнтеграцииСервер** - модуль программного интерфейса, где описана серверная логика взаимодействия с подсистемой управления интеграцями и функции взаимодействия с другими системами (подробно см. в главе [Реализованные методы](#реализованные-методы));
-    - **пбп_КоннекторHTTP** - модуль программного интерфейса, предоставляющий удобную обертку вызовов REST-методов HTTP-сервисов (см. [Коннектор: удобный HTTP-клиент](https://github.com/vbondarevsky/Connector)).
+    - **пбп_ИнтеграцииСервер** - модуль программного интерфейса, где описана серверная логика и функции взаимодействия с другими системами (подробно см. в главе [Реализованные методы](#реализованные-методы));
+	- **пбп_ИнтеграцииСлужебный** - модуль служебного программного интефейса, где описана логика взаимодействия с объектами подсистемы, а также вспомогательные экспортные функции (подробно см. в главе [Служебный программный интерфейс](#служебный-программный-интерфейс));
+	- **пбп_ИнтеграцииFTPSFTP** - модуль программного интерфейса, где описана серверная логика и функции взаимодействия с FTP и SFTP серверами (подробно см. в главе [Реализованные методы](#реализованные-методы));
+    - **пбп_КоннекторHTTP** - модуль программного интерфейса, предоставляющий удобную обертку вызовов REST-методов HTTP-сервисов (см. [Коннектор: удобный HTTP-клиент](https://github.com/vbondarevsky/Connector));
+	- ***пбп_МетодыРегламентныхЗаданийСервер** - модуль программного интерфейса, являющийся "единым хранилищем" экспортных методов регламентных заданий;
      
 "*" В рамках общего отказа от предопределенных значений в справочниках ПБП необходимо уточнение: предопределенные значения справочника **пбп_ТипыИнтеграций** используются по причине того, что в них перечислены общие, стандартизированные и широкоиспользумые типы, которые, в свою очередь, влиют на параметризацию справочников **пбп_НастройкиИнтеграции**, **пбп_ИнтеграционныеПотоки** и **пбп_ИсторияИнтеграции**.
 
 ## Ролевая модель
 
 Для создания и настройки объектов подсистемы управление интеграциями существует роль **пбп_РедактированиеНастроекИнтеграции**.
+Для просмотра справочника истории интеграции существует роль **пбп_ПросмотрИсторииИнтеграции**.
 
 ## Связанные подсистемы
 
 1. [Предопределенные значения](docs/ПредопределенныеЗначения.md)
 2. [Переопределения методов БСП](docs/ПереопределениеМетодовБСП.md)
 3. [Пользовательские функции](docs/ПользовательскиеФункции.md)
+4. [Загрузка файла через табличный документ](docs/ЗагрузкаФайлаЧерезТабличныйДокумент.md)
 
 ## Порядок взаимодействия
 
-Для создания настроек интеграции необходимо создать предопределенные элементы справочников **пбп_ИнтегрируемыеСистемы**, **пбп_НастройкиИнтеграции**, **пбп_ИнтеграционныеПотоки** с помощью подсистемы предопределенных значений (см. [Предопределенные значения](docs/ПредопределенныеЗначения.md)). Рассмотрим заполнение данных на нескольких примерах:
+Взаимодействие с подсистемой будет отличаться для разных типов интеграции, но можно выделить общие шаги для любого типа:
+1. После определения типа интеграции, необходимо заполнить информацию о настройках в справочниках подсистемы. Для создания настроек интеграции необходимо создать предопределенные элементы справочников **пбп_ИнтегрируемыеСистемы**, **пбп_НастройкиИнтеграции**, **пбп_ИнтеграционныеПотоки** с помощью подсистемы предопределенных значений (см. [Предопределенные значения](docs/ПредопределенныеЗначения.md)). Создание не предопределенных потоков <ins>допускается только в случае файловых обменов при использовании пользовательских функций</ins>;
+2. Если это "предопределенная" интеграция (без использования пользовательской функции), то вызов должен быть обернут в запись в справочник истории интеграции для хранения в нем логов;
+3. Подбор и реализация вызова нужного метода интеграции в зависимости от ее типа;
+4. Пост-обработка полученного в п.3 результата вызова;
+5. Запись лога обмена в справочник истории интеграции;
+
+### Заполнение предопределенных значений настроек
+
+Для заполнения предопределенных значений необходимо перейти в общий модуль "пбп_ПредопределенныеЗначенияПереопределяемый". В соответствующих объектам метаданных процедурах добавить строки в таблицу предопределенных по обязательным полям:
+```bsl
+Процедура ПредопределенныеЗначенияИнтегрируемыеСистемы(Таблица) Экспорт
+
+   // Добавление
+   НоваяСистема = Таблица.Добавить();
+   НоваяСистема.Наименование           = "Система N";
+   НоваяСистема.ИдентификаторНастройки = "СистемаN";
+   // КонецДобавления
+
+КонецПроцедуры
+
+Процедура ПредопределенныеЗначенияНастройкиИнтеграции(Таблица) Экспорт
+    
+   // Добавление
+   НоваяНастройка = Таблица.Добавить();
+   НоваяНастройка.Наименование           = "Интеграция с системой N";
+   НоваяНастройка.ИдентификаторНастройки = "ИнтеграцияССистемойN";
+   // Параметром передается идентификатор настройки интегрируемой системы
+   НоваяНастройка.ИнтегрируемаяСистема   = пбп_ИнтеграцииСлужебный.ИнтегрируемаяСистема("СистемаN");
+   // Заполняем необходимый тип интеграции из предопределенных значений справочника, например "SFTP"
+   НоваяНастройка.ТипИнтеграции          = Справочники.пбп_ТипыИнтеграций.SFTP;
+   // Указываем тип авторизации. Для большинства типов интеграций - это базовая.
+   // Для интеграций с типом "брокеры сообщений", "REST API" и "SOAP" доступна авторизация через bearer-токен (JWT-токен)
+   НоваяНастройка.ТипАвторизации         = Перечисления.пбп_ТипыАвторизации.Базовая;
+   // КонецДобавления
+
+КонецПроцедуры
+
+Процедура ПредопределенныеЗначенияИнтеграционныеПотоки(Таблица) Экспорт
+
+   // Добавление
+   НовыйМетод = Таблица.Добавить();
+   НовыйМетод.Наименование           = "Интеграционный поток системы N";
+   НовыйМетод.ИдентификаторНастройки = "ИнтеграционныйПотокСистемыN";
+   // Направление потока служит логическим разделением потоков по отношению к системе-корреспонденту:
+   // Исходящий - ИС-отправитель - наша система, ИС-получатель - сторонняя;
+   // Входящий - ИС-отправитель - сторонняя система, ИС-получатель - наша;
+   // Служебный - для служебных методов, по типу отправки оповещений / логов / очистки файлов и т.д.
+   НовыйМетод.НаправлениеПотока      = Перечисления.пбп_НаправленияИнтеграционныхПотоков.Исходящий;
+   // КонецДобавления
+
+КонецПроцедуры
+```
+Идентификатор настройки каждого объекта должен быть уникальным в рамках одного типа метаданных.
+После инициализации и заполнения предопределенных элементов в коде, необходимо зайти в пользовательский режим в формы списков соответствующих справочников и нажать на кнопку "Заполнить предопределенные" в следующей последовательности: интегрируемые системы, настройки интеграции, интеграционные потоки:
+
+![image](images/ЗаполнениеПредопределенныхПодсистемыИнтеграции.png)
+
+### Служебный программный интерфейс
+
+Как видно из прошлого примера (заполнения предопределенных значений настройки интеграции), для поиска интегрируемой системы по идентификатору настройки вызывается метод общего модуля пбп_ИнтеграцииСлужебный. Помимо данной функции в этом модуле служебного программного интерфейса реализована следующая логика и методы:
+
+1. **Работа с историей интеграции**:
+* ПолучитьСтруктуруЗаписиИстории - возвращает структуру со всеми необходимыми значениями для заполнения записи истории интеграции;
+* СоздатьСообщениеИсторииИнтеграции - создает запись справочника История интеграции с информацией о событии интеграции (лог). В первом параматре передается заполненная структура, полученная из функции ПолучитьСтруктуруЗаписиИстории;
+* ДобавитьЗаписьВПротоколОбмена - дополняет значение ключа "ПротоколОбмена" структуры строкой события через разделитель, полученной из функции ПолучитьСтруктуруЗаписиИстории. В первом параметре передается структура записи истории, во втором - текст добавляемого сообщения, в третьем - разделитель (по-умолчанию: '";" + Символы.ПС');
+* ПолучитьПредставлениеТекстЗапросаВнешнегоИсточникаДанных - возвращает представление текста запроса для внешнего источника данных. Вместо имен параметров запроса в его тексте подставляются значения параметров. Первым параметром передается запрос, который необходимо конвертировать в строку;
+2. **Работа с данными подсистемы**:
+* ПолучитьСтруктуруНастроекИнтеграции - возвращает структуру со значениями реквизитов настроек интеграции, включая данные безопасного хранилища (логин, пароль / токен). В параметре указывается ссылка на настройку интеграции;
+* ПолучитьСтруктуруПотокаИНастроекИнтеграции - аналогично предыдущей функции, но получает данные по интеграционному потоку, добавляя в структуру данные по точке входа. В параметр передается ссылка на интеграционный поток;
+* ПолучитьСтруктуруПараметровВхода - возвращает структуру, полученную из реквизитов табличной части "ПараметрыВхода" интеграционного потока. Вторым параметром указывается заполнять значения по умолчанию для параметров или нет. В случае, если параметры заполняются по умолчанию, то каждой строке параметра будет выведено значение, заполненное в табличной части, конвертированное в JSON-формат (булево: "true" или "false"; дата: "yyyy-MM-dd" и т.д.). В противном случае, значение будет конвертировано в тип 1С, указанный в колонке "Тип" табличной части;
+* ИнтеграционныйПоток - возвращает интеграционный поток по идентификатору настройки;
+* ИнтегрируемаяСистема - возвращает интегрируемую систему по идентификатору настройки;
+* НастройкаИнтеграции - возвращает настройку интеграции по идентификатору настройки;
+
+### Заполнение истории интеграции
+
+Рассмотрим заполнение данных на примерах по типам интеграций:
+
+### Файловые интеграции
+
+### Прямое подключение к базе данных
+
+### Вызов внешней процедуры
+
+### Брокеры сообщений
 
 #### Заполнение настроек для обмена через FTP-Сервер
 Заходим в общий модуль "пбп_ПредопределенныеЗначенияПереопределяемый" и добавляем следующий код: