This module is used to enable CICD practices for Ignition tags. It enables the capability to export and import tag configurations from a gateway to a git repository. This allows for the ability to track tag changes in a git repository and to be able to roll back changes if needed.
During the export process, the module creates a deterministically sorted copy of the JSON data to ensure that source control is not confused when a new file gets saved, and the keys are accidentally reordered. This process is applied recursively to all nested arrays and objects within the JSON data.
A document of example API calls has been added, which can be found here.
GET /data/tag-cicd/tags/export
This endpoint exports the tag configuration as a JSON string.
| Name | Type | Description |
|---|---|---|
provider |
string |
The tag provider to export from. If not specified, defaults to the DEFAULT_PROVIDER. |
baseTagPath |
string |
The base tag path to start the export from. If not specified, defaults to an empty string, which means the export will start from the root of the tag provider. |
recursive |
boolean |
If true, the export will recursively include all tags and folders under the baseTagPath. If false, only the direct children of the baseTagPath will be exported. |
localPropsOnly |
boolean |
If true, only the local properties of the tags will be exported (user-created configuration). If false, all properties (including inherited properties) will be exported. |
curl "https://tag-cicd.localtest.me/data/tag-cicd/tags/export?provider=default&baseTagPath=MyTagFolder&recursive=true&localPropsOnly=true"The response will be a JSON string containing the exported tag configuration.
POST /data/tag-cicd/tags/export
This endpoint exports the tag configuration and saves it to a specified file path on the Ignition gateway server.
| Name | Type | Description |
|---|---|---|
provider |
string |
The tag provider to export from. If not specified, defaults to the DEFAULT_PROVIDER. |
baseTagPath |
string |
The base tag path to start the export from. If not specified, defaults to an empty string, which means the export will start from the root of the tag provider. |
recursive |
boolean |
If true, the export will recursively include all tags and folders under the baseTagPath. If false, only the direct children of the baseTagPath will be exported. |
localPropsOnly |
boolean |
If true, only the local properties of the tags will be exported (user-created configuration). If false, all properties (including inherited properties) will be exported. |
filePath |
string |
The file path on the Ignition gateway server where the exported tag configuration will be saved. This parameter is required. |
individualFilesPerObject |
boolean |
If true, the export will create individual JSON files for each tag and folder, maintaining the tag hierarchy. If false, the entire tag configuration will be exported as a single JSON file. |
deleteExisting |
boolean |
If true, any existing files or directories in the export directory that are not going to be replaced by the new export will be deleted before saving the new export. If false (default), existing files and directories will not be deleted. |
curl -X POST "http://tag-cicd.localtest.me/data/tag-cicd/tags/export?provider=default&baseTagPath=MyTagFolder&recursive=true&localPropsOnly=true&filePath=data/projects/my-project/tags.json&individualFilesPerObject=false&deleteExisting=true"The response will be a JSON string containing the exported tag configuration, similar to the Export Tags endpoint. The exported tag configuration will also be saved to the specified filePath on the Ignition gateway server.
POST /data/tag-cicd/tags/import
This endpoint imports a tag configuration from a JSON string in the request body.
| Name | Type | Description |
|---|---|---|
provider |
string |
The tag provider to import into. If not specified, it will be determined from the JSON payload. If the JSON payload does not specify a provider, the DEFAULT_PROVIDER will be used. |
baseTagPath |
string |
The base tag path where the imported tags will be created/updated. If not specified, defaults to an empty string, which means the tags will be imported at the root of the tag provider. |
collisionPolicy |
string |
The collision policy to use when importing tags. Valid values are: "a" (abort), "o" (overwrite), "u" (update), and "d" (delete and overwrite). If not specified, defaults to "a". |
filePath |
string |
The file path on the Ignition gateway server from where the tag configuration will be imported. This parameter is required when individualFilesPerObject is true. |
individualFilesPerObject |
boolean |
If true, the import will expect individual JSON files for each tag and folder, maintaining the tag hierarchy. The filePath parameter should point to the directory containing the JSON files. If false, the import will expect a single JSON file containing the entire tag configuration. |
curl -X POST -H "Content-Type: application/json" -d @path/to/tag_configuration.json "http://tag-cicd.localtest.me/data/tag-cicd/tags/import?provider=default&baseTagPath=MyTagFolder&collisionPolicy=o"The request body should be a JSON string representing the tag configuration to import. The format of the JSON depends on the value of individualFilesPerObject:
- If
individualFilesPerObjectisfalse, the request body should be a single JSON object representing the entire tag configuration. - If
individualFilesPerObjectistrue, the request body should be omitted, and the tag configuration will be imported from individual JSON files located at the specifiedfilePath.
The response will be a JSON object containing the results of the import operation, including the created and deleted tags.
This repository provides two convenience scripts for exporting and importing tags: tag-export.sh and tag-import.sh. These scripts simplify the process of interacting with the module's API endpoints.
The tag-export.sh script allows you to easily export tags from an Ignition gateway using the module's export API endpoint.
./tag-export.sh [options] <gateway_base_url>| Option | Description | Default |
|---|---|---|
-p, --provider <provider> |
Set the provider | default |
-t, --base-tag-path <path> |
Set the base tag path | Empty string |
-r, --recursive <true|false> |
Set recursive export | true |
-d, --delete-existing |
Delete existing tags before exporting | - |
-h, --help |
Display the help message | - |
./tag-export.sh -p default -t MyTagFolder -r true --delete-existing http://localhost:8088The tag-import.sh script allows you to easily import tags into an Ignition gateway using the module's import API endpoint.
./tag-import.sh [options] <gateway_base_url>| Option | Description | Default |
|---|---|---|
-p, --provider <provider> |
Set the provider | default |
-c, --policy <policy> |
Set the collision policy | o (overwrite) |
-d, --directory <path> |
Specify the directory path to import | - |
-a, --auto |
Automatically import tags from all providers in the specified directory | - |
--force |
Force overwrite if collision policy is set to o |
- |
--debug |
Enable debug mode | - |
-h, --help |
Display the help message | - |
./tag-import.sh -p default -c o -d /path/to/tags --force http://localhost:8088Within the root directory there is a file named gradle.properties.template. This file should be copied to gradle.properties and the properties within it should be filled out with the appropriate values.
| Property | Description |
|---|---|
ignition.signing.keystoreFile |
The path to the keystore file. |
ignition.signing.keystorePassword |
The password for the keystore. |
ignition.signing.certFile |
The path to the certificate file. |
ignition.signing.certAlias |
The alias of the certificate. |
ignition.signing.certPassword |
The password for the certificate. |
Once the gradle.properties file has been filled out, the module can be built by running the following command:
./gradlew build- Install SDKMAN
curl -s "https://get.sdkman.io" | bash- Install Java
sdk install java java 17.0.11-zulu- Install Gradle
sdk install gradle 7.5.1- If you are going to deploy to a gateway with non-standard certificates installed, you will need to add the gateway's certificate to the Java truststore. This can be done by running the following commands:
keytool -import -cacerts -alias root_ca -file /path/to/root_ca.crt -storepass changeit
keytool -import -cacerts -alias server_cert -file /path/to/server.crt -storepass changeit