From 5e41aa5cc4080a423fe35454cc1b5331ba731150 Mon Sep 17 00:00:00 2001
From: Andreas Hilbig <andreas.hilbig@hilbigit.com>
Date: Tue, 27 Jan 2026 18:44:44 +0100
Subject: [PATCH] chore: add default filters for host and host group queries

- Introduced `HOST_TYPE_FILTER_DEFAULT` and `HOST_GROUP_FILTER_DEFAULT` constants in the `Config` class.
- Updated resolvers to use these defaults when `tag_hostType` or `search_name` arguments are not provided.
- Added corresponding tests to verify default behavior in host and host group queries.
- Added documentation on overriding 'HOST_GROUP_FILTER_DEFAULT' by explicitly setting the 'search_name' argument in the 'allHostGroups' query.
- Explained the usage of the '*' wildcard in 'search_name' with a concrete example for subgroup matching.
---
 .idea/workspace.xml         | 26 +++++++++++--------
 README.md                   | 52 +++++++++++++++++++++++++++++++++++++
 src/api/resolvers.ts        | 13 ++++++----
 src/common_utils.ts         |  2 ++
 src/test/host_query.test.ts | 30 +++++++++++++++++++++
 5 files changed, 107 insertions(+), 16 deletions(-)

diff --git a/.idea/workspace.xml b/.idea/workspace.xml
index 58392a8..ad6f159 100644
--- a/.idea/workspace.xml
+++ b/.idea/workspace.xml
@@ -4,17 +4,12 @@
     <option name="autoReloadType" value="SELECTIVE" />
   </component>
   <component name="ChangeListManager">
-    <list default="true" id="d7a71994-2699-4ae4-9fd2-ee13b7f33d35" name="Changes" comment="chore: update base host group name from &quot;Baustellen-Devices&quot; to &quot;Roadwork&quot; in code, tests, and documentation">
+    <list default="true" id="d7a71994-2699-4ae4-9fd2-ee13b7f33d35" name="Changes" comment="chore: centralize configuration management using a new `Config` class&#10;&#10;- Replaced all direct `process.env` references with `Config` class constants.&#10;- Added `dotenv` package to manage environment variables.&#10;- Updated affected files, including schema loader, Zabbix API, resolvers, logging system, and integration points.&#10;- Improved maintainability and consistency in environment variable handling.">
       <change beforePath="$PROJECT_DIR$/.idea/workspace.xml" beforeDir="false" afterPath="$PROJECT_DIR$/.idea/workspace.xml" afterDir="false" />
-      <change beforePath="$PROJECT_DIR$/package-lock.json" beforeDir="false" afterPath="$PROJECT_DIR$/package-lock.json" afterDir="false" />
-      <change beforePath="$PROJECT_DIR$/package.json" beforeDir="false" afterPath="$PROJECT_DIR$/package.json" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/README.md" beforeDir="false" afterPath="$PROJECT_DIR$/README.md" afterDir="false" />
       <change beforePath="$PROJECT_DIR$/src/api/resolvers.ts" beforeDir="false" afterPath="$PROJECT_DIR$/src/api/resolvers.ts" afterDir="false" />
-      <change beforePath="$PROJECT_DIR$/src/api/schema.ts" beforeDir="false" afterPath="$PROJECT_DIR$/src/api/schema.ts" afterDir="false" />
       <change beforePath="$PROJECT_DIR$/src/common_utils.ts" beforeDir="false" afterPath="$PROJECT_DIR$/src/common_utils.ts" afterDir="false" />
-      <change beforePath="$PROJECT_DIR$/src/datasources/zabbix-api.ts" beforeDir="false" afterPath="$PROJECT_DIR$/src/datasources/zabbix-api.ts" afterDir="false" />
-      <change beforePath="$PROJECT_DIR$/src/datasources/zabbix-permissions.ts" beforeDir="false" afterPath="$PROJECT_DIR$/src/datasources/zabbix-permissions.ts" afterDir="false" />
-      <change beforePath="$PROJECT_DIR$/src/index.ts" beforeDir="false" afterPath="$PROJECT_DIR$/src/index.ts" afterDir="false" />
-      <change beforePath="$PROJECT_DIR$/src/logging/logger.ts" beforeDir="false" afterPath="$PROJECT_DIR$/src/logging/logger.ts" afterDir="false" />
+      <change beforePath="$PROJECT_DIR$/src/test/host_query.test.ts" beforeDir="false" afterPath="$PROJECT_DIR$/src/test/host_query.test.ts" afterDir="false" />
     </list>
     <option name="SHOW_DIALOG" value="false" />
     <option name="HIGHLIGHT_CONFLICTS" value="true" />
