Использование программного компонента#

Взаимодействие с серверной частью#

Следующие компоненты OneWork предоставляют REST API, их OpenAPI спецификацию можно просмотреть с помощью Swagger в разделе «Справочники API»:

ssd-core-data
ssd-role-manager
ssd-ui-admin
ssd-transaction-manager

Создание набора инструментов#

Для создания нового набора зайдите под учетной записью пользователя с правами Администратор OneWork в Swagger сервиса ssd-core-data (https://works.domain.ru/ssd/ssd-core-data/swagger-ui/index.html). Для создания набора предназначен endpoint POST /v2/bundle. В теле запроса отправляется объект следующего вида:

{
    "bundle_key": "string",  // ключ набора (латинские символы и цифры)
    "bundle_name": "string", // человекочитаемое имя набора
    "description": "string", // описание набора
    "is-active": true,       // флаг активности
    "tool_keys": [           // перечень инструментов, которые должны войти в состав набора
    "string"
    ]
}

Список доступных инструментов можно получить с помощью endpoint /v2/tools.

Пример тела запроса для создания набора, содержащего инструменты TrackWork, Artifactory CI/CD:

{
    "bundle_key": "newbundle",  
    "bundle_name": "Новый набор инструментов", 
    "description": "Демонстрация создания", 
    "is-active": true,       
    "tool_keys": [    
      "track", "nci", "ncd"
    ]
}

Добавление инструмента в проект#

Для создания нового набора зайдите под учетной записью пользователя с правами Администратор OneWork в Swagger сервиса ssd-core-data (https://works.domain.ru/ssd/ssd-core-data/swagger-ui/index.html). Для создания набора предназначен endpoint POST v3/project_tools. В теле запроса отправляется объект следующего вида:

{
  "projectId": "string",  // ключ проекта (латинские символы и цифры)
  "tools": [           // перечень инструментов, которые должны войти в состав набора
    {
      "toolKey": "string", // ключ инструмента
      "toolParameters": [
        {
          "dataType": "integer",
          "showUi": "boolean",
          "pname": "string",
          "pvalue": "string"
        }
      ]
    }
  ]
}

Пример тела запроса для для добавления инструмента Artifactory CI/CD в проект:

{
  "projectId": "/orgTest/projectTest",
  "tools": [
    {
      "toolKey": "nci",
      "toolParameters": [
        {
          "dataType": 3,
          "showUi": true,
          "pname": "groupId",
          "pvalue": "ru.v3org2.test25"
        }
      ]
    },
    {
      "toolKey": "ncd",
      "toolParameters": [
        {
          "dataType": 3,
          "showUi": true,
          "pname": "groupId",
          "pvalue": "ru.v3org2.test25"
        }
      ]
    }
  ]
}

Редактирование набора инструментов#

Для редактирования набора предназначен endpoint PUT /v2/bundle. В теле запроса отправляет объект, аналогичный созданию, для обновления доступны поля bundle_name, description, is-active

Текущее состояние набора можно получить с помощью GET /v2/bundles.

Редактирование набора инструментов, принадлежащих бандлу в данный момент недоступно. Рекомендовано создание нового бандла в случае, если состав бандла по умолчанию не соответствует состоянию развернутых инструментов.

Также можно отредактировать состав набора напрямую в БД (изменения вносить в таблицу v2_bundle2tool), но такие изменения необходимо осуществить до начала пользования платформой. Расширение списка инструментов набора, который уже задействован в существующих проектах, может привести к некорректному отображению их статуса.

Взаимодействие с kafka#

Обмен сообщениями осуществляется через топик шины на базе Apache Kafka. Формат сообщений - JSON. Для обмена предлагается использовать следующие топик:

SSD_INPUT: запросы создание организации, проектных областей и привязки пользователя к проекту в ролью.
SSD_OUTPUT: ответы на запросы создания организации, проектных областей и привязки пользователя к проекту.

Запросы на изменение сущностей и ответы о выполнении операции имеют единую структуру, специфичная часть запроса сериализуется в виде строки и передается в атрибуте content.

Управление платформой выполняет однократную отправку запроса на изменение, не повторяя запрос в случае ошибки. При необходимости повторное выполнение запрашиваемой операции предусматривается на стороне OneWork.

Ответ о выполнении операции отправляется со стороны OneWork:

Сообщение отправляется в момент создания организации/проекта со статусом «Выполняется».
После успешного завершения отправляется ответ со статусом «Готово».
В случае ошибки, отправляется ответ со статусом «Ошибка» и расшифровка.

Формат базового запроса

Запрос на создание/изменение/удаление организаций и проектных областей, привязку/отвязку пользователя к проектной области представляет собой JSON, атрибуты описаны в следующей таблице.

Название атрибута	Тип атрибута	Размерность	Обязательность	Описание
requestId	string	36	+	Уникальный идентификатор запроса. Используется для трекинга запросов на изменение и связи его с ответами на запрос. В ответах должен передаваться тот же идентификатор. Представляет собой UUID.
timestamp	string	25	+	Дата и время отправки запроса на изменение. Представляет собой дату и время в формате ISO-8601. Например, 2023-06-20T13:08:39+03:00
targetSystem	string	3	+	Код системы, в которую отправляется запрос. Всегда имеет значение «SSD» (Обратите внимание, SSD это код системы OneWork)
entityType	string	12	+	Определяет тип объекта, для которого запрашивается операция: ORGANIZATION - организация, PROJECT - проект, USER - пользователь, ROLE - роль
entityOperation	string	11	+	Определяет операцию, которую нужно выполнить с объектом: для организации, проекта, роли: 1) CREATE - создание 2) UPDATE - изменение 3) DELETE - удаление для пользователя: 4) BIND - привязать к проектной области 5) UNBIND - отвязать от проектной области 6) CHANGE_ROLE - изменить роль пользователя в проектной области
content	string	1000	+	Часть запроса, специфичная для конкретной сущности в виде JSON, переданного как строка.

