Разработка решений на платформе ELMA365 / Утилита elma365pm для CI/CD в решениях

Утилита elma365pm для CI/CD в решениях

Пользовательские решения можно разрабатывать короткими итерациями, чтобы поддерживать их целостность и версионность. Такой подход реализуется при помощи цикла Разработка > Тестирование > Эксплуатация (Develop > Test > Production). В нём решение проходит три этапа, каждый из которых выполняется в отдельной компании: dev-компания используется для разработки, test-компания — для тестирования, prod-компания — для эксплуатации готового решения.

Этот цикл осуществляется с помощью принципов Непрерывная интеграция (Continuous integration) и Непрерывная сборка и выкладка (Continuous delivery and deploy) или CI/CD.

В ELMA365 для реализации подхода CI/CD предусмотрено несколько инструментов, которые можно использовать независимо друг от друга:

инструмент Непрерывная выкладка (Low-code CI / CD) — обмен компонентами между компаниями из разных окружений выполняется на основе стандартных процессов экспорта и импорта. Все настройки осуществляются в интерфейсе ELMA365. Две компании связываются между собой. Затем создаётся профиль обмена: выбираются компоненты конфигурации, указывается тип операции и т. д. Профиль сохраняется, что позволяет выполнять операцию обмена несколько раз. Присутствует возможность сравнить конфигурации двух компаний и проанализировать результат выполнения операции. Процесс обмена выполняется в фоновом режиме. Подробнее о работе с инструментом читайте в статье «Непрерывная интеграция и выкладка (Low-code CI/CD)»;
утилита elma365pm — вспомогательная независимая утилита командной строки применяется совместно со сторонними сервисами контроля версий и настройки пайплайнов, например, GitLab. Утилита позволяет экспортировать в файл компонент конфигурации компании (раздел, модуль или решение). Затем работа осуществляется в стороннем сервисе, что позволяет использовать операции из High-code разработки. Компонент обновляется до новой версии, упаковывается в файл и импортируется в другую компанию.

В этой статье описывается основной принцип работы с утилитой elma365pm и используемые при этом команды.

Пример организации цикла разработки и выкладки с использованием системы контроля версий GitLab и нескольких окружений dev-test-prod приведён в ELMA365 Community.

Загрузка утилиты

Нажмите на ссылку, чтобы загрузить утилиту elma365pm для различных операционных систем, совместимую с поставками ELMA365 SaaS и последней версией ELMA365 On-Premises:

После загрузки распакуйте .exe-файл.

Доступные команды утилиты

Работа с утилитой elma365pm осуществляется с помощью выполнения команд в командной строке. Команды могут использоваться с доступными флагами. Они прописываются после наименования команды.

После загрузки утилиты вы можете запросить справочную информацию, выполнив команду:

elma365pm --help

Подробная инструкция для каждой команды вызывается следующим образом:

elma365pm <command> --help

В таблице ниже приведены доступные команды и флаги:

