Опис вимог до інтеграції систем – стандартне завдання для системного або бізнес-аналітика. Але ви можете зіштовхнутися із складнощами, якщо раніше не виконували його. Я хочу поділитися своїм досвідом і розповісти про те, на що слід звернути увагу, якщо перед вами стоїть завдання щодо написання вимог до інтеграції систем. Ця стаття буде присвячена файловому обміну.
(Про вимоги до інтеграції через 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». Неуспішно відпрацьованими повинні вважатися файли:
пусті,
файли з некоректною структурою даних, тобто такі, що не відповідають XSD-схемі, наведеній нижче.
Файл повинен бути видалений із папки «XXX_Loaded» через [Проміжок часу] з моменту опрацювання.
З папки «XXX_Error» файли не повинні видалятися автоматично.
До речі, щодо видалення даних. Є сенс передбачити зберігання вихідних даних, переміщення їх в архів після опрацювання або тимчасові таблиці. Тобто те місце, де будуть зберігатися вихідні отримані файли. Не завжди для цього є можливість, але якщо є, то вони можуть виручити при розборі конфліктних ситуацій та помилок.
Попередні роботи до старту інтеграції
Не завжди вимагається окремо описувати, що має бути зроблено до старту інтеграції. Але якщо треба провести певні роботи, наприклад, вивірка довідника, заповнення реквізитів, налаштування, то необхідно прописати склад робіт і вказати відповідальну сторону.
Приклад
Перед початком синхронізації необхідно виконати зіставлення елементів довідника [Назва довідника] в системі [Назва Системи-джерела] з елементами довідника [Назва довідника] в системі [Назва Системи-приймача].
Зіставлення треба провести в системі [Назва Системи-приймача] силами [Відповідальна сторона].
Аналіз даних файлів
Далі переходимо до аналізу й опису вмісту файлу.
Замовник може передати приклад файлу і, якщо пощастить, специфікацію з описом структури. У будь-якому випадку, необхідно перевірити приклад і документ на актуальність й достовірність.
Після цього необхідно описати:
Якщо назва файлу формується по шаблону, то описати сам шаблон. За аналогією з назвою папок, у назві файлу не повинно бути пробілів чи спеціальних знаків, які можуть бути сприйняті парсером як роздільники або стоп-символи.
Описати атрибути і їх тип, обов’язковість, допустимі значення, розмір полів тощо.
Необхідно додати до специфікації заповнений приклад файлу і схему даних. У нашому випадку це буде XSD-схема.
Якщо вимагається створення нових сутностей, також описати їх.
Для опису інформації про атрибути можна скористатися таблицею 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 та дати. Зміст та кількість символів у цих параметрах більш передбачувані.
Журналювання
Далі потрібно описати, чи має Адміністратор можливість переглянути інформацію щодо:
Запланованих завдань із часом наступного запуску завдання.
Завдань, що виконуються на поточний момент, із часом запуску завдання та статусом завдання.
Історій виконаних завдань із часом останнього виконання, тривалістю та статусом виконання.
Добре, коли журнал системних подій щодо кожного запуску інтеграції містить:
Дату та час запуску.
Ініціатор запуску (система або користувач).
Тривалість виконання інтеграції.
Найменування зовнішньої системи.
Кількість оброблених записів,
а також деталізацію в розрізі кожного запуску:
Час початку обробки запису.
Час закінчення обробки запису.
Результат обробки (успішно, попередження, помилка).
Відомості про помилку.
Є сенс вказати, де Адміністратор може переглянути цю інформацію.
Необхідно продумати, які події на якому рівні зберігатимуться. Наприклад, на рівні Information повинні логуватися дії щодо створення та оновлення всіх сутностей та полів. А у разі виникнення помилок, повідомлення про них повинні заноситись у логи на рівні Warning.
Не пишіть у вимогах бездумно фразу "записати в логи помилку". Колега-розробник може записати в логи всі типи подій (і помилки, і інформацію, і попередження) на рівні Error. Це може мати негативні наслідки під час приймання інтеграції Замовником.
Розмежування прав
Не завжди потрібно описувати, хто і що бачить під час відпрацювання сценаріїв інтеграції систем. Найчастіше доступ до запуску та відключення механізму інтеграції має Адміністратор.
Але якщо у вас вирішення конфліктів при інтеграції лягає на плечі виділеного користувача або ролі, то потрібно вказати, куди цей користувач має доступ і які права він має.
Висновок
Отже, цю статтю було присвячено файловому обміну.
Про моменти, на які варто звернути увагу для інших типів взаємодії між системами, я розповім у наступних статтях.
(Переклад виконано: Viktoriia Drachenko, Gobov Denys)