QDT Profile¶
Rules¶
Added in version 0.34
You can add rules to make the profile deployment conditional. In the following example, the profile will be deployed only on Linux:
{
"$schema": "https://raw.githubusercontent.com/Guts/qgis-deployment-cli/main/docs/schemas/profile/qgis_profile.json",
"name": "only_linux",
"folder_name": "qdt_only_linux",
"description": "A QGIS profile for QDT with a conditional deployment rule.",
"author": "Julien Moura",
"email": "infos+qdt@oslandia.com",
"qgisMinimumVersion": "3.34.0",
"qgisMaximumVersion": "3.99.10",
"version": "1.7.0",
"rules": [
{
"name": "Environment",
"description": "Profile is configured to run only on Linux.",
"conditions": {
"all": [
{
"path": "$.environment.operating_system_code",
"value": "linux",
"operator": "equal"
}
]
}
}
]
}
The rules engine is based on Python Rule Engine project whom rules syntax belongs to JSON Rules Engine.
Conditions and rules context¶
Rules is a set of conditions that use logical operators to compare values with context (a set of facts) which is exposed as a JSON object. Here comes the context for a Linux environment:
{
"date": {
"current_day": 1,
"current_month": 5,
"current_weekday": 2,
"current_year": 2024
},
"environment": {
"computer_network_name": "fv-az1490-607",
"linux_distribution_name": "Ubuntu",
"linux_distribution_version": "22.04",
"operating_system_code": "linux",
"operating_system_release": "6.5.0-1018-azure",
"processor_architecture": "x86_64",
"windows_edition": null
},
"user": {
"groups_domain": [],
"groups_local": [
"adm",
"systemd-journal"
],
"name": "runner",
"windows_extended": null
}
}
To help you writing rules, QDT provides a command to export rules context:
qdt export-rules-context -o qdt_rules_context.json
Model definition¶
The project comes with a JSON schema describing the model of a profile:
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://github.com/Guts/qgis-deployment-cli/raw/main/docs/schemas/profile/qgis_profile.json",
"$comment": "A QGIS profile described in a JSON file.",
"type": "object",
"properties": {
"alias": {
"description": "Profile's name in an human readable form, allowing special characters.",
"type": "string"
},
"author": {
"description": "Name of profile auhor and maintener.",
"type": "string"
},
"description": {
"description": "Profile description.",
"type": "string"
},
"email": {
"description": "Email of profile's auhor and maintener.",
"format": "email",
"maxLength": 127,
"minLength": 6,
"type": "string"
},
"folder_name": {
"description": "Name of the profile's directory in QGIS.",
"type": "string"
},
"icon": {
"description": "Relative path to the icon used for shortcuts.",
"type": "string"
},
"name": {
"description": "Profile name without any special characters.",
"type": "string"
},
"plugins": {
"description": "Plugins installed with the profile.",
"title": "QGIS Plugins",
"type": "array",
"items": {
"$ref": "qgis_plugin.json"
}
},
"qgisMaximumVersion": {
"description": "Maximum QGIS version where the profile can be deployed.",
"maxLength": 14,
"minLength": 5,
"pattern": "^(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)$",
"type": "string"
},
"qgisMinimumVersion": {
"description": "Minimum QGIS version where the profile can be deployed.",
"maxLength": 14,
"minLength": 5,
"pattern": "^(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)$",
"type": "string"
},
"rules": {
"description": "Logical rules based on contextual elements that condition profile deployment.",
"title": "QGIS Plugins",
"type": "array",
"items": {
"$ref": "rules.json"
}
},
"splash": {
"description": "Relative path to the splash image.",
"type": "string"
},
"version": {
"description": "Profile version. Must complies with SemVer.",
"maxLength": 14,
"minLength": 5,
"pattern": "^(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)$",
"type": "string"
}
},
"required": [
"author",
"email",
"name",
"version"
]
}
With a submodel for plugin object:
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://raw.githubusercontent.com/Guts/qgis-deployment-cli/main/docs/schemas/profile/qgis_plugin.json",
"$comment": "A QGIS plugin described in a JSON file.",
"type": "object",
"properties": {
"folder_name": {
"description": "Name of the plugins's directory once installed in QGIS. Useful when name does not complies with filename conventions.",
"type": "string"
},
"location": {
"description": "Indicates if the plugin is located on a remote server or on local drive/network.",
"enum": ["local", "remote"],
"type": "string"
},
"name": {
"description": "Plugin name, as referenced in the source plugins repository.",
"type": "string"
},
"official_repository": {
"description": "Indicates if the plugin is referenced on plugins.qgis.org",
"type": "boolean"
},
"plugin_id": {
"description": "Plugin ID as referenced into the repository (XML version). Typically for official repository: https://plugins.qgis.org/plugins/plugins.xml?qgis=3.22",
"type": "number"
},
"qgisMaximumVersion": {
"description": "Maximum QGIS version where the plugin can be installed.",
"maxLength": 14,
"minLength": 3,
"pattern": "^(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)$",
"type": "string"
},
"qgisMinimumVersion": {
"description": "Minimum QGIS version where the plugin can be installed.",
"maxLength": 14,
"minLength": 3,
"pattern": "^(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)\\.(?:0|[1-9]\\d*)$",
"type": "string"
},
"repository_url_xml": {
"description": "URL to the plugin repository file (XML).",
"type": "string",
"examples": ["https://oslandia.gitlab.io/qgis/ngp-connect/plugins.xml"]
},
"url": {
"description": "Direct URI (URL or local path) to download the plugin archive (.zip).",
"type": "string",
"format": "uri",
"examples": [
"https: //plugins.qgis.org/plugins/QuickOSM/version/2.2.2/download/",
"/home/jmo/Git/Oslandia/QGIS/stsi-plugin-qgis-geocoder-locator-filter/stsi_locator_filter.1.0.0.zip"
]
},
"version": {
"description": "Version of the plugin to be installed.",
"type": "string"
}
}
}
Tip
To retrieve the ID of a plugin see this page.
Sample profile.json¶
{
"$schema": "https://raw.githubusercontent.com/Guts/qgis-deployment-cli/main/docs/schemas/profile/qgis_profile.json",
"name": "demo_qdt",
"folder_name": "demo_qdt",
"description": "QGIS profile made to demonstrate how QGIS Deployement Toolbelt works.",
"author": "Julien Moura",
"email": "qgis@oslandia.com",
"icon": "images/qgis_icon_oslandia.ico",
"qgisMinimumVersion": "3.24",
"qgisMaximumVersion": "3.99",
"version": "1.1.0",
"plugins": [
{
"name": "Layers menu from project",
"folder_name": "menu_from_project",
"official_repository": true,
"plugin_id": 43,
"version": "2.1.0"
},
{
"name": "QuickOSM",
"folder_name": "QuickOSM",
"location": "remote",
"official_repository": true,
"plugin_id": 2733,
"version": "2.1.1"
},
{
"name": "QTribu",
"folder_name": "qtribu",
"official_repository": true,
"plugin_id": 2733,
"version": "0.14.2"
}
]
}