zabbix/zabbix-graphql-api
1
0
Fork 0
Code Pull requests Activity

feat: implement weather sensor extension and enhance device interfaces

Browse source 
This change introduces the Weather Sensor device type which retrieves data from public APIs, and enhances the core Host/Device interfaces to provide consistent access to inventory and items across all specialized device types. It also improves search logic and fixes several bugs identified during implementation.

- Weather Sensor Extension: Added schema and recipe for a device retrieving weather data via Zabbix HTTP agent items.

- Interface Enhancements: Added inventory and items fields to Host and Device interfaces to ensure all device specialized types have consistent access to monitoring and inventory data.

- Search Logic Improvements: Enhanced ParsedArgs to support searchByAny and technical name (host) searches when a name pattern is provided.

- Bug Fixes:

  - Fixed getLocations argument order in the Zabbix API datasource.

  - Implemented deduplication for groupids and templateids in HostImporter to prevent Zabbix duplicate value errors.

  - Added missing url field to CreateTemplateItem for HTTP Agent item support.

- Testing:

  - Extended the regression test suite with 4 new automated checks covering the fixed bugs.

  - Updated Jest tests to accommodate the improved search parameters.

- Documentation: Updated cookbook and test specifications to reflect new features and regression testing obligations.
This commit is contained in:
Andreas Hilbig 2026-02-01 06:36:29 +01:00
parent b84e4c0734
commit 5da4a17e36
20 changed files with 438 additions and 98 deletions
Download patch file Download diff file Expand all files Collapse all files

93
docs/howtos/cookbook.md
View file

@ -194,6 +194,99 @@ AI agents can use the generalized `verifySchemaExtension.graphql` operations to
---
## 🍳 Recipe: Extending Schema with a Weather Sensor Device (Public API)
This recipe demonstrates how to extend the schema with a new device type that retrieves real-time weather data from a public API (Open-Meteo) using Zabbix HTTP agent items. This approach allows you to integrate external data sources into your Zabbix monitoring and expose them through the GraphQL API.
### 📋 Prerequisites
- Zabbix GraphQL API is running.
- The device has geo-coordinates set in its inventory (`location_lat` and `location_lon`).
### 🛠️ Step 1: Define the Schema Extension
Create a new `.graphql` file in `schema/extensions/` named `weather_sensor.graphql`.
```graphql
type WeatherSensorDevice implements Host & Device {
hostid: ID!
host: String!
deviceType: String
hostgroups: [HostGroup!]
name: String
tags: DeviceConfig
state: WeatherSensorState
}
type WeatherSensorState implements DeviceState {
operational: OperationalDeviceData
current: WeatherSensorValues
}
type WeatherSensorValues {
temperature: Float
streetConditionWarnings: String
}
```
### ⚙️ Step 2: Register the Resolver
Add the new type and schema to your `.env` file to enable the dynamic resolver:
```env
ADDITIONAL_SCHEMAS=./schema/extensions/weather_sensor.graphql
ADDITIONAL_RESOLVERS=WeatherSensorDevice
```
Restart the API server to apply the changes.
### 🚀 Step 3: Import the Weather Sensor Template
Use the `importTemplates` mutation to create the `WEATHER_SENSOR` template. This template uses an **HTTP agent** item to fetch data from Open-Meteo and **dependent items** to parse the results.
> **Reference**: See the [Sample: Weather Sensor Template Import](../../docs/queries/sample_import_weather_sensor_template.graphql) for the complete mutation and variables.
**Key Item Configuration**:
- **Master Item**: `weather.get` (HTTP Agent)
- URL: `https://api.open-meteo.com/v1/forecast?latitude={INVENTORY.LOCATION.LAT}&longitude={INVENTORY.LOCATION.LON}&current=temperature_2m,weather_code`
- **Dependent Item**: `state.current.temperature` (JSONPath: `$.current.temperature_2m`)
- **Dependent Item**: `state.current.streetConditionWarnings` (JavaScript mapping from `$.current.weather_code`)
### ✅ Step 4: Verification
Create a host, assign it coordinates, and query its weather state.
1. **Create Host**:
```graphql
mutation CreateWeatherHost {
importHosts(hosts: [{
deviceKey: "Berlin-Weather-Sensor",
deviceType: "WeatherSensorDevice",
groupNames: ["External Sensors"],
templateNames: ["WEATHER_SENSOR"],
location: {
name: "Berlin",
location_lat: "52.52",
location_lon: "13.41"
}
}]) {
hostid
}
}
```
2. **Query Data**:
```graphql
query GetWeather {
allDevices(tag_deviceType: ["WeatherSensorDevice"]) {
... on WeatherSensorDevice {
name
state {
current {
temperature
streetConditionWarnings
}
}
}
}
}
```
---
## 🍳 Recipe: Provisioning a New Host
### 📋 Prerequisites

82
docs/queries/sample_import_weather_sensor_template.graphql Normal file
View file