Команда: `elma365pm unpack` — распаковать пакет экспорта формата .e365 в файловую систему. В команде задаётся путь до пакета и до папки-распаковки. Использование: `elma365pm unpack --src=String --out=String` Флаги:
`--src=String`	Путь до компонента.
`--out=String`	Директория файловой системы, куда распаковывается пакет.
`--experimental-restruct`	По умолчанию структура каталогов и файлов после распаковки пакета экспорта соответствует внутренней структуре такого пакета. Примените флаг, чтобы реструктурировать пакет для повышения наглядности. Тогда при распаковке сформируется иерархическая структура решения. Например, файл с описанием приложения будет находиться в каталоге раздела, каталог раздела — в каталоге решения, описания переносимых сервисов или методов API в каталоге модуля и т. д. Использовать флаг необходимо с осторожностью.
Команда: `elma365pm pack` — упаковать директорию в пакет .e365. В команде задаётся путь до распакованного пакета и файл, в который необходимо упаковать компоненты. Использование: `elma365pm pack --src=String --out=String` Флаги:
`--src=String`	Директория файловой системы, где хранится распакованный пакет.
`--out=String`	Файл, куда запаковывается пакет.
`--version-up`	Обновление версии пакета.
Команда: `elma365pm export` — экспортировать компонент из ELMA365 в директорию файловой системы. Использование: `elma365pm export <command>`
Подкоманды (доступные компоненты экспорта):
`elma365pm export namespace` — экспорт раздела. Использование: `elma365pm export namespace (ns) --token=STRING --host=STRING --out=STRING`
`elma365pm export solution` — экспорт решения. Использование: `elma365pm export solution (sln) --token=STRING --host=STRING --out=STRING`
`elma365pm export module` — экспорт модуля. Использование: `elma365pm export module (mod) --token=STRING --host=STRING --out=STRING`
`elma365pm export configuration` — экспорт конфигурации. Доступен в ELMA365 On-premises 2022.11 и выше. Использование: `elma365pm export configuration (cfg) --token=STRING --host=STRING --out=STRING`
Флаги, доступные для подкоманд экспорта:
`--token=String`	Токен авторизации, созданный в ELMA365 в разделе Администрирование.
`--host=String`	Адрес хоста ELMA365.
`--out=String`	Директория файловой системы, куда экспортируется пакет.
`--code=String`	Код идентификатора экспортируемого компонента.
`--dts`	Флаг управляет генерацией файлов d.ts, которые активируют подсказки IDE по типам языка TypeScript в скриптах. По умолчанию включен. Важно: для пакетов с множеством компонентов генерация может занять продолжительное время.
`--experimental-restruct`	Реструктурировать пакет для отображения логической иерархии файлов. Применяется с осторожностью.
`--allow-deps=true/false`	Применяется при экспорте решений. Позволяет выгрузить решение с добавленными связями с компонентами другого решения. Подробнее читайте в разделе «Особенности использования утилиты».
Команда: `elma365pm import` — импортировать объекты в ELMA365. Использование: `elma365pm import --token=STRING --host=STRING --src=STRING` Флаги:
`--token=String`	Токен авторизации, созданный в ELMA365 в разделе Администрирование.
`--host=String`	Адрес хоста ELMA365.
`--src=String`	Директория файловой системы для упаковки и импорта.
`--version-up`	Обновление версии пакета.
`--replace-org-struct`	Замена организационной структуры. Используется только при импорте конфигурации компании.
`--force`	Принудительный импорт при наличии конфликтов. Используйте с осторожностью, конфликт может означать, что данные на целевом хосте повреждены.
`--fail-on-conflict`	Вывод в коде выхода ненулевой код ошибки, если при принудительном импорте пакета возникли конфликты. Используется только с флагом `--force`.
Команда: `elma365pm check` — проверить пакет на пригодность к импорту. Использование: `elma365pm check --token=STRING --host=STRING --src=STRING` Флаги:
`--token=String`	Токен авторизации, созданный в ELMA365 в разделе Администрирование.
`--host=String`	Адрес хоста ELMA365.
`--src=String`	Директория файловой системы для упаковки и импорта.
`--version-up`	Обновление версии пакета.
Команда: `elma365pm version` — показать информацию о версии утилиты Использование: `elma365pm version` Флаг: `--json` — вывод информации в JSON
Флаги, доступные для каждой команды:
`--help`	Справочная информация о команде.
`--debug`	Вывод подробных логов выполнения операции.
`--timeout`	Ожидание выполнения операции. По умолчанию задано значение 5 минут. Изменяется в случае обработки объёмного пакета. Например: `elma365pm export solution –timeout=10m`.

Особенности использования утилиты

Обратите внимание на особенности работы с утилитой elma365pm:

С помощью утилиты нельзя экспортировать или импортировать платные системные решения.
Чтобы экспортировать решение с настроенными связями с компонентами другого решения, в команде экспорта применяется параметр --allow-deps со значением true:

elma365pm export solution --token=TOKEN --host=https://dev-elma365.myorg
--out=my_solution --code=my_solution_code --allow-deps=true

Если не использовать параметр --allow-deps или установить для него значение false, решение со связанными компонентами не экспортируется.

Пример использования утилиты

Для примера в качестве инфраструктуры хранения исходного кода и непрерывной сборки используется сервис GitLab. Это наиболее популярный продукт с возможностью разворачивания своего сервера в закрытом контуре.

Рассмотрим основные этапы непрерывной сборки и выкладки на примере решения Служебные записки (Internal_Documents).

