Пользовательские решения можно разрабатывать короткими итерациями, чтобы поддерживать их целостность и версионность. Такой подход реализуется при помощи цикла Разработка > Тестирование > Эксплуатация (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 |
Пример команды |
elma365pm unpack --src=String --out=String |
Доступные флаги |
|
--src=String |
Вместо String укажите путь до компонента. |
--out=String |
Вместо String укажите папку файловой системы, куда распаковывать пакет. |
--experimental-restruct |
Используйте флаг с осторожностью. По умолчанию структура каталогов и файлов после распаковки пакета экспорта соответствует внутренней структуре такого пакета. Тогда при распаковке сформируется иерархическая структура решения. Например, файл с описанием приложения будет находиться в каталоге раздела, каталог раздела — в каталоге решения, описания переносимых сервисов или методов API в каталоге модуля и т. д. |
Упаковать папку в пакет .e365
Команда |
elma365pm pack |
Пример команды |
elma365pm pack --src=String --out=String |
Доступные флаги |
|
--src=String |
Вместо String укажите папку файловой системы, где хранится распакованный пакет. |
--out=String |
Вместо String укажите файл, куда запаковывается пакет. |
--version-up |
Обновление версии пакета. |
Экспортировать компонент из ELMA365
Вы можете экспортировать раздел, решение, модуль или конфигурацию. Для каждого из этих действий используется своя команда.
Пример команды для экспорта раздела |
|
elma365pm export namespace --token=STRING --host=STRING --out=STRING или elma365pm export ns --token=STRING --host=STRING --out=STRING
|
|
Пример команды для экспорта решения |
|
elma365pm export solution --token=STRING --host=STRING --out=STRING или elma365pm export sln --token=STRING --host=STRING --out=STRING
|
|
Пример команды для экспорта модуля |
|
elma365pm export module --token=STRING --host=STRING --out=STRING или elma365pm export mod --token=STRING --host=STRING --out=STRING
|
|
Пример команды для экспорта конфигурации |
|
elma365pm export configuration --token=STRING --host=STRING --out=STRING или elma365pm export cfg --token=STRING --host=STRING --out=STRING
|
|
Доступные флаги для команд экспорта |
|
--token=String |
Вместо String укажите токен авторизации, созданный в ELMA365 в разделе Администрирование. |
--host=String |
Вместо String укажите адрес хоста ELMA365. |
--out=String |
Вместо String укажите директорию файловой системы, куда экспортируется пакет. |
--code=String |
Вместо String укажите код идентификатора экспортируемого компонента. |
--dts |
Флаг управляет генерацией файлов d.ts, которые активируют подсказки IDE по типам языка TypeScript в скриптах. По умолчанию генерация этих файлов отключена. Важно: для пакетов с множеством компонентов генерация может занять продолжительное время. |
--experimental-restruct |
Реструктурировать пакет для отображения логической иерархии файлов. Используйте с осторожностью. |
--allow-deps=true/false |
Применяется при экспорте решений. Позволяет выгрузить решение с добавленными связями с компонентами другого решения. Подробнее читайте в разделе «Особенности использования утилиты». |
Импортировать объекты в ELMA365
Команда |
elma365pm import |
Пример команды |
elma365pm import --token=STRING --host=STRING --src=STRING |
Доступные флаги |
|
--token=String |
Вместо String укажите токен авторизации, созданный в ELMA365 в разделе Администрирование. |
--host=String |
Вместо String укажите адрес хоста ELMA365. |
--src=String |
Вместо String укажите директорию файловой системы для упаковки и импорта. |
--version-up |
Обновление версии пакета. |
--replace-org-struct |
Замена организационной структуры. Используется только при импорте конфигурации компании. |
--force |
Принудительный импорт при наличии конфликтов. Используйте с осторожностью, конфликт может означать, что данные на целевом хосте повреждены. |
--fail-on-conflict |
Вывод в коде выхода ненулевого кода ошибки, если при принудительном импорте пакета возникли конфликты. Используется только с флагом |
--exclude-upgrade-permissions |
Сохранение настроенных прав доступа для раздела, решения и конфигурации. При импорте этих компонентов права доступа остаются прежними и не обновляются. |
Проверить пакет на пригодность к импорту
Команда |
elma365pm check |
Пример команды |
elma365pm check --token=STRING --host=STRING --src=STRING |
Доступные флаги |
|
--token=String |
Вместо String укажите токен авторизации, созданный в ELMA365 в разделе Администрирование. |
--host=String |
Вместо String укажите адрес хоста ELMA365. |
--src=String |
Вместо String укажите директорию файловой системы для упаковки и импорта. |
--version-up |
Обновление версии пакета. |
Посмотреть версию утилиты
Команда |
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 |
На верхнем уровне находятся папки сервисов, т. к. архитектура системы микросервисная. В каждой папке сервиса обычно есть файл manifest.json и две папки entities и resources. В корне также лежит файл package.json, в котором описаны основные данные выгруженного решения или раздела.
В основном файлы в структуре делятся на три типа:
- Файлы описаний конфигурации — это файлы формата .json или файлы без расширения, также являющиеся JSON-файлами. В этих файлах можно найти описание полей и настройки приложения, описание процесса, виджеты и модули.
- Файлы скриптов — это файлы формата .ts, в которых хранятся тексты скриптов процессов, виджетов, модулей.
Файлы скриптов распаковываются для удобного просмотра и совместного ревью кода. Содержимое этих файлов не упаковывается в пакет при импорте. Вы можете редактировать распакованные файлы скриптов, а также использовать файлы-автодополнения для удобства работы в редакторах кода.
- Прочие файлы ресурсов или локализации. Такие файлы обычно находятся в папке
resources. Локализация пакетов решений в будущем будет переработана, поэтому сейчас файлы локализации используются ровно один раз при первом импорте пакета. Вы можете вносить изменения прямо в эти файлы, и они будут упакованы утилитой.