Ниже приведена JSON-схема базового запроса на выполнение операции с сущностью.

{
    "$schema": "https://JSON-schema.org/draft/2019-09/schema",
    "type": "object",
    "description": "JSON-схема единого формата запроса интеграции",
    "additionalProperties": false,
    "required": [
        "requestId",
        "timestamp",
        "tenant",
        "targetSystem",
        "entityType",
        "content"
    ],
    "properties": {
        "requestId": {
            "type": "string",
            "format": "uuid",
            "description": "Уникальный идентификатор запроса"
        },
        "timestamp": {
            "type": "string",
            "format": "date-time",
            "description": "Дата и время отправки запроса на выполнение операции"
        },
        "targetSystem": {
            "$ref": "#/$defs/targetSystemDefinition",
            "description": "Система, в которую отправляется сообщение (SSD)"
        },
        "entityType": {
            "$ref": "#/$defs/entityTypeDefinition",
            "description": "Код объекта, которым управляем этим сообщением: ORGANIZATION - организация, PROJECT - проект, USER - пользователь"
        },
        "entityOperation": {
            "$ref": "#/$defs/entityOperationDefinition",
            "description": "Операция, которую требуется выполнить над объектом: CREATE, UPDATE, DELETE: создание, обновление, удаление (применимы к организации и проекту), BIND: привязать пользователя к проектной области, UNBIND: отвязать пользователя от проектной области, CHANGE_ROLE: изменить роль пользователя"
        },
        "content": {
            "type": "string",
            "maxLength": 2000,
            "description": "Часть запроса, специфичная для управляемой сущности в виде JSON, сериализованного в строку"
        }
    },
    "$defs": {
        "targetSystemDefinition": {
            "enum": [
                "SSD"
            ]
        },
        "entityTypeDefinition": {
            "enum": [
                "ORGANIZATION",
                "PROJECT",
                "USER",
                "ROLE",
                "TOOL"
            ]
        },
        "entityOperationDefinition": {
            "enum": [
                "CREATE",
                "UPDATE",
                "DELETE",
                "BIND",
                "UNBIND",
                "CHANGE_ROLE"
            ]
        }
    }
}

