Описание требований к интеграции (часть 1). Файловый обмен
Обновлено: 10 апр. 2021 г.
Описание требований к интеграции систем – стандартная задача для системного или бизнес-аналитика. Но вы можете столкнуться со сложностями, если раньше не решали ее.
Я хочу поделиться своим опытом и рассказать о том, чему нужно уделить внимание, если перед вами стоит задача по написанию требований к интеграции систем. Эта статья будет посвящена файловому обмену.
(О требованиях к интеграции через API вы можете почитать тут: Часть 2.)
Настройки подключения и расписание запуска
Как правило написание требований аналитиком начинается с того, как будет осуществляться интеграция. Начните описание со следующих пунктов:
Тип взаимодействия. В нашем случае - файловый обмен.
Протокол взаимодействия. Это может быть обычный открытый FTP протокол либо защищенные протоколы: FTPS (FTP через защищенный криптографический протокол SSL), SFTP (с использованием защищенного протокола SSH).
Настройки подключения. Путь к FTP-серверу, учетные записи для подключения к нему. Также можно указать, чьими силами будет осуществляться настройка доступа: Заказчика или Исполнителя.
Условия запуска обмена. Это могут быть разные события: изменился статус сущности, наступило время, заданное в расписании, пользователь нажал кнопку и т.д.
Расписание запуска обмена. Если условием запуска механизма информационного обмена является расписание, то указывается периодичность запуска (например, ежедневно, еженедельно и т.д.), осуществляющего разбор и обработку, а также время запуска. Также можно указать, должна ли быть возможность отключения запуска, возможность принудительного запуска в любой момент, вне зависимости от настроенного расписания. В некоторых случаях могут быть установлены дополнительные правила для расписания. Например, если на момент заданного времени старта задачи нет данных, то повторять запуск каждые X минут Y раз. Если файл не появился, то записать в лог ошибку.
Пример
Интеграция с внешней системой [Название внешней Системы] должна выполняться с помощью задачи (job) [Название задачи] в соответствии с указанным в [Место настроек расписания, у разных систем свое] расписанием.
При запуске задачи Система обращается к папке на FTP-сервере по указанному в настройках задачи пути и принимает XML-файл установленного формата [здесь может быть любой другой формат: CSV, JSON, BIN, структурированный TXT, и др.].
Для загрузки данных на стороне [Название принимающей Системы] необходимо создать техническую доменную учетную запись (см. таблицу 1), выполняющую получение данных из FTP-каталога и заполнение [указать что заполняем, таблицу БД, список и т.п.]. Для создаваемой учётной записи (УЗ) должен быть установлен запрет интерактивного входа [зависит от требований].
Хранение учетных данных доменной УЗ предполагается с использованием хранилища учетных данных авторизации в службе [Название службы].
Для подключения к FTP серверу и проверки корректности загрузки данных необходимо предоставить доступ к FTP серверу для УЗ, перечисленных в таблице 1 (должно быть выполнено силами [Ответственная сторона]).
Таблица 1. Перечень УЗ для доступа к FTP - серверу
Где и как забираем данные
Далее необходимо описать требования к тому месту, откуда будут забираться данные.
Т.к. мы говорим о файловом обмене, то может возникнуть потребность проанализировать структуру папок, например, на FTP-сервере, а также перемещать или удалять файлы после обработки.
Если названия папок сформированы по шаблону, то этот шаблон необходимо описать. В названии папок не должны присутствовать пробелы и специальные символы, которые могут быть приняты парсером как разделители.
Кстати, может возникнуть необходимость забирать файлы не только из папок. Они могут приходить по почте, или пользователи могут загружать файлы вручную. В этом случае порядок описания тот же, просто описываются требования не к FTP, а к почтовому ящику или Exchange серверу.
Пример
Необходимо организовать объем доступного дискового пространства на FTP-сервере не менее [Объем] Гб.
Путь к FTP-серверу: [Путь]
XML-файлы, предназначенные для загрузки в [Название принимающей Системы] должны помещаться в папку «XXX_Download».
После передачи XML-файла, Система должна:
Переместить успешно обработанный файл в папку «XXX_Loaded».
Если файл обработан неуспешно, то переместить неуспешно обработанный файл в папку «XXX_Error». Неуспешно обработанными должны считаться файлы:
o пустые,
o файлы, с некорректной структурой данных,
т.е. не соответствующие XSD-схеме, приведенной ниже.
Файл должен быть удален из папки «XXX_Loaded» через [Период времени] с момента обработки.
Из папки «XXX_Error» файлы не должны удаляться автоматически.
Кстати, про удаление данных. Есть смысл предусмотреть хранение исходных данных, перемещение их в архив после обработки или временные таблицы. Т.е. то место, где будут хранится исходные полученные файлы. Не всегда для этого есть возможность, но если есть, то они могут выручить при разборе конфликтных ситуаций и ошибок.
Предварительные работы до старта интеграции
Не всегда требуется отдельно описывать, что должно быть сделано до старта интеграции. Но если должны быть проведены некие работы, например, выверка справочника, заполнение реквизитов, настройка, то необходимо прописать состав работ и указать ответственную сторону.
Пример
Перед началом синхронизации необходимо выполнить сопоставление элементов справочника [Название справочника] в системе [Название Системы-источника] с элементами справочника [Название справочника] в системе [Название Системы-приемника].
Сопоставление должно быть проведено в системе [Название Системы-приемника] силами [Ответственная сторона].
Анализ данных файлов
Далее приступаем к анализу и описанию содержимого файла.
Заказчик может передать пример файла и, если повезет, спецификацию с описанием структуры. В любом случае, необходимо проверить пример и документ на актуальность и достоверность.
Как проверить на актуальность? Если доступа к данным нет, имеет смысл попросить провести для вас демонстрацию Систем и данных, которые будут передаваться или получаться.
После этого необходимо описать:
Если название файла формируется по шаблону, то описать сам шаблон. По аналогии с названием папок, в названии файлов не должны присутствовать пробелы и специальные символы, которые могут быть приняты парсером как разделители или стоп-символы.
Описать атрибуты и их тип, обязательность, допустимые значения, размер полей и т.д.
Необходимо приложить в спецификацию заполненный пример файла и схему данных. В нашем случае это будет XSD-схема.
Если требуется создание новых сущностей, также описать их.
Для описания информации об атрибутах можно воспользоваться таблицей 2.
Таблица 2. Описание атрибутов
Не забываем о проверках на ошибочные ситуации и поведение нашей системы в них:
Если название файла не соответствует шаблону названия.
Если файл не соответствует формату.
Если нарушена структура и порядок следования атрибутов.
Если файл пуст.
Если обязательные атрибуты не заполнены.
Если вам нужно возвращать результат обработки в передающую Систему, то все то же самое необходимо описать для ответного файла.
Пример
Название XML-файла должно формироваться по шаблону:
NNN_[Дата формирования файла в формате YYYY-MM-DD]_[Время формирования файла в формате HH-MM-SS в 24-часовом формате].
Например, NNN_2017-07-04_04-02-15
Пример XML-файла с данными из [Название Системы-источника]: [Пример XML-файла]