Custom solutions can be developed in short iterations to maintain their integrity and versioning. This approach can be implemented using the Develop > Test > Production cycle. In this cycle, the solution goes through three stages, each of which is performed in a separate company: the dev company is used for development, the test company is used for testing, and the prod company is used for the operation of the finished solution.
This cycle is performed by using the principles of Continuous integration and Continuous delivery and deploy or CI/CD.
HUMMIX provides several tools that can be used independently of each other to implement the CI/CD approach:
- Low-code CI / CD provides the exchange of components between companies from different environments based on standard export and import processes. All configuration is done in the HUMMIX interface. Two companies should be bound to each other. Then an exchange profile is created: configuration components are selected, the type of operation is specified, etc. The profile is saved, which allows the exchange operation to be performed several times. You can also compare the configurations of the two companies and analyze the results of the operation. The exchange process is performed in the background. For more information about the tool, see the Low-code CI/CD.
- hummixpm utility is an auxiliary independent command line utility used in conjunction with external version control and pipelines configuration services, such as GitLab. The utility allows you to export a company configuration component (workspace, module, or solution) to a file. The work is then performed in an external service, thus making it possible to use operations from high-code development. The component is updated to a new version, packed into a file, and imported into another company.
This article describes the main principle of working with the hummixpm utility and available commands.
Download utility
Use these links to download the hummixpm utility for various operating systems, compatible with HUMMIX SaaS deliveries and the latest version of HUMMIX On-Premises:
- Linux.
- Windows.
- macOS (Intel x64 architecture).
- macOS (ARM x64 architecture), M1 processor).
After downloading, unpack the .exe file.
Available utility commands
The hummixpm utility is operated by running commands on the command line. Commands can be used with available flags. They are written after the command name.
After downloading the utility, you can request help information by executing the command:
hummixpm --help
To get detailed instructions on each command, run the following:
hummixpm <command> --help
The following features are currently available:
Command:
Use:
Flags: |
|
|
Path to the component. |
|
The file system directory where the package is unzipped to. |
|
By default, the directory and file structure after unpacking an export package corresponds to the internal structure of this package. Apply the flag to restructure the package for better visibility. Then, when unpacking, a hierarchical structure of the solution will be formed. For example, the app description file will be located in the workspace directory, the workspace directory in the solution directory, descriptions of portable services or API methods in the module directory, etc. The flag should be used with caution. |
Command:
Use:
Flags: |
|
|
The file system directory where the unpacked package is stored. |
|
The file where the package is packed into. |
|
Package version update. |
Command:
Use:
|
|
Subcommands (available export components): |
|
Use:
|
|
Use:
|
|
Use:
|
|
Use:
|
|
Flags available for export subcommands: |
|
|
Authentication token created in HUMMIX in the Administration workspace. |
|
HUMMIX host address. |
|
The file system directory to which the package is exported. |
|
The ID code of the exported component. |
|
This flag controls the generation of d.ts files that activate IDE tips for TypeScript language types in scripts. It is enabled by default. Important: for packages with many components, generation may take a while. |
|
Restructure the package to display a logical hierarchy of files. Use with caution. |
|
This flag is used when exporting solutions. It allows you to export a solution with added links to components of another solution. For more details, see Utility features. |
Command:
Use:
Flags: |
|
|
Authentication token created in HUMMIX in the Administration workspace. |
|
HUMMIX host address. |
|
File system directory for packing and importing. |
|
Package version update. |
|
Organizational chart replacement. It is used only when importing a company configuration. |
|
Forced import if there are conflicts. Use with caution, a conflict may mean that data on the target host is corrupted. |
|
Output a non-zero error code in the exit code if there are conflicts during the forced import of a package. Use only with the |
--exclude-upgrade-permissions |
Preserves configured access permissions for the workspace, solution, and configuration. When importing these components, the access permissions remain the same and are not updated. |
Command:
Use:
Flags: |
|
|
Authentication token created in HUMMIX in the Administration workspace. |
|
HUMMIX host address. |
|
File system directory for packing and importing. |
|
Package version update. |
Command:
Use:
Flag:
|
|
Flags available for each command: |
|
|
Help information about the command. |
|
Output detailed logs of the operation execution. |
|
Waiting for the operation to be performed. The default value is 5 minutes. It is changed in case of bulk processing. For example: |
Utility features
Pay attention to the features of the hummixpm utility:
- The utility cannot be used to export or import paid system solutions.
- To export a solution with configured links to components of another solution,the
--allow-depsparameter with the valuetrueis applied in the export command:
hummixpm export solution --token=TOKEN --host=https://dev-hummix.myorg
--out=my_solution --code=my_solution_code --allow-deps=true
If you do not use the --allow-deps parameter or you set it to false, the solution with associated components will not be exported.
Utility use example
For example, the GitLab service is used as a source code storage and continuous delivery infrastructure. This is the most popular product with the ability to deploy its server in a closed loop.
Let’s consider the main stages of continuous delivery and deploy on the example of the Memos (Internal_Documents) solution.
- The solution developer performs the work in the company with dev environment.
- After development is complete, the solution must be uploaded to the repository folder in the file system. To do this, the following command is used:
hummixpm export solution --token=TOKEN --host=https://dev15-hummix.myorg
--out=Internal_Documents --code=Internal_Documents
The export and import token are created by the system administrator in Administration > Tokens.
After executing this command, the /Internal_Documents folder will contain the Memos solution files.
- The developer then uses the git repository tools according to internal rules.
In our example, the developer commits the changes to a separate working branch and pushes them to a shared repository on the GitLab service. Next, a request is created on the server in the working repository to merge its branch into the common develop branch.
- After the developer branch is checked and approved, the merge is performed.
- In the process of automatic solution delivery on the develop branch, the following is performed:
- packing the solution artefact into an .e365 file for testing:
hummixpm pack --src=procurement --out=dist/procurement.e365
- uploading the solution to a company with a test environment:
hummixpm import --token=TEST-TOKEN --host=https://test-hummix.myorg
--src=Internal_Documents --version-up --force
To ignore import errors and force an import, the --force flag is used in the example.
- After testing, the solution is uploaded for operation in a prod environment company:
hummixpm import --token=PRODUCTION-TOKEN --host=https://hummix.myorg
--src=Internal_Documents --version-up
File structure of a solution
When you unpack the solution into files by using the hummixpm export command, you will see the structure of the solution in the target folder. As an example, we use the prebuilt business solution Memos.
PS InternalDocuments> tree /F |
The top level consists of service folders, as the system architecture is microservice-based. Each service folder usually has the manifest.json file and 2 folders entities and resources. The root also stores the package.json file that includes the main data of the exported solution or workspace.
Generally, there are three types of files in the structure:
- Configuration files are .json files or files with no extension (that are also .json files). These files include information about apps’ fields and settings, as well as processes, widgets, and modules.
- Script files are .ts files that contain the code of scripts from processes, widgets, and modules.
Script files are unpacked only for easy viewing and code review. The content of these files is not included into the package when the solution is imported.
- Other resource and localization files are usually stored in the
resourcesfolder. Solution package localization is going to be considerably reworked, so now localization files are used only once during the import of a package. You can make changes directly to these files. They will be used to form a new package that can be imported with the utility.