Ниже приведен пример такого запроса.

{
  "requestId": "4005b83f-acbc-4f49-9b47-92bd50796945",
  "timestamp": "2024-06-03T13:59:17.717780972Z",
  "targetSystem": "SSD",
  "content": "{\"project-key\":\"cash\",\"project-name\":\"cash\",\"description\":\"some cash description\",\"owner-login\":\"login\",\"parent-id\":\"/org\"}",
  "entityType": "PROJECT",
  "entityOperation": "CREATE"
}

Создание/изменение/удаление организации в Productivity (ex. OneWork)#

Для создании организации отправляется сообщение с необходимой информацией для создания организации. На стороне OneWork сообщение обрабатывается и как результат обработки отправляется сообщение об успешном или неуспешном создании/изменении организации.

В запросах изменения организации возможны изменения только названия организации и подробное описание. Ключ организации не может быть изменен.

Ниже приведена JSON-схема запроса на выполнение операции с организацией.

{
  "$schema": "http://JSON-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "requestId": {
      "type": "string"
    },
    "timestamp": {
      "type": "string"
    },
    "targetSystem": {
      "type": "string"
    },
    "content": {
      "type": "string"
    },
    "entityType": {
      "type": "string"
    },
    "entityOperation": {
      "type": "string"
    }
  },
  "required": [
    "requestId",
    "timestamp",
    "targetSystem",
    "content",
    "entityType",
    "entityOperation"
  ]
}

Ниже приведен пример запроса.

{
  "requestId": "76c536e5-644f-46bf-88c5-c27718bcfac8",
  "timestamp": "2024-06-03T13:46:53.203887392Z",
  "targetSystem": "SSD",
  "content": "{\"project-key\":\"example\",\"project-name\":\"example\",\"description\":\"some description\",\"owner-login\":\"login\"}",
  "entityType": "ORGANIZATION",
  "entityOperation": "CREATE"
}

Content
{"project-key":"example","project-name":"example","description":"some description","owner-login":"login"}

Ниже приведена JSON-схема ответа на выполнение операции с организацией.

{
  "$schema": "http://JSON-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "requestId": {
      "type": "string"
    },
    "timestamp": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "content": {
      "type": "string"
    }
  },
  "required": [
    "requestId",
    "timestamp",
    "status",
    "content"
  ]
}

Ниже приведен пример запроса.

{
  "requestId": "b030b8f1-ce65-4166-b208-157b382cbcaa",
  "timestamp": "2024-06-03T14:11:24.069478242Z",
  "status": "DONE",
  "content": "{\"url\":\"#/example/\",\"project-id\":\"/example\"}"
}

Content 
{"url":"#/example/","project-id":"/example"}

Создание/изменение/удаление проектной области в OneWork#

В topic отправляется сообщение с необходимой информацией для создания проектной области. На стороне OneWork сообщение обрабатывается и как результат обработки отправляется сообщение о начале работ и об успешном или неуспешном создании/изменении проектной области.

В запросах изменения проектной области возможны изменения только названия проекта, подробное описание, массив артефактов. Остальные атрибуты не могут быть изменены.

Ниже приведена JSON-схема запроса на создание проектной области в OneWork.

{
  "$schema": "http://JSON-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "requestId": {
      "type": "string"
    },
    "timestamp": {
      "type": "string"
    },
    "targetSystem": {
      "type": "string"
    },
    "content": {
      "type": "string"
    },
    "entityType": {
      "type": "string"
    },
    "entityOperation": {
      "type": "string"
    }
  },
  "required": [
    "requestId",
    "timestamp",
    "targetSystem",
    "content",
    "entityType",
    "entityOperation"
  ]
}

Ниже приведен пример запроса.

{
  "requestId": "4005b83f-acbc-4f49-9b47-92bd50796945",
  "timestamp": "2024-06-03T13:59:17.717780972Z",
  "targetSystem": "SSD",
  "content": "{\"project-key\":\"cash\",\"project-name\":\"examplecash\",\"description\":\"some cash description\",\"owner-login\":\"example\",\"parent-id\":\"/example\"}",
  "entityType": "PROJECT",
  "entityOperation": "CREATE"
}