Разработчик решения выполняет работу в компании с dev-окружением.
После окончания разработки необходимо выгрузить решение в папку репозитория в файловой системе. Для этого используется команда:

elma365pm export solution --token=TOKEN --host=https://dev15-elma365.myorg
--out=Internal_Documents --code=Internal_Documents

Токен для экспорта и импорта создаётся администратором системы в разделе Администрирование > Токены.

После выполнения этой команды в папке /Internal_Documents будут содержаться файлы решения Служебные записки.

Затем разработчик использует инструменты работы с репозиторием git, согласно внутреннему регламенту.

В нашем примере он фиксирует свои изменения (commit) в отдельную рабочую ветку (branch) и отправляет их в общий репозиторий (push) на сервис GitLab. Далее на сервере в рабочем репозитории создаётся запрос на слияние своей ветки в общую ветку develop.

После проверки и согласования ветки разработчика осуществляется слияния.
В процессе автоматической сборки решения на ветке develop выполняется:

упаковка артефакта решения в файл .e365 для тестирования:

elma365pm pack --src=procurement --out=dist/procurement.e365

загрузка решения в компанию с test-окружением:

elma365pm import --token=TEST-TOKEN --host=https://test-elma365.myorg
--src=Internal_Documents --version-up --force

Чтобы проигнорировать ошибки импорта и выполнить принудительную загрузку в примере используется флаг --force.

После тестирования решения загружается для эксплуатации в компанию с prod-окружением:

elma365pm import --token=PRODUCTION-TOKEN --host=https://elma365.myorg
--src=Internal_Documents --version-up

Подробнее о применении утилиты elma365pm и работе с ней на примере читайте на официальном сайте ELMA365.

Файловая структура решения

При распаковке решения в файлы командой elma365pm export вы увидите в целевой папке структуру решения. Для примера используется готовое бизнес-решение Служебные записки.

Файловая структура

PS InternalDocuments> tree /F

