sequences_entity_example

Пример сущности для бизнес-процессов

Цель примера: Показать возможности связки Dochub+plantuml для генерации диаграмм последовательности (например, описание бизнес-процессов) в контексте имеющегося описания архитектуры предприятия.

Пример является доработанной версией сущности interactions из официальной документации, опубликованной на одном из воркшопов по Dochub. Добавлена автоматическая линковка компонентов в качестве участников, а также поддержка ссылок в шагах. Это могут быть ссылки на другие диаграммы, swagger-контракты и тд.

Суть примера

Показать, как с помощью сущностей можно "затащить" в dochub бизнес-документацию и связать ее с архитектурой компании. Как простой пример последовательности была выбрана сказка "Колобок".

В результате аналитики и технические писатели получают возможность описать с помощью текста (а значит - и положить в git) бизнес-процессы:

sequences:
  story.pigs:
    title: Сказка "колобок"
    location: Документы/Колобок/Диаграмма
    icon: swap_horiz
    groups:
      - title: Рождение колобка
        triggers:
          - Жили-были дед и баба
        steps:
          - from: grandpa
            to: grandma
            value: Испеки, старуха, колобок!
          - from: grandma
            to: grandma
            value: Поскрести по сусекам
          - from: grandma
            to: kolobok
            value: Испекла баба колобок
            contract: kolobok.receipt
        results:
          - Колобок полежал—полежал, да вдруг и покатился
...

Dochub сам превратит найденные упоминания компонентов из полей from/to в ссылки на их профили и подтянет названия, а поле contract позволит обеспечить перелинковку с другими документами, в том числе внешними.

Файловая структура примера

• components - данные архитектуры для рендеринга
  • heroes.yaml - компоненты-участники сказки
  • root.yaml - корневой манифест данных архитектуры
• docs - документы в формате markdown для демонстрации возможностей линковки через contract
• entities - метамодель;
  • templates - шаблоны, используемые для рендеринга диаграмм
    • tree.puml - Plantuml-шаблон для вывода всех диаграмм в виде дерева
    • blank.puml - Plantuml-шаблон для просмотра конкретной диаграммы
  • manifest.yaml - манифест пользовательских сущностей (там определена сущность sequences)
  • sequences.yaml - пример сущности
  • root.yaml - корневой манифест метамодели
• dochub.yaml - корневой манифест примера

Валидация

Dochub имеет встроенные механизмы контроля корректности заполнения описания. Чтобы его активировать, для создаваемых сущностей мы описываем правила валидации:

"Из коробки" это позволяет проверять соответствие сущностей при работе в IDE через плагин Dochub. Чтобы валидация выполнялась также в приложении Dochub, а ошибки выводились в блоке "Проблемы", необходимо добавить вызов валидатора:

rules:
  validators:
    sequences:
      title: Валидатор последовательностей
      source: >
        (
          $validator := $jsonschema($.entities.sequences.schema.patternProperties.*); /* Передаем схему в части отдельного объекта, а не всех sequences */
          ([([
            $.sequences.$spread().( /* Сканируем все последовательности */
              $ID := $keys()[0];
              {
                "id": $ID,											/* Запоминаем идентификатор компонента */
                "isvalid": $validator($.*)							/* Валидируем компонент по схеме */									
              }
            )        
          ][isvalid != true]).isvalid.{  /* Генерируем отклонения по выявленным нарушениям */
            "uid": $.params.*[0] & "-sequence-" & %.id,				/* Уникальный идентификатор выявленной ошибки */
            "location": "/entities/sequences/blank?id=" & %.id,		/* Ссылка на расположение объекта ошибки */
            "correction": "Исправьте ошибку",						          
            "description": $.message
          }])
        
        )

Задания для практики

• Реализуйте документ со списком диаграмм и задействованных в них компонентов
• Добавьте поддержку активации/деактивации участников через дополнительный атрибут сущности