Content
{
  "project-key": "cash",
  "project-name": "example cash",
  "description": "some cash description",
  "owner-login": "ivanoff",
  "parent-id": "/example"
}

Ниже приведена JSON-схема ответа на выполнение операции с проектной областью.

{
  "$schema": "http://JSON-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "requestId": {
      "type": "string"
    },
    "timestamp": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "content": {
      "type": "string"
    }
  },
  "required": [
    "requestId",
    "timestamp",
    "status",
    "content"
  ]
}

Ниже приведен пример запроса.

{
  "url": "#/example/cash",
  "project-id": "/example/cash"
}

Сообщение для создания проектной области должно формироваться после создания организации, если организация не была создана в OneWork и пришло сообщение о создании проектной области, то вернется ошибка «Не найдена организация»

Добавление/удаление инструмента(ов) в существующую проектную область в OneWork#

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

Ниже приведена JSON-схема запроса на создание проектной области в OneWork.

{
  "$schema": "http://JSON-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "requestId": {
      "type": "string"
    },
    "timestamp": {
      "type": "string"
    },
    "targetSystem": {
      "type": "string"
    },
    "content": {
      "type": "string"
    },
    "entityType": {
      "type": "string"
    },
    "entityOperation": {
      "type": "string"
    }
  },
  "required": [
    "requestId",
    "timestamp",
    "targetSystem",
    "content",
    "entityType",
    "entityOperation"
  ]
}

Content:
{
  "$schema": "http://JSON-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "project-id": {
      "type": "string"
    },
    "tools": {
      "type": "array",
      "items": [
        {
          "type": "object",
          "properties": {
            "tool-id": {
              "type": "string"
            },
            "parameters": {
              "type": "array",
              "items": [
                {
                  "type": "object",
                  "properties": {
                    "tool-parameter-name": {
                      "type": "string"
                    },
                    "tool-parameter-value": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "tool-parameter-name",
                    "tool-parameter-value"
                  ]
                },
                {
                  "type": "object",
                  "properties": {
                    "tool-parameter-name": {
                      "type": "string"
                    },
                    "tool-parameter-value": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "tool-parameter-name",
                    "tool-parameter-value"
                  ]
                }
              ]
            }
          },
          "required": [
            "tool-id",
            "parameters"
          ]
        }
      ]
    }
  },
  "required": [
    "project-id",
    "tools"
  ]
}

Ниже приведен пример запроса добавления инструмента в существующую проектную область в OneWork.

{
  "requestId": "b3b1cde1-95c4-45aa-838c-dc4113121b2c",
  "timestamp": "2024-06-03T13:39:37.540433917Z",
  "targetSystem": "SSD",
  "content": "{\"project-id\":\"/example\",\"tools\":[{\"tool-id\":\"jira\",\"parameters\":[{\"tool-parameter-name\":\"p2\",\"tool-parameter-value\":\"v2\"},{\"tool-parameter-name\":\"p1\",\"tool-parameter-value\":\"v1\"}]}]}",
  "entityType": "TOOL",
  "entityOperation": "CREATE"
}

Ниже приведен пример запроса удаления инструмента в существующей проектной области OneWork.

{
  "requestId": "770a292b-ed16-4de1-a395-d55245f7719e",
  "timestamp": "2024-06-03T13:39:37.544737117Z",
  "targetSystem": "SSD",
  "content": "{\"project-id\":\"/example\",\"tools\":[{\"tool-id\":\"jira\",\"parameters\":[]}]}",
  "entityType": "TOOL",
  "entityOperation": "DELETE"
}

В ответ на запрос создания проектной области возвращается JSON-объект в атрибуте content базового ответа, содержащий ссылку на проектную область в OneWork.

В случае запросов на изменение и удаление, атрибут content не возвращается в базовом ответе.

Ниже приведена JSON-схема ответа на выполнение операции с проектной областью.