│   package.json
│
├───appViews
│   │   manifest.json
│   │
│   ├───entities
│   │   └───InternalDocuments
│   │           document_type.json
│   │           serviceNote.json
│   │
│   └───resources
│       └───entities
│           └───InternalDocuments
│                   document_type.json.po
│                   serviceNote.json.po
│
├───groups
│   │   manifest.json
│   │
│   └───entities
│       └───InternalDocuments
│               27b37284-0ab0-4d9e-8b39-893938770deb.json
│
├───pages
│   │   manifest.json
│   │
│   ├───entities
│   │   ├───global
│   │   │       InternalDocuments.json
│   │   │
│   │   └───InternalDocuments
│   │           document_type.json
│   │           link_9556a21b-ef8b-4dd6-ad43-2a6d81dd5fda.json
│   │           sep_adab5a75-98bf-46f2-af6e-4a67866260a6.json
│   │           sep_ffe43b88-2ee2-42b0-939a-d4f88a435c98.json
│   │           serviceNote.json
│   │
│   └───resources
│       ├───global
│       │       InternalDocuments.widgets.json
│       │
│       └───InternalDocuments
│               document_type.widgets.json
│               link_9556a21b-ef8b-4dd6-ad43-2a6d81dd5fda.widgets.json
│               sep_adab5a75-98bf-46f2-af6e-4a67866260a6.widgets.json
│               sep_ffe43b88-2ee2-42b0-939a-d4f88a435c98.widgets.json
│               serviceNote.widgets.json
│
├───permissionsSettings
│   │   manifest.json
│   │
│   └───entities
│       ├───global
│       │       InternalDocuments.pagePermissions.json
│       │
│       └───InternalDocuments
│           │   document_type.pagePermissions.json
│           │   document_type.permissionSettings.json
│           │   document_type@__directory.permissionSettings.json
│           │   link_9556a21b-ef8b-4dd6-ad43-2a6d81dd5fda.pagePermissions.json
│           │   sep_adab5a75-98bf-46f2-af6e-4a67866260a6.pagePermissions.json
│           │   sep_ffe43b88-2ee2-42b0-939a-d4f88a435c98.pagePermissions.json
│           │   serviceNote.pagePermissions.json
│           │   serviceNote.permissionSettings.json
│           │   serviceNote@__directory.permissionSettings.json
│           │
│           └───serviceNote
│                   _process_serviceNoteProcessing.permissionSettings.json
│
├───processor
│   │   manifest.json
│   │
│   ├───entities
│   │   └───InternalDocuments.serviceNote
│   │           serviceNoteProcessing.json
│   │           serviceNoteProcessing.ts
│   │
│   └───resources
│       └───InternalDocuments.serviceNote
│               serviceNoteProcessing.po
│               serviceNoteProcessing.runtime
│
├───templates
│   │   manifest.json
│   │
│   ├───entities
│   │   └───InternalDocuments.serviceNote
│   │           accb6290-4c06-44c3-8ce1-fe0721fab4e2
│   │
│   └───resources
│       └───InternalDocuments.serviceNote
│           └───accb6290-4c06-44c3-8ce1-fe0721fab4e2
│                   Служебная записка.docx
│
└───widgets
    │   manifest.json
    │
    ├───entities
    │   ├───InternalDocuments.document_type
    │   │       _create
    │   │       _create.client.ts
    │   │       _create.server.ts
    │   │
    │   └───InternalDocuments.serviceNote
    │           form_20d7fc9f-744b-4c5b-9e63-ad6cb52d8f73
    │           form_20d7fc9f-744b-4c5b-9e63-ad6cb52d8f73.client.ts
    │           form_20d7fc9f-744b-4c5b-9e63-ad6cb52d8f73.server.ts
    │           form_bd63ceb5-914e-406a-90e3-d513b9258ed4
    │           form_bd63ceb5-914e-406a-90e3-d513b9258ed4.client.ts
    │           form_bd63ceb5-914e-406a-90e3-d513b9258ed4.server.ts
    │           form_c4663ece-c7bb-4926-8cc0-1272029cb586
    │           form_c4663ece-c7bb-4926-8cc0-1272029cb586.client.ts
    │           form_c4663ece-c7bb-4926-8cc0-1272029cb586.server.ts
    │           form_dd59c19d-84ff-45ef-b393-db8726a154a8
    │           form_dd59c19d-84ff-45ef-b393-db8726a154a8.client.ts
    │           form_dd59c19d-84ff-45ef-b393-db8726a154a8.server.ts
    │           form_f51fd1ff-a3ce-4e1d-b7ca-5fd5e324e08b
    │           form_f51fd1ff-a3ce-4e1d-b7ca-5fd5e324e08b.client.ts
    │           form_f51fd1ff-a3ce-4e1d-b7ca-5fd5e324e08b.server.ts
    │           _create
    │           _create.client.ts
    │           _create.server.ts
    │           _view
    │           _view.client.ts
    │           _view.server.ts
    │
    └───resources
        ├───InternalDocuments.document_type
        │       _create.po
        │
        └───InternalDocuments.serviceNote
                form_20d7fc9f-744b-4c5b-9e63-ad6cb52d8f73.po
                form_bd63ceb5-914e-406a-90e3-d513b9258ed4.po
                form_c4663ece-c7bb-4926-8cc0-1272029cb586.po
                form_dd59c19d-84ff-45ef-b393-db8726a154a8.po
                form_f51fd1ff-a3ce-4e1d-b7ca-5fd5e324e08b.po
                _create.po
                _view.po

На верхнем уровне находятся папки сервисов, т. к. архитектура системы микросервисная. В каждой папке сервиса обычно есть файл manifest.json и 2 папки entities и resources. В корне также лежит файл package.json, в котором описаны основные данные выгруженного решения или раздела.

В основном файлы в структуре делятся на 3 типа:

Файлы описаний конфигурации — это файлы формата .json или файлы без расширения, также являющиеся JSON-файлами. В этих файлах можно найти описание полей и настройки приложения, описание процесса, виджеты и модули.
Файлы скриптов — это файлы формата .ts, в которых хранятся тексты скриптов процессов, виджетов, модулей.

Файлы скриптов распаковываются для удобного просмотра и совместного ревью кода. Содержимое этих файлов не упаковывается в пакет при импорте.

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

Прочие файлы ресурсов или локализации. Такие файлы обычно находятся в папке resources. Локализация пакетов решений в будущем будет переработана, поэтому сейчас файлы локализации используются ровно один раз при первом импорте пакета. Вы можете вносить изменения прямо в эти файлы, и они будут упакованы утилитой.

create-service.html npm-package.html

Была ли статья полезной?