@ -0,0 +1,82 @@
### Mutation
Use this mutation to import a template specifically designed to work with the `WeatherSensorDevice` type. This template retrieves real-time weather data from the public Open-Meteo API using a Zabbix HTTP agent item.
```graphql
mutation ImportWeatherSensorTemplate($templates: [CreateTemplate!]!) {
importTemplates(templates: $templates) {
host
templateid
message
error {
message
code
}
}
}
```
### Variables
The following variables define the `WEATHER_SENSOR` template. It uses the host's inventory coordinates (`{INVENTORY.LOCATION_LAT}` and `{INVENTORY.LOCATION_LON}`) to fetch localized weather data.
```json
{
"templates": [
{
"host": "WEATHER_SENSOR",
"name": "Weather Sensor API Template",
"groupNames": ["Templates/External APIs"],
"tags": [
{ "tag": "deviceType", "value": "WeatherSensorDevice" }
],
"items": [
{
"name": "Open-Meteo API Fetch",
"type": 19,
"key": "weather.get",
"value_type": 4,
"history": "0",
"delay": "1m",
"url": "https://api.open-meteo.com/v1/forecast?latitude={INVENTORY.LOCATION.LAT}&longitude={INVENTORY.LOCATION.LON}&current=temperature_2m,weather_code",
"description": "Master item fetching weather data from Open-Meteo based on host coordinates."
},
{
"name": "Current Temperature",
"type": 18,
"key": "state.current.temperature",
"value_type": 0,
"history": "7d",
"master_item": {
"key": "weather.get"
},
"preprocessing": [
{
"type": 12,
"params": ["$.current.temperature_2m"]
}
]
},
{
"name": "Street Condition Warnings",
"type": 18,
"key": "state.current.streetConditionWarnings",
"value_type": 4,
"history": "7d",
"master_item": {
"key": "weather.get"
},
"preprocessing": [
{
"type": 12,
"params": ["$.current.weather_code"]
},
{
"type": 21,
"params": ["var codes = {0:\"Clear\",1:\"Mainly Clear\",2:\"Partly Cloudy\",3:\"Overcast\",45:\"Fog\",48:\"Depositing Rime Fog\",51:\"Light Drizzle\",53:\"Moderate Drizzle\",55:\"Dense Drizzle\",56:\"Light Freezing Drizzle\",57:\"Dense Freezing Drizzle\",61:\"Slight Rain\",63:\"Moderate Rain\",65:\"Heavy Rain\",66:\"Light Freezing Rain\",67:\"Heavy Freezing Rain\",71:\"Slight Snow Fall\",73:\"Moderate Snow Fall\",75:\"Heavy Snow Fall\",77:\"Snow Grains\",80:\"Slight Rain Showers\",81:\"Moderate Rain Showers\",82:\"Violent Rain Showers\",85:\"Slight Snow Showers\",86:\"Heavy Snow Showers\",95:\"Thunderstorm\",96:\"Thunderstorm with Slight Hail\",99:\"Thunderstorm with Heavy Hail\"}; var code = parseInt(value); var warning = codes[code] || \"Unknown\"; if ([56, 57, 66, 67, 71, 73, 75, 77, 85, 86].indexOf(code) !== -1) { return \"WARNING: Slippery Roads (Snow/Ice)\"; } if ([51, 53, 55, 61, 63, 65, 80, 81, 82].indexOf(code) !== -1) { return \"CAUTION: Wet Roads\"; } return warning;"]
}
]
}
]
}
]
}
```

6
docs/tests.md
View file

@ -73,6 +73,10 @@ This document outlines the test cases and coverage for the Zabbix GraphQL API.
#### Currently Contained Regression Tests
The `runAllRegressionTests` mutation (TC-E2E-02) executes the following checks:
- **Host without items**: Verifies that hosts created without any items or linked templates can be successfully queried by the system. This ensures that the hierarchical mapping and resolvers handle empty item lists gracefully.
- **Locations query argument order**: Verifies that the `locations` query correctly handles its parameters and successfully contacts the Zabbix API without session errors (verifying the fix for argument order in the resolver).
- **Template technical name lookup**: Verifies that templates can be correctly identified by their technical name (`host` field) when linking them to hosts during import.
- **HTTP Agent URL support**: Verifies that templates containing HTTP Agent items with a configured URL can be imported successfully (verifying the addition of the `url` field to `CreateTemplateItem`).
- **Host retrieval and visibility**: Verifies that newly imported hosts are immediately visible and retrievable via the `allHosts` query, including correctly delivered assigned templates and assigned host groups (verifying the fix for `output` fields in the host query data source).
## ✅ Test Coverage Checklist
@ -129,6 +133,6 @@ The `runAllRegressionTests` mutation (TC-E2E-02) executes the following checks:
As per project guidelines, every new feature or bug fix must be accompanied by a described test case in this specification.
- **Feature**: A new feature must have a corresponding test case (TC) defined before implementation.
- **Bug Fix**: A bug fix must include a reproduction test case that fails without the fix and passes with it.
- **Bug Fix**: A bug fix must include a reproduction test case that fails without the fix and passes with it. Additionally, a permanent regression test must be added to the automated suite (e.g., `RegressionTestExecutor`) to prevent the issue from re-occurring.
- **Documentation**: The `docs/tests.md` file must be updated to reflect any changes in test coverage.
- **Categorization**: Tests must be categorized as Unit, Integration, or End-to-End (E2E).