{
  "$schema": "http://JSON-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "requestId": {
      "type": "string"
    },
    "timestamp": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "content": {
      "type": "string"
    }
  },
  "required": [
    "requestId",
    "timestamp",
    "status",
    "content"
  ]
}

Ниже приведен пример запроса.

{
  "url": "#/example/",
  "project-id": "/example"
}

Сообщение для добавления инструмента в проектную область должно формироваться после создания проектной области, если проектная область не была создана в OneWork и пришло сообщение о добавлении инструмента, то вернется ошибка «Не найдена проектная область».

Добавление/удаление пользователя#

В topic отправляется сообщение с необходимой информацией для добавление пользователя. На стороне OneWork сообщение обрабатывается и как результат обработки отправляется сообщение о начале работ и об успешном или неуспешном создании/изменении пользователя.

В запросах изменения пользователя возможны изменения только роли пользователя. Остальные атрибуты не могут быть изменены.

Ниже приведена JSON-схема запроса на добавление пользователя в OneWork.

{
  "$schema": "http://JSON-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "requestId": {
      "type": "string"
    },
    "timestamp": {
      "type": "string"
    },
    "targetSystem": {
      "type": "string"
    },
    "entityType": {
      "type": "string"
    },
    "entityOperation": {
      "type": "string"
    },
    "content": {
      "type": "string"
    }
  },
  "required": [
    "requestId",
    "timestamp",
    "targetSystem",
    "entityType",
    "entityOperation",
    "content"
  ]
}

Ниже приведен пример запроса.

{
    "requestId": "d4d21fdf-52e5-428e-8d5e-ec3b955faf1f",
    "timestamp": "2024-08-19T15:38:28.356920+03:00",
    "targetSystem": "SSD",
    "entityType": "USER",
    "entityOperation": "BIND",
    "content": "{\"project-id\": \"/okaf35/pkaf785\", \"e-mail\": \"one_work_user1@test.com\", \"role\": \"tester\", \"user-name\": \"one_work_user1\"}"
}

В случае запросов на изменение и удаление, атрибут content не возвращается в базовом ответе.

Ниже приведена JSON-схема ответа на выполнение операции с пользователем.

{
  "$schema": "http://JSON-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "requestId": {
      "type": "string"
    },
    "timestamp": {
      "type": "string"
    },
    "targetSystem": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "statusMessage": {
      "type": "string"
    },
    "content": {
      "type": "string"
    }
  },
  "required": [
    "requestId",
    "timestamp",
    "targetSystem",
    "status",
    "statusMessage",
    "content"
  ]
}

Ниже приведен пример ответа.

{
  "requestId": "d4d21fdf-52e5-428e-8d5e-ec3b955faf1f",
  "timestamp": "2024-08-19T12:38:30.310046321Z",
  "targetSystem": "SberworksApi",
  "status": "DONE",
  "statusMessage": "OK",
  "content": "{\"url\":\"/#/organization/okaf35/project/pkaf785\",\"project-id\":\"/okaf35/pkaf785\"}"
}

Реализация единого UI инструментов Works#

OneWork предоставляет компонент бокового меню, который позволяет создавать единый интерфейс навигации для инструментов Works.

Установка компонента#

Получите код веб-компонента одним из следующих способов:
1. Как npm-пакет:
```
npm install @ssd/side-menu --registry=${REGISTRY_URL}
```
2. Как bundle файл в дистрибутиве: pl/sidemenu.bundle.js.
Добавьте в разметку тег для подключения кода веб-компонента:
```
<script src="sidemenu.bundle.js"></script>
```

Встройте веб-компонент в разметку тегом:

<div style="position: fixed; top: 0; left: 0; bottom: 0; width: 300px; z-index: 1;">
    <side-menu></side-menu>
</div>

Передайте следующие атрибуты при помощи метода setAttribute или укажите их непосредственно в теге:

mode — режим работы: works или separate. В режиме works показывается базовая структура меню, и с ней объединяются пункты меню из атрибута children-items. В режиме separate показываются только пункты из атрибута children-items.

children-items — массив пунктов меню. Элемент массива состоит из полей:

