business_entity_management

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

Цель примера: Показать возможности по управлению бизнес-сущностями в инструменте управления архитектурой DocHub.

Помимо заявленной цели пример содержит еще несколько интересных реализаций. Например, отчет показывающий список систем/сервисов с реализацией передачи параметра в другой отчет для установки значения фильтра.

Суть примера

Стояла реальная бизнес-задача показать в каких системах используются те или иные бизнес-сущности.

Вторая задача определилась по ходу реализации. Оказалось, что в компании нет процесса управления бизнес-сущностями на логическом уровне, что приводит к тому, что в разных системах/сервисах одну и ту же бизнес-сущность логически и физически реализуют по-разному. Начиная с того, что реквизиты могут называются по разному и иметь разный физический смысл и заканчивая тем, что часть сущностей с одинаковым названием физически означают разные вещи. Все это вызывает большие проблемы в первую очередь с интеграцией между сервисами.

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

Логическое описание реализации и файловая структура примера

Для реализации был выбран вариант создания нового entity, который называется "business_entities". Физически "business_entities" было реализовано через 2 файла:

• business_entities/business_entities_model.yaml - в этом файле была описана сама модель, реализован вывод в меню и несколько вариантов визуализации в виде отчетов. Все запросы переиспользуемые, так как они были добавлены в datasets/datasets.yaml

entities: # Сущности расширенной метамодели
  # Бизнес-сущности
  business_entities:               # Секция, где будет описываться объекты сущности "взаимодействие". Обязательно.enti
    title: Бизнес-сущности   # Название сущности. Обязательно.
    description: >          # Описание сущности текст или ссылка на документ. Необязательно.
      Ключевые бизнес-сущности ГК Болото
    menu: >                 # Генератор раcположения в меню. Запрос или явное описание объета. Необязательно.
      (
        Запрос
      )
    presentations:
      business_entities_table_list:
        type: table
        headers:
          Описание полей таблицы
        source: swamp.dataset.business_entities_list

      # Выводим список бизнес-сущностей, полученных в запросе выше business_entities_list
      business_entities_list:
        type: markdown
        template: business_entities_list.md

      # Выводим карточку выбранной бизнес-сущности
      business_entity_card:
        type: markdown
        template: business_entity_card.md
        source: >            
          (
            $entities := [$.business_entities.$spread().$merge([$.*, {"id": $keys($)}])];
            $entities [id=$params.id];
          )

      # Получаем список бизнес-сущностей, используемых в системах, все это выводим в таблицу
      business_entities_table_in_systems:
        type: table
        headers:
          Описание полей таблицы
        source: swamp.dataset.business_entities_in_systems

      # Выводим писок бизнес-сущностей, используемых в системах полученных в запросе выше business_entities.in_systems
      business_entities_in_systems:
        type: markdown
        template: business_entities_in_systems.md

      # Наследуемся от таблицы business_entities.in_systems и делаем фильтр по конкретной системе
      business_entities_table_in_systems.filtered:     # Дочерняя таблица
        type: table
        headers: 
          Описание полей таблицы
        origin: swamp.dataset.business_entities_in_systems       # Базовый источник данных
        source: >
          (
              $[system_id=$params.system_id]
          )

• business_entities/business_entities.yaml - в этом файле хранятся значения "business_entities"

business_entities:
  bank:
    title: Банки
    description: pass    
    parameters:
      - name: bank_name
        description: Наименование банка
      - name: bik
        description: БИК банка

  chekingaccount:
    title: Расчетные счета
    description: pass

  contractor:
    title: Контрагенты
    description: pass

  contractoraccount:
    title: Счета контрагентов
    description: pass

Для реализации привязки бизнес-сущностей в системах/сервисах необходимо добавлять массив используемых бизнес-сущностей в раздел "business_entities":

# Описываем L1 Context в нотации C4 Model
components:
  swamp.frog.spoll:
    title: S.POLL    # Название компоненты
    entity: system   # Сущность компонента из PlantUML (https://plantuml.com/ru/deployment-diagram)    
    short_description: Сервис формирования опросов
    description: Сервис формирования опросов
    business_owners:
      - Пиявки
    application_owner: Лунтик    
    critical_level: business_operational #administrative/business_operational/business_critical/mission_critical
    system_category: business_app #channel_app/business_app/ext_business_app/it_app/ext_it_app        
    aspects:                # Аспекты, которе реализует компонент
      - hr
    business_entities:      
      - bank
      - currency
      - region
      - chekingaccount
      - contractoraccount
      - contract
    links:
    # Интеграции между системами разных БЮ      
    - id: swamp.frog.1cbit_finance
      direction: <--
    - id: swamp.crocodile.crm
      direction: <--
    - id: swamp.crocodile.spact
      direction: <--

Также было разработано несколько отчетов. Практически все отчеты реализуются через markdown путём встраивания различных объектов DocHub внутрь, например, таблиц.

• business_entities/business_entity_card.md — это карточка бизнес-сущности. Если добавить реквизиты к сущности, то в карточке они тоже будут выводиться. Для примера можно сформировать карточу бизнес-сущности "bank".
• business_entities/business_entities_list.md — это список всех бизнес-сущностей с возможностью перехода в карточку конкретной бизнес-сущности.
• business_entities/business_entities_in_systems.md — это список показывающий список бизнес-сущностей используемых в каждой системе. В этом отчете реализован пример установки фильтра по конкретной системе. Также реализована возможность сортировки практически по всем полям.
• systems_table.md — этот отчет выводит список систем, но также к нему была добавлена ссылка для возможности выводить отфильтрованный по системе список бизнес-сущностей.

Концептуальная схема примера ниже:

Использование

В меню плагина DocHub выберите пункт Документы/Моё болото. В меню вы увидите ссылки на 3 отчета.

1. Выберите пункт "1. Бизнес-сущности":

Нажмите на ссылку "Банки" и перейдите в карточку бизнес-сущности:

2. Выберите пункт "2. Список бизнес-сущностей в системах":

Так как в системе CRM указан ошибочный идентификатор, то в колонке "Бизнес-сущность" для этого идентификатора указана ошибка "Ошибка в идентификаторе бизнес-сущности".

При нажатии на заголовок таблицы "Бизнес-сущность" вы можете отсортировать список по имени бизнес-сущности и посмотреть в каких системах используется та или иная бизнес-сущность.

Нажав ссылку "Отбор по системе" можно отфильтровать список по конкретной системе:

3. Выберите пункт "3. Список систем":

В колонке "Бизнес-сущности" нажмите "Ссылка". В результате выведется список бизнес-сущностей отфильтрованный по выбранной системе, аналогично пункту 2 этого раздела.

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

• Разберитесь со структурой примера, особе внимание обратите на алгоритмы формирования запросов. Если что-то не понятно, то можно почитать документацию по JSONata;
• Попробуйте реализовать какой-нибудь свой вариант отчета переиспользовав один из запросов описанных datasets/datasets.yaml.