Описание требований к интеграции систем – стандартная задача для системного или бизнес-аналитика. Но вы можете столкнуться со сложностями, если раньше не решали ее.
Я хочу поделиться своим опытом и рассказать о том, чему нужно уделить внимание, если перед вами стоит задача по написанию требований к интеграции систем. Эта статья будет посвящена файловому обмену.
(О требованиях к интеграции через 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-файла]
Для формирования текста XML-сообщения из [Название Системы-источника] должны использоваться XDTO-пакеты.
XSD-схема: [XSD-схема]
Таблица 3. Описание атрибутов, пример
Алгоритм обработки файлов, правила валидации
Далее приступаем к описанию алгоритма обработки.
Для каждой строки интеграции, необходимо описать проверки:
Наличие сущности в Системе и что делать, если сущность не найдена. Как минимум, тут есть два варианта: создать сущность или вывести в лог ошибку.
Проверки на целостность данных, например, есть ли у дочерней сущности родитель, соответствуют ли передаваемые значения внутренней логике Системы?
Для каждой строки, необходимо описать непосредственно сам алгоритм
Что должно происходить в системе? Создание, изменение, удаление сущностей? Что происходит с сущностью при этих действиях, что записывается в атрибуты сущности.
Здесь могут быть выявлены дополнительные проверки при выполнении каждого из указанных действий. Например, мы пытаемся удалить сущность, у которой уже есть связанные сущности. В этом случае мы должны проанализировать эти связи и принять решение, можно что-то удалять или нет. Или, например, при корректировке суммы договора получилось отрицательное значение и согласно требованиям, это ошибка. Необходимо прописать и согласовать с Заказчиком правила обработки таких ситуаций.
Пример
При загрузке информации Система должна выполнить для каждой карточки объекта ИС, передаваемой в XML-файле:
1. Найти в [Название сущности] элемент, содержащий в поле [Атрибут сущности]
значение тега [тег] передаваемой карточки XML-файла;
2. Если элемент найден, то обновить поля [Название сущности] следующим образом:
2.1. [Описание алгоритма при обновлении сущности]
2.2. Записать в лог информацию «Обновлен элемент «[Title]», ID [ID]».
3. Если карточка не найдена, то создать новый элемент в [Название сущности], при этом:
3.1. [Описание алгоритма при создании сущности]
3.2. Записать в лог информацию «Создан элемент «[Title]», ID [ID]».
Если есть загрузка из нескольких источников одной и той же сущности
В этом случае желательно разделить потоки данных на уровне структуры. Т.е. явно указывать в одном из служебных атрибутов сущности, откуда пришла та или иная запись. Даже если нет необходимости явно различать источник данных в пользовательском интерфейсе, такое разделение поможет при разборе ошибок.
Системные и архитектурные ограничения
К таким ограничениям может относиться как несоответствие структуре базы данных, так и системные ограничения на получение файлов больших размеров. Ограничения могут быть разной степени тяжести. В одном случае достаточно будет прописать перечень форматов и размер передаваемых файлов. В другом случае могут возникнуть серьезные сложности, если структура передаваемых файлов, и это понятно уже на берегу, не ляжет на структуру данных в Системе-приемнике. Сможете ли вы решить эту ситуацию на уровне алгоритма, зависит от уровня сложности задачи. Но такие ограничения всегда лучше продумать заранее.
Проверки, излишне требовательные к данным
Такие проверки могут обернуться проблемами при приемке и тестировании интеграции на промышленных данных.
Пример проверки
Необходимо проверить формат значения в строке «Test»:
[ID1 в формате XXX]-[ID2 в формате ZZZ]-[Date в формате DD/MM/YYYY]-[CityName].
Параметр CityName в этой строке содержит название города. Если мы попытаемся проанализировать строку с учетом названия города, то столкнемся с практически непредсказуемым содержанием пробелов и тире в названии городов. Это может привести к тому, что часть данных при загрузке данных окажется невалидной из-за этой проверки.
Поэтому одно из решений такой ситуации – не анализировать CityName, а проверять формат двух первых ID и даты. Содержание и количество символов в этих параметрах более предсказуемо.
Журналирование
Далее нужно описать, есть ли у Администратора возможность просмотреть информацию по:
Запланированным заданиям с временем следующего запуска задания.
Выполняющимся на текущий момент заданиям с временем запуска задания и статусом задания.
Истории выполненных заданий со временем последнего выполнения, длительностью и статусом выполнения.
Хорошо, когда журнал системных событий по каждому запуску интеграции содержит:
Дату и время запуска.
Инициатор запуска (система, либо пользователь).
Длительность выполнения интеграции.
Наименование внешней системы.
Количество обработанных записей,
а также детализацию в разрезе каждого запуска:
o Время начала обработки записи.
o Время окончания обработки записи.
o Результат обработки (успешно, предупреждение, ошибка).
o Сведения об ошибке.
Имеет смысл указать, где Администратор может посмотреть эту информацию.
Необходимо продумать, какие события на каком уровне будут храниться. Например, на уровне Information должны логироваться действия по созданию и обновлению всех сущностей и полей. А в случае возникновения ошибок, сообщения о них должны заноситься в логи на уровне Warning.
Не пишите в требованиях бездумно фразу «записать в логи ошибку». Коллега-разработчик может записать в логи все типы событий (и ошибки, и информацию, и предупреждения) на уровне Error. Это может неприятно закончится при приемке интеграции Заказчиком.
Разграничение прав
Не всегда требуется описывать, кто и что видит при отработке сценариев интеграции систем. Чаще всего доступом к запуску и отключению механизма интеграции обладает Администратор.
Но если у вас решение конфликтов при интеграции ложится на плечи выделенного пользователя или роли, то нужно указать, куда у этого пользователя есть доступ и какими правами он обладает.
Заключение
Итак, эта статья была посвящена файловому обмену.
О моментах, на которые стоит обратить внимание для других типов взаимодействия между системами, я расскажу в следующих статьях.