@@ -120,7 +115,7 @@
       <recent name="\\wsl.localhost\Ubuntu\home\ahilbig\git\vcr\zabbix-graphql-api\schema" />
     </key>
   </component>
-  <component name="RunManager" selected="npm.test">
+  <component name="RunManager" selected="Node.js.index.ts">
     <configuration name="copy-schema" type="js.build_tools.npm" temporary="true" nameIsGenerated="true">
       <package-json value="$PROJECT_DIR$/package.json" />
       <command value="run" />
@@ -353,7 +348,15 @@
       <option name="project" value="LOCAL" />
       <updated>1769525714791</updated>
     </task>
-    <option name="localTasksCounter" value="20" />
+    <task id="LOCAL-00020" summary="chore: centralize configuration management using a new `Config` class&#10;&#10;- Replaced all direct `process.env` references with `Config` class constants.&#10;- Added `dotenv` package to manage environment variables.&#10;- Updated affected files, including schema loader, Zabbix API, resolvers, logging system, and integration points.&#10;- Improved maintainability and consistency in environment variable handling.">
+      <option name="closed" value="true" />
+      <created>1769531308340</created>
+      <option name="number" value="00020" />
+      <option name="presentableId" value="LOCAL-00020" />
+      <option name="project" value="LOCAL" />
+      <updated>1769531308340</updated>
+    </task>
+    <option name="localTasksCounter" value="21" />
     <servers />
   </component>
   <component name="TypeScriptGeneratedFilesManager">
@@ -393,7 +396,8 @@
     <MESSAGE value="chore: update Docker image path in workflows and README" />
     <MESSAGE value="docs: add Virtual Control Room (VCR) sample application info to README.md&#10;&#10;- Added a new section describing the Virtual Control Room (VCR) as a sample application.&#10;&#10;- Explained how VCR utilizes key API features like hierarchical mapping, dynamic authorization, mass provisioning, and data visualization.&#10;&#10;- Included a link to the technical product information PDF in the docs folder.&#10;&#10;- Added VCR to the Key Features list." />
     <MESSAGE value="chore: update base host group name from &quot;Baustellen-Devices&quot; to &quot;Roadwork&quot; in code, tests, and documentation" />
-    <option name="LAST_COMMIT_MESSAGE" value="chore: update base host group name from &quot;Baustellen-Devices&quot; to &quot;Roadwork&quot; in code, tests, and documentation" />
+    <MESSAGE value="chore: centralize configuration management using a new `Config` class&#10;&#10;- Replaced all direct `process.env` references with `Config` class constants.&#10;- Added `dotenv` package to manage environment variables.&#10;- Updated affected files, including schema loader, Zabbix API, resolvers, logging system, and integration points.&#10;- Improved maintainability and consistency in environment variable handling." />
+    <option name="LAST_COMMIT_MESSAGE" value="chore: centralize configuration management using a new `Config` class&#10;&#10;- Replaced all direct `process.env` references with `Config` class constants.&#10;- Added `dotenv` package to manage environment variables.&#10;- Updated affected files, including schema loader, Zabbix API, resolvers, logging system, and integration points.&#10;- Improved maintainability and consistency in environment variable handling." />
   </component>
   <component name="XDebuggerManager">
     <breakpoint-manager>
diff --git a/README.md b/README.md
index 01d2740..71b50a7 100644
--- a/README.md
+++ b/README.md
@@ -58,6 +58,8 @@ The API is configured via environment variables. Create a `.env` file or set the
 | `ZABBIX_EDGE_DEVICE_BASE_GROUP` | Base host group for devices | `Roadwork` |
 | `ZABBIX_PERMISSION_TEMPLATE_GROUP_NAME_PREFIX` | Prefix for template groups used as permissions | `Permissions` |
 | `SCHEMA_PATH` | Path to the directory containing `.graphql` schema files | `./schema/` |
+| `HOST_GROUP_FILTER_DEFAULT` | Default search pattern for `allHostGroups` query | |
+| `HOST_TYPE_FILTER_DEFAULT` | Default value for `tag_hostType` filter in `allHosts` and `allDevices` queries | |
 
 ### Starting the API
 
@@ -187,6 +189,54 @@ This allows for fine-grained access control in your frontend or external applica
 
 For a complete example of how to import these permission groups, see the [Permissions Template Groups Import Sample](docs/sample_import_permissions_template_groups_mutation.graphql).
 
