Інструкція з налаштування структурованого документа



Дана інструкція описує налаштування та порядок роботи з структурованим документом.


1 Авторизація в системі

Для авторизації на платформі перейдіть за посиланням https://doc.edi-n.com/auth та введіть свої логін = email і пароль на формі авторизації. Детальна інформація з авторизації міститься в «Інструкції з авторизації».

2 Налаштування структурованого документа

У межах документообігу EDIN-DOCflow, поряд із неструктурованими (звичайними) документами, реалізована можливість передачі структурованих (XML) документів у комплекті. Визначення типу документа як структурованого відбувається на етапі налаштування типів документів у межах компанії.

Для налаштування структурованого документа перейдіть в меню «Налаштування компанії» – «Мої компанії» та оберіть потрібну компанію зі списку, натиснувши на її назву. У формі редагування, що відкриється, перейдіть до вкладки «Документи». Вкладка містить вже закріплені за компанією типи документів. Для додання нового документа з ознакою «Структурований» натисніть на кнопку «Додати»:

../../_images/instr_struct_doc_1.png

У формі додання типу документа заповніть обов’язкові поля:

  • Назва – поле призначене для введення літер, цифр або спеціальних символів, мінімальна кількість знаків – три

  • Код - поле призначене для введення літер, цифр або спеціальних символів, мінімальна кількість знаків – один. Значення, введене в поле «Код», має бути унікальним у межах компанії. У разі введення значення, що вже використовується, система відобразить відповідне повідомлення.

Наступним кроком встановіть відмітку напроти типу документа, а саме «Структурований», і натисніть «Зберегти»:

../../_images/instr_struct_doc_2.png

Документ буде збережено та відображено в переліку типів документів з позначкою «Структурований» иконка-кубик:

../../_images/instr_struct_doc_3_02.png

Для редагування назви або коду типу документа натисніть на його назву у загальному переліку, внесіть потрібні зміни та натисніть «Зберегти».

2.1 Опис (налаштування) структури документа

Для опису і зберігання структури документа використовується текстовий формат JSON. Параметри, що прописуються у налаштуваннях структури, визначають порядок відображення на web-формі елементів структури документа і правила їх заповнення.

При описі структурованого документа використовуються певні типи даних, кожен з яких є окремим типом елемента і описується у вигляді окремої структури зі своїм переліком параметрів, наприклад:

../../_images/json.png

Основні параметри, що використовуються при описі структурованого документа:

  • id — ідентифікатор елемента, назва елемента в документі XML

  • title — назва елемента на web-формі при заповненні документа

  • readonly (true / false) — визначає можливість редагування відповідного елемента структури

  • attribute (true / false) — при встановленому параметрі відповідний елемент є атрибутом в XML-файлі, при невстановленому — тегом

  • optional (true / false) — визначає обов’язковість заповнення поля

  • type — спеціальна секція для визначення типу елемента

  • data — спеціальна секція для визначення заповнення елемента певними значеннями, посиланнями на об’єкти плафторми, тощо

  • fields — спеціальна секція для опису масиву полів для типів елементів object і array

  • function — function - задана функція виконання вибірки з довідника або математичних операцій по вже введеним інших полях документа (функції updateDictLink і arithmeticOperate)

Зверніть увагу!

Імена елементів у структурі XML повинні дотримуватись наступних правил написання імен:

  • Імена можуть містити літери, цифри та інші символи, але,

  • Імена не можуть починатися з цифри або символу пунктуації

  • Імена не можуть починатися з поєднання «xml» (або XML, або Xml і т.п.)

  • Імена не можуть містити пробіли

Кожен тип елемента описується у вигляді окремої, особливої структури зі своїм переліком параметрів. На поточний момент реалізовані наступні типи:

  • рядок (string) - дозволяє зберігати текстові значення

  • число (number) - дозволяє зберігати числові значення зі знаком і розділювач дробової частини, кількість цифр після коми

  • дата (date) - дозволяє зберігати дату без часу

  • час (time) - дозволяє зберігати час

  • перелік (enum) - дозволяє задати список значень з можливістю вибору одного значення

  • об’єкт (object) - дозволяє вказати елемент, який є вузлом, структурою зі своїми полями

  • масив (array) - дозволяє вказати елемент, який є таблицею або масивом значень зі своїми полями