Элемент	Тип	Описание
`key`	string	уникальный в рамках меню ключ
`label`	string	название пункта меню, которое будет видеть пользователь
`icon`	string	название иконки (необязательный, иконки используются из библиотеки `antd`)
`link`	string	ссылка на ресурс (необязательный)
`children`	array	массив внутренних пунктов меню, элемент массива имеет структуру, аналогичную `children-items`

open-keys — массив ключей (string), которые должны быть открыты.
selected-keys — массив ключей (string), которые должны быть выделены.
ssd-ui-admin-url — базовый URL для сервиса ssd-ui-admin (string).
tool-key - код инструмента (string). Значения приведены в разделе Базовая структура меню в режиме works.
project-uri — часть URL инструмента, содержащая код организации и код проектной области, однозначно определяющая контекст проекта совместно с кодом инструмента tool-key. Например, для Gitlab:
- если url = http://srv.ws.test-env:3000/RMSHK/RMSHK_GOSIS/erp-marketplace, то project-uri = RMSHK/RMSHK_GOSIS;
- если url = http://srv.ws.test-env:3000/groups/RMSHK/RMSHK_GOSIS, то project-uri = RMSHK/RMSHK_GOSIS.

В режиме works необходимо задать значения следующих атрибутов:

children-items
open-keys
selected-keys
ssd-ui-admin-url
tool-key
project-uri

В режиме works при смене контекста проекта внутри инструмента новое значение должно быть передано в атрибут project-uri веб-компонента.

В режиме separate необходимо задать значения следующих атрибутов:

children-items
open-keys
selected-keys

Если в инструменте произошел переход вне контекста проекта (актуально для Gitlab), то единое меню должно либо быть скрыто, либо переведено в режим separate. В последнем случае инструмент полностью отвечает за содержимое меню.

Задайте единые размеры и цвета для всех инструментов:
- ширина: 300 px, прокрутка появляется внутри этой ширины без отступа от правого края (стилизованная под MacOS);
- фон: Белый #FFFFFF
- фон под открытыми пунктами второго и следующих уровней: #FAFAFA

Базовая структура меню в режиме works#

Свойство link элементов базового меню формируется динамически на основе контекста проекта и данных из бекэнда OneWork.

Некоторые пункты базового меню могут быть недоступны в зависимости от контекста проекта.

Описание работы меню в режиме works#

В режиме works выполняется объединение по ключу key корневых элементов атрибута children-items с базовой структурой меню. Если элемент с таким ключом найден в базовой структуре меню (на любом уровне), то его свойства label, icon, link и children перезаписываются (если заданы в корневом элементе).

Например, следующее значение атрибута children-items добавит дочерние пункты меню к базовому пункту Конвейер → Сборка:

[
  {
    key: 'continuousIntegration__Сборка',
    label: 'Сборка',
    children: [
      {
        key: 'continuousIntegration__Сборка__ItemOne',
        label: 'Дочерний пункт 1',
        link: '/x/y/z/1'
      },
      {
        key: 'continuousIntegration__Сборка__ItemTwo',
        label: 'Дочерний пункт 2',
        children: [
          {
            key: 'continuousIntegration__Сборка__ItemTwo__1',
            label: 'Дочерний пункт 2.1',
            link: '/x/y/z/2/1'
          },-
          {
            key: 'continuousIntegration__Сборка__ItemTwo__2',
            label: 'Дочерний пункт 2.2',
            link: '/x/y/z/2/2'
          }
        ]
      }
    ]
  }
]

Использование программного компонента#

Взаимодействие с серверной частью#

Создание набора инструментов#

Добавление инструмента в проект#

Редактирование набора инструментов#

Взаимодействие с kafka#

Создание/изменение/удаление организации в Productivity (ex. OneWork)#

Создание/изменение/удаление проектной области в OneWork#

Добавление/удаление инструмента(ов) в существующую проектную область в OneWork#

Добавление/удаление пользователя#

Реализация единого UI инструментов Works#

Установка компонента#

Базовая структура меню в режиме works#

Описание работы меню в режиме works#

Диаграмма последовательности формирования содержимого единого меню#