+## Host Classification & Filtering
+
+The API leverages Zabbix tags to classify hosts and devices, enabling efficient filtering and multi-tenancy support.
+
+### The `hostType` Tag
+
+The `hostType` tag is used to categorize hosts and templates. This allows the API to provide default filters for specific application domains or device categories.
+
+#### How to set the Host Type in Zabbix:
+
+To classify a host or a template, simply add a tag in the Zabbix UI or via the API:
+*   **Tag Name**: `hostType`
+*   **Tag Value**: A string representing the category (e.g., `Roadwork/Devices`, `SmartCity/Sensors`).
+
+This tag can be defined:
+1.  **Directly on the Host**: Specific to that individual device.
+2.  **On a Template**: All hosts linked to this template will inherit the classification.
+
+### Default Filtering with `HOST_TYPE_FILTER_DEFAULT`
+
+By configuring the `HOST_TYPE_FILTER_DEFAULT` environment variable, you can set a global default for the `allHosts` and `allDevices` queries. 
+
+*   If `HOST_TYPE_FILTER_DEFAULT=Roadwork/Devices` is set, a query like `allHosts { host }` will only return hosts that have the `hostType` tag set to `Roadwork/Devices`.
+*   This default can always be overridden in the GraphQL query by explicitly passing the `tag_hostType` argument.
+
+### Search Filtering with `HOST_GROUP_FILTER_DEFAULT`
+
+The `HOST_GROUP_FILTER_DEFAULT` variable provides a default search pattern for the `allHostGroups` query. This is particularly useful for restricting the visible host group hierarchy to a specific subtree by default.
+
+#### Overriding the Default Filter
+
+The default filter can be overridden by explicitly providing the `search_name` argument in the `allHostGroups` query. When `search_name` is present, the environment variable is ignored.
+
+#### Using Wildcards
+
+The `search_name` parameter supports the `*` wildcard (enabled via the Zabbix API's `searchWildcardsEnabled` feature). This allows you to search for all subgroups within a specific path.
+
+**Example**: To find all subgroups of `Roadwork/Devices/`, use the following query:
+
+```graphql
+query {
+  allHostGroups(search_name: "Roadwork/Devices/*") {
+    groupid
+    name
+  }
+}
+```
+
 ## Sample Application: Virtual Control Room (VCR)
 
 The **Virtual Control Room (VCR)** is a professional cockpit and control center application designed for monitoring and managing large-scale deployments of IoT and Edge devices, such as traffic management systems, roadwork safety equipment, and environmental sensors.
@@ -214,6 +264,8 @@ ZABBIX_AUTH_TOKEN=your-super-admin-token-here
 ZABBIX_EDGE_DEVICE_BASE_GROUP=Roadwork
 API_VERSION=1.0.0
 SCHEMA_PATH=./schema/
+HOST_GROUP_FILTER_DEFAULT=Roadwork/Devices/*
+HOST_TYPE_FILTER_DEFAULT=Roadwork/Devices
 
 # Schema Extensions (No-Code)
 ADDITIONAL_SCHEMAS=./schema/extensions/display_devices.graphql,./schema/extensions/location_tracker_devices.graphql,./schema/extensions/location_tracker_commons.graphql
diff --git a/src/api/resolvers.ts b/src/api/resolvers.ts
index 025a5b8..e55c45a 100644
--- a/src/api/resolvers.ts
+++ b/src/api/resolvers.ts
@@ -97,7 +97,9 @@ export function createResolvers(): Resolvers {
                 zabbixAuthToken,
                 cookie, dataSources
             }: any) => {
-                args.tag_hostType ??= [ZABBIX_EDGE_DEVICE_BASE_GROUP];
+                if (Config.HOST_TYPE_FILTER_DEFAULT) {
+                    args.tag_hostType ??= [Config.HOST_TYPE_FILTER_DEFAULT];
+                }
                 return await new ZabbixQueryHostsRequestWithItemsAndInventory(zabbixAuthToken, cookie)
                     .executeRequestThrowError(
                         dataSources.zabbixAPI, new ParsedArgs(args)
@@ -107,8 +109,9 @@ export function createResolvers(): Resolvers {
                 zabbixAuthToken,
                 cookie, dataSources
             }: any) => {
-                args.tag_hostType ??= [ZABBIX_EDGE_DEVICE_BASE_GROUP];
-
+                if (Config.HOST_TYPE_FILTER_DEFAULT) {
+                    args.tag_hostType ??= [Config.HOST_TYPE_FILTER_DEFAULT];
+                }
                 return await new ZabbixQueryDevices(zabbixAuthToken, cookie)
                     .executeRequestThrowError(
                         dataSources.zabbixAPI, new ZabbixQueryDevicesArgs(args)
@@ -118,8 +121,8 @@ export function createResolvers(): Resolvers {
                 zabbixAuthToken,
                 cookie
             }: any) => {
-                if (!args.search_name) {
-                    args.search_name = ZABBIX_EDGE_DEVICE_BASE_GROUP + "/*"
+                if (!args.search_name && Config.HOST_GROUP_FILTER_DEFAULT) {
+                    args.search_name = Config.HOST_GROUP_FILTER_DEFAULT
                 }
                 return await new ZabbixQueryHostgroupsRequest(zabbixAuthToken, cookie).executeRequestThrowError(
                     zabbixAPI, new ZabbixQueryHostgroupsParams(args)
diff --git a/src/common_utils.ts b/src/common_utils.ts
index 58b75e1..937350c 100644
--- a/src/common_utils.ts
+++ b/src/common_utils.ts
@@ -14,4 +14,6 @@ static readonly DRY_RUN = process.env.DRY_RUN
     static readonly ZABBIX_ROADWORK_BASE_GROUP = process.env.ZABBIX_ROADWORK_BASE_GROUP
     static readonly ZABBIX_PERMISSION_TEMPLATE_GROUP_NAME_PREFIX = process.env.ZABBIX_PERMISSION_TEMPLATE_GROUP_NAME_PREFIX || "Permissions"
     static readonly LOG_LEVELS = process.env.LOG_LEVELS
+    static readonly HOST_TYPE_FILTER_DEFAULT = process.env.HOST_TYPE_FILTER_DEFAULT;
+    static readonly HOST_GROUP_FILTER_DEFAULT = process.env.HOST_GROUP_FILTER_DEFAULT;
 }
\ No newline at end of file
diff --git a/src/test/host_query.test.ts b/src/test/host_query.test.ts
index 98e8dd2..9b256d7 100644
--- a/src/test/host_query.test.ts
+++ b/src/test/host_query.test.ts
@@ -2,6 +2,7 @@
 import {createResolvers} from "../api/resolvers.js";
 import {zabbixAPI, ZABBIX_EDGE_DEVICE_BASE_GROUP} from "../datasources/zabbix-api.js";
 import {QueryAllHostsArgs, QueryAllDevicesArgs, QueryAllHostGroupsArgs} from "../schema/generated/graphql.js";
+import {Config} from "../common_utils.js";
 
 // Mocking ZabbixAPI
 jest.mock("../datasources/zabbix-api.js", () => ({
@@ -14,6 +15,14 @@ jest.mock("../datasources/zabbix-api.js", () => ({
     ZABBIX_EDGE_DEVICE_BASE_GROUP: "Roadwork"
 }));
 
+// Mocking Config
+jest.mock("../common_utils.js", () => ({
+    Config: {
+        HOST_TYPE_FILTER_DEFAULT: "Roadwork",
+        HOST_GROUP_FILTER_DEFAULT: "Roadwork/%"
+    }
+}));
+
 describe("Host and HostGroup Resolvers", () => {
     let resolvers: any;
 
@@ -94,6 +103,27 @@ describe("Host and HostGroup Resolvers", () => {
         }));
     });
 
+    test("allHostGroups query - uses default search pattern", async () => {
+        const mockGroups = [{ groupid: "10", name: "Roadwork/Group 1" }];
+        (zabbixAPI.post as jest.Mock).mockResolvedValueOnce(mockGroups);
+
+        const args: QueryAllHostGroupsArgs = {};
+        const context = { 
+            zabbixAuthToken: "test-token"
+        };
+
+        const result = await resolvers.Query.allHostGroups(null, args, context);
+
+        expect(result).toEqual(mockGroups);
+        expect(zabbixAPI.post).toHaveBeenCalledWith("hostgroup.get", expect.objectContaining({
+            body: expect.objectContaining({
+                params: expect.objectContaining({
+                    search: { name: ["Roadwork/%"] }
+                })
+            })
+        }));
+    });
+
     test("locations query", async () => {
         const mockLocations = [{ name: "Loc 1", latitude: 1.0, longitude: 2.0 }];
         (zabbixAPI.getLocations as jest.Mock).mockResolvedValueOnce(mockLocations);