Таблиця 1 - Типи даних (типи елементів) із параметрами, що застосовуються при описі структурованого документа:

Тег

Значення

Опис

Параметр

Приклад

string

рядок

Для внесення і збереження текстових значень

minLength — мінімальна кількість символів не меньше 1;

maxLength — максимальна кількість символів не більше 9999;

regexp — регулярний вираз

case (реєстр) — визначає, в якому реєстрі використовувати рядок (upper, lower, camel)

«string»: {

«minLength»: 1,

«maxLength»: 10,

«regexp»: «….»,

«case»: «upper│lower│camel»

},

number

число

Для внесення і збереження числових значень

type (тип) — позитивне / негативне;

decimal (дріб) — вказується кількість цифр після коми (для дробів)

«number»: {

«type»: «positive│negative»,

«decimal»: 3

},

date

дата

Для внесення і збереження дати, без позначки часу

format — вказується формат дати, где Y - рік, M - місяць, D - день

«type»: { «date»: { «format»: «DD.MM.YYYY» }

time

час

Для внесення і збереження часу

format — вказується формат часу, де H - година, M - хвилина, S - секунда; при цьому H використовується для 24-годинного формату, h - для 12-годинного

«type»: {

«time»: {

«format»: «HH:MM:SS»

}

enum

перелік

Для внесення і збереження списку значень із можливістю вибору одного значення

value (значення) — значення, яке буде додане в тег; name (назва) — назва значення

«enum»: [

{

«value»: «Значение которое будет добавлено в документ»,

«name»: «Название значения»

}

]

object

об’єкт

Для позначення елемента, який є структурою зі своїми полями

«type»: { «object»: {} },

array

масив

Для позначення елемента, який є таблицею або масивом значень зі своїми полями

minLength — мінімальна кількість рядків не менше 1;

maxLength — максимальна кількість рядків не более 9999;

«array»: { «minLength»: 1, «maxLength»: 10 },

Секція data описує правила і можливості щодо заповнення елемента.

Зверніть увагу!

Тег «ref» заповнюється посиланням на комплект лише при формуванні зовнішнього документа у розділі «Документи», наприклад: «ref»: «pack.senderCompany.companyId». При формуванні внутрішнього документа у розділі «Внутрішні документи компанії» потрібно використовувати посилання на документ, наприклад: «ref»: «doc.senderCompany».

Таблиця 2 - Структура секції data:

Функції:

  1. updateDictLink - здійснює вибірку з довідника за шаблоном: $updateDictLink('Акт.Послуги[2].Код', 'code')$, де

  • Акт.Послуги[2].Код - маршрут до поля, яке потрібно заповнити code зі довідника;

  • code - поле значення довідника, з якого потрібно взяти значення.

Якщо тип даних (array) і функція вказана в полі data - то вона буде працювати тільки для зазначеного елемента масиву, наприклад:

"data": [
     {
       "index": 1,
       "ref": "dict.10",
      **"function": "$updateDictLink('Акт.Послуги[1].Код', 'code')$"**
     }
 ]

Пояснення до прикладу: при зміні в першому елементі масиву «index»: 1 поля «id»: «Назва», буде виконана функція $ UpdateDictLink („Акт.Послугі [1] .Код“, „code“) $ «яка запише в поле Акт.Послуги [1].Код значення code із довідника.

Якщо функція вказана в самому вузлі field, то вона буде працювати для кожного елемента масиву, також якщо маршрут вказати наступним чином „Акт.Послуги [@index] .Код“, то він буде посилатися на той же елемент масиву, в якому функція була викликана, наприклад:

 "fields": [
{
  "id": "Назва",
  "title": "Найменування робіт, послуг",
  "optional": false,
  "readonly": false,
  "attribute": true,
  "data": [
    {
      "index": -1,
      "ref": "dict.10"
    }
  ],
 **"function": "$updateDictLink('Акт.Послуги[@index].Код', 'code')$"**,
  "type": {
    "enum": []
  }
}]
  1. arithmeticOperate - виконує математичні операції по вже введених інших полях. Шаблон: $arithmeticOperate(resultPath: string, sourcePath1: string, operationType: string, sourcePath2: string)$, де

  • resultPath - шлях до елементу структурованого документа в який потрібно записати результат;

  • sourcePath1 - шлях до елементу структурованого документа в якому міститься перший аргумент для арифметичної операції;

  • operationType - вид операції, можливі значення «+», «-«, «/», «*»;

  • sourcePath2 - шлях до елементу структурованого документа в якому міститься другий аргумент для арифметичної операції (sourcePath2 може бути відсутнім);

Зверніть увагу!

Важливо! У разі, якщо схема документа створена з використанням типу даних enum, для відображення значень довідника в структурованому документі необхідно вказати «type»: {«enum»: []}}.

Для завантаження (внесення) опису структури документа натисніть на іконку «Структурований»:

../../_images/instr_struct_doc_4.png

У формі, що відкриється, натисніть на кнопку «Додати»:

../../_images/instr_struct_doc_5.png

Наступним кроком введіть опис структури документа у форматі JSON, оберіть кодування xml для документа і натисніть «Зберегти»:

../../_images/instr_struct_doc_6.png

Система повідомить про успішне збереження відповідним повідомленням. Під час збереження опису структури відбувається перевірка валідності внесених даних на відповідність формату JSON та перевірка на дублі.

Перевірка елементів структурованого документа при збереженні:

../../_images/instr_struct_doc_validation2.png

У разі внесення не коректних даних кнопка «Зберегти» не активується. При внесенні дублюючого опису користувачеві буде відображене відповідне повідомлення. Перевірка на дублі виконується у межах компанії.

Збереження опису структури відбувається по версіях створення. Номер версії присвоюється автоматично. Система також фіксує дату та час модифікації кожної версії.

Під версією мається на увазі збереження певної модифікації опису структури. Система передбачає можливість роботи з різними модифікаціями одного типу документа за рахунок активації тієї чи іншої версії структури даних. Не активована схема зберігається у статусі «Чернетка».

../../_images/instr_struct_doc_7.png

Схема у статусі «Чернетка» доступна для редагування. Для переходу у режим редагування натисніть на номер версії иконка-дата або на кнопку «Редагувати». Для активації певної версії структури натисніть «Активувати» у формі редагування опису даних:

../../_images/instr_struct_doc_8.png

Для зручності у формі додання версій реалізований пошук за номером і датою. Для старту пошуку введіть початкові символи у пошукове поле:

../../_images/instr_struct_doc_9.png

Зверніть увагу!

У статусі «Активний» і «Чернетка» може бути лише одна версія структури.

3 Налаштування зв’язку структурованого документа з типом комплекта

Налаштування виконується на загальних підставах. Детальний опис процедури в пункті 8 «Інструкції бізнес-адміністратора».

4 Заповнення структурованого документа

Форма заповнення структури відкривається при доданні документа з ознакою «структурований» до комплекта. Для цього перейдіть в меню «Зовнішні комплекти документів», у вкладці Чернетки виберіть комплект та в ньому перейдіть до вкладки «Документи», і натисніть «Додати»:

../../_images/instr_struct_doc_10.png

Після цього відкриється форма для заповнення структурованого документа, складена відповідно до опису його структури.

Елементи структури документа відображаються послідовно, у порядку, заданому в налаштуваннях структури. При цьому типи елемента (секції) відображаються у вигляді окремих структур, складові компоненти яких розташовуються горизонтально по три в ряд. Назва структури (типу елемента) виділяється жирним шрифтом:

../../_images/instr_struct_doc_11.png

Заповніть поля документа і натисніть кнопку «Зберегти». Для повторного перегляду збереженого структурованого документа в комплекті натисніть на іконку иконка-кубик напроти документа:

../../_images/instr_struct_doc_12.png

5 Блокування типу документа

Для блокування типу документа оберіть потрібний тип з переліку закріплених за компанією, меню «Налаштування компанії» – «Мої компанії» – «Документи», та переведіть перемикач у положення «Заблокувати»:

../../_images/instr_struct_doc_13.png

Тип документа буде переведений у статус «Заблокований». Даний статус блокує використання типу документа у будь-яких операціях з моменту призначення статусу.

Служба Технічної Підтримки