From 15dd138f042ede7222453ed85d27dfa04dbee6c7 Mon Sep 17 00:00:00 2001 From: Jagdish Khunti <66874579+JagdishKhunti@users.noreply.github.com> Date: Wed, 9 Sep 2026 14:30:53 +0100 Subject: [PATCH 1/5] ATL-674:- Add SHIELD telemetry event API endpoints Introduces SHIELD telemetry event support in the Data Gateway OpenAPI spec, including new event schemas, event-name enum values, and endpoints to create events plus list events globally or by tenant with optional date filtering. Also bumps the API and TypeScript SDK package versions to 3.3.4 to publish the new contract. --- specs/Data-Gateway.json | 290 ++++++++++++++++++- src/dataGateway/TypeScript/package-lock.json | 4 +- src/dataGateway/TypeScript/package.json | 2 +- 3 files changed, 292 insertions(+), 4 deletions(-) diff --git a/specs/Data-Gateway.json b/specs/Data-Gateway.json index af58517..3b41ef5 100644 --- a/specs/Data-Gateway.json +++ b/specs/Data-Gateway.json @@ -2080,6 +2080,66 @@ } ] }, + "Telemetry.Shield.EventName": { + "description": "Enumeration of SHIELD telemetry event names that can be recorded for a tenant.", + "type": "string", + "enum": [ + "license_report_saved", + "license_report_started", + "shield_installed" + ], + "examples": [ + "shield_installed", + "license_report_saved" + ], + "title": "Application Telemetry - SHIELD Event Name" + }, + "Telemetry.Shield.Event": { + "description": "A single SHIELD telemetry event recorded for a tenant.", + "type": "object", + "properties": { + "eventId": { + "$ref": "#/components/schemas/Uuid", + "description": "Unique identifier for the event record." + }, + "eventName": { + "$ref": "#/components/schemas/Telemetry.Shield.EventName", + "description": "Name of the SHIELD event." + }, + "tenantId": { + "$ref": "#/components/schemas/Uuid", + "description": "Tenant that generated the event." + }, + "createdAt": { + "$ref": "#/components/schemas/DateTimeStringType", + "description": "Timestamp indicating when the record was created. This value is automatically managed by Sequelize." + }, + "updatedAt": { + "$ref": "#/components/schemas/DateTimeStringType", + "description": "Timestamp indicating when the record was last updated. This value is automatically managed by Sequelize." + } + }, + "required": [ + "eventName" + ], + "title": "Application Telemetry - SHIELD Event", + "examples": [ + { + "eventId": "c1a2b3d4-5e6f-4789-9abc-def012345678", + "eventName": "shield_installed", + "tenantId": "46759f55-fb42-49e3-83ab-93de2a39bc1d", + "createdAt": "2026-01-01T00:00:00.000Z", + "updatedAt": "2026-01-01T00:00:00.000Z" + }, + { + "eventId": "e3c4d5f6-7a8b-4901-bcde-f01234567890", + "eventName": "license_report_saved", + "tenantId": "46759f55-fb42-49e3-83ab-93de2a39bc1d", + "createdAt": "2026-01-02T08:20:00.000Z", + "updatedAt": "2026-01-02T08:20:00.000Z" + } + ] + }, "Update.Shield.Check": { "description": "Object returning the value of the version of the latest application package available.", "properties": { @@ -5699,7 +5759,7 @@ }, "description": "Collects data from the various SHI Lab products and makes it available in a standardized way.", "title": "SHI - Data Gateway", - "version": "3.3.1" + "version": "3.3.4" }, "openapi": "3.1.1", "paths": { @@ -8043,6 +8103,234 @@ ] } }, + "/Api/Telemetry/Shield/Event": { + "post": { + "description": "Submits a single SHIELD event for the authenticated tenant.\n\nThis endpoint requires the `Telemetry.Shield.ReadWrite`, or `Telemetry.Shield.ReadWrite.All` scope (permission).", + "operationId": "/Api/Telemetry/Shield/Event/Post", + "requestBody": { + "content": { + "application/json": { + "examples": { + "Shield Installed": { + "description": "Example event reported when SHIELD is installed on a tenant.", + "summary": "Shield Installed Event", + "value": { + "eventName": "shield_installed" + } + }, + "License Report Saved": { + "description": "Example event reported when a license report has finished saving for a tenant.", + "summary": "License Report Saved Event", + "value": { + "eventName": "license_report_saved" + } + } + }, + "schema": { + "$ref": "#/components/schemas/Telemetry.Shield.Event" + } + } + } + }, + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "Shield Installed": { + "description": "The recorded event after being saved for the authenticated tenant.", + "summary": "Recorded Shield Installed Event", + "value": { + "eventId": "c1a2b3d4-5e6f-4789-9abc-def012345678", + "eventName": "shield_installed", + "tenantId": "46759f55-fb42-49e3-83ab-93de2a39bc1d", + "createdAt": "2026-01-01T00:00:00.000Z", + "updatedAt": "2026-01-01T00:00:00.000Z" + } + }, + "License Report Saved": { + "description": "The recorded event after being saved for the authenticated tenant.", + "summary": "Recorded License Report Saved Event", + "value": { + "eventId": "e3c4d5f6-7a8b-4901-bcde-f01234567890", + "eventName": "license_report_saved", + "tenantId": "46759f55-fb42-49e3-83ab-93de2a39bc1d", + "createdAt": "2026-01-02T08:20:00.000Z", + "updatedAt": "2026-01-02T08:20:00.000Z" + } + } + }, + "schema": { + "$ref": "#/components/schemas/Telemetry.Shield.Event" + } + } + }, + "description": "OK" + }, + "400": { + "$ref": "#/components/responses/400" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403" + }, + "500": { + "$ref": "#/components/responses/500" + } + }, + "tags": [ + "Telemetry" + ], + "summary": "Creates a SHIELD Event" + }, + "get": { + "description": "Retrieves the SHIELD event records that have been reported across all tenants, optionally filtered to a date range. This endpoint does not filter by tenant, so records for every tenant are returned. Data is not guaranteed to be retrieved in any specific order.\n\nThis endpoint requires the `Telemetry.Shield.Read`, or `Telemetry.Shield.Read.All` scope (permission). This endpoint is also only accessible from the `SHI` and `SHI Lab` tenants. End user access is restricted.", + "operationId": "/Api/Telemetry/Shield/Event/Get", + "parameters": [ + { + "$ref": "#/components/parameters/dateStart" + }, + { + "$ref": "#/components/parameters/dateEnd" + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "List of Events": { + "description": "List of SHIELD event records reported across all tenants.", + "summary": "List of SHIELD Event Records", + "value": [ + { + "eventId": "c1a2b3d4-5e6f-4789-9abc-def012345678", + "eventName": "shield_installed", + "tenantId": "46759f55-fb42-49e3-83ab-93de2a39bc1d", + "createdAt": "2026-01-01T00:00:00.000Z", + "updatedAt": "2026-01-01T00:00:00.000Z" + }, + { + "eventId": "d2b3c4e5-6f7a-4890-abcd-ef0123456789", + "eventName": "license_report_started", + "tenantId": "a7159bdc-678d-4726-901e-cd6d018d46e2", + "createdAt": "2026-01-02T08:15:00.000Z", + "updatedAt": "2026-01-02T08:15:00.000Z" + }, + { + "eventId": "e3c4d5f6-7a8b-4901-bcde-f01234567890", + "eventName": "license_report_saved", + "tenantId": "a7159bdc-678d-4726-901e-cd6d018d46e2", + "createdAt": "2026-01-02T08:20:00.000Z", + "updatedAt": "2026-01-02T08:20:00.000Z" + } + ] + } + }, + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Telemetry.Shield.Event" + }, + "minItems": 0 + } + } + }, + "description": "OK" + }, + "400": { + "$ref": "#/components/responses/400" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403" + } + }, + "summary": "Lists SHIELD Event Records", + "tags": [ + "Telemetry" + ] + } + }, + "/Api/Telemetry/Shield/Event/Tenant/{tenantId}": { + "get": { + "description": "Retrieves the SHIELD event records that have been reported for the specified tenant, optionally filtered to a date range. Data is not guaranteed to be retrieved in any specific order.\n\nThis endpoint requires the `Telemetry.Shield.Read`, or `Telemetry.Shield.Read.All` scope (permission). This endpoint is also only accessible from the `SHI` and `SHI Lab` tenants. End user access is restricted.", + "operationId": "/Api/Telemetry/Shield/Event/Tenant/:tenantId/Get", + "parameters": [ + { + "$ref": "#/components/parameters/tenantId" + }, + { + "$ref": "#/components/parameters/dateStart" + }, + { + "$ref": "#/components/parameters/dateEnd" + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "List of Events": { + "description": "List of SHIELD event records reported for the specified tenant.", + "summary": "List of SHIELD Event Records", + "value": [ + { + "eventId": "c1a2b3d4-5e6f-4789-9abc-def012345678", + "eventName": "shield_installed", + "tenantId": "46759f55-fb42-49e3-83ab-93de2a39bc1d", + "createdAt": "2026-01-01T00:00:00.000Z", + "updatedAt": "2026-01-01T00:00:00.000Z" + }, + { + "eventId": "d2b3c4e5-6f7a-4890-abcd-ef0123456789", + "eventName": "license_report_started", + "tenantId": "46759f55-fb42-49e3-83ab-93de2a39bc1d", + "createdAt": "2026-01-02T08:15:00.000Z", + "updatedAt": "2026-01-02T08:15:00.000Z" + }, + { + "eventId": "e3c4d5f6-7a8b-4901-bcde-f01234567890", + "eventName": "license_report_saved", + "tenantId": "46759f55-fb42-49e3-83ab-93de2a39bc1d", + "createdAt": "2026-01-02T08:20:00.000Z", + "updatedAt": "2026-01-02T08:20:00.000Z" + } + ] + } + }, + "schema": { + "type": "array", + "items": { + "$ref": "#/components/schemas/Telemetry.Shield.Event" + }, + "minItems": 0 + } + } + }, + "description": "OK" + }, + "400": { + "$ref": "#/components/responses/400" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403" + } + }, + "summary": "Retrieves SHIELD Event Records for Specified Tenant", + "tags": [ + "Telemetry" + ] + } + }, "/Api/Update/Shield/Channel": { "get": { "description": "Retrieves all of the channel configurations that are present in the update service.\n\nThis endpoint requires the `UpdateShield.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI Lab` tenant. End user access is restricted.", diff --git a/src/dataGateway/TypeScript/package-lock.json b/src/dataGateway/TypeScript/package-lock.json index 885e5e1..bb52b4b 100644 --- a/src/dataGateway/TypeScript/package-lock.json +++ b/src/dataGateway/TypeScript/package-lock.json @@ -1,12 +1,12 @@ { "name": "@software-hardware-integration-lab/sdk-data-gateway", - "version": "3.3.3", + "version": "3.3.4", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@software-hardware-integration-lab/sdk-data-gateway", - "version": "3.3.3", + "version": "3.3.4", "license": "MIT", "dependencies": { "@microsoft/kiota-authentication-azure": "~1.0.0-preview.103", diff --git a/src/dataGateway/TypeScript/package.json b/src/dataGateway/TypeScript/package.json index 00e4e83..4c7c94e 100644 --- a/src/dataGateway/TypeScript/package.json +++ b/src/dataGateway/TypeScript/package.json @@ -1,6 +1,6 @@ { "name": "@software-hardware-integration-lab/sdk-data-gateway", - "version": "3.3.3", + "version": "3.3.4", "type": "module", "main": "bin/index.js", "description": "SDK client used to interface with the SHI Data Gateway service.", From c3eddfdd014130b3702c8cab0297092610d2fec5 Mon Sep 17 00:00:00 2001 From: Jagdish Khunti <66874579+JagdishKhunti@users.noreply.github.com> Date: Wed, 9 Sep 2026 15:43:46 +0100 Subject: [PATCH 2/5] Clarify SHIELD event schema and permissions Marks SHIELD event identifiers and timestamps as read-only in the OpenAPI schema. Updates the GET endpoint permission text to reflect the required Telemetry.Shield.Read.All and Telemetry.Shield.ReadWrite.All scopes, and adjusts the spec version metadata accordingly. --- specs/Data-Gateway.json | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/specs/Data-Gateway.json b/specs/Data-Gateway.json index 3b41ef5..304ba43 100644 --- a/specs/Data-Gateway.json +++ b/specs/Data-Gateway.json @@ -2100,7 +2100,8 @@ "properties": { "eventId": { "$ref": "#/components/schemas/Uuid", - "description": "Unique identifier for the event record." + "description": "Unique identifier for the event record.", + "readOnly": true }, "eventName": { "$ref": "#/components/schemas/Telemetry.Shield.EventName", @@ -2108,15 +2109,18 @@ }, "tenantId": { "$ref": "#/components/schemas/Uuid", - "description": "Tenant that generated the event." + "description": "Tenant that generated the event.", + "readOnly": true }, "createdAt": { "$ref": "#/components/schemas/DateTimeStringType", - "description": "Timestamp indicating when the record was created. This value is automatically managed by Sequelize." + "description": "Timestamp indicating when the record was created. This value is automatically managed by Sequelize.", + "readOnly": true }, "updatedAt": { "$ref": "#/components/schemas/DateTimeStringType", - "description": "Timestamp indicating when the record was last updated. This value is automatically managed by Sequelize." + "description": "Timestamp indicating when the record was last updated. This value is automatically managed by Sequelize.", + "readOnly": true } }, "required": [ @@ -5759,7 +5763,7 @@ }, "description": "Collects data from the various SHI Lab products and makes it available in a standardized way.", "title": "SHI - Data Gateway", - "version": "3.3.4" + "version": "3.3.2" }, "openapi": "3.1.1", "paths": { @@ -8186,7 +8190,7 @@ "summary": "Creates a SHIELD Event" }, "get": { - "description": "Retrieves the SHIELD event records that have been reported across all tenants, optionally filtered to a date range. This endpoint does not filter by tenant, so records for every tenant are returned. Data is not guaranteed to be retrieved in any specific order.\n\nThis endpoint requires the `Telemetry.Shield.Read`, or `Telemetry.Shield.Read.All` scope (permission). This endpoint is also only accessible from the `SHI` and `SHI Lab` tenants. End user access is restricted.", + "description": "Retrieves the SHIELD event records that have been reported across all tenants, optionally filtered to a date range. This endpoint does not filter by tenant, so records for every tenant are returned. Data is not guaranteed to be retrieved in any specific order.\n\nThis endpoint requires the `Telemetry.Shield.Read.All`, or `Telemetry.Shield.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI` and `SHI Lab` tenants. End user access is restricted.", "operationId": "/Api/Telemetry/Shield/Event/Get", "parameters": [ { @@ -8258,7 +8262,7 @@ }, "/Api/Telemetry/Shield/Event/Tenant/{tenantId}": { "get": { - "description": "Retrieves the SHIELD event records that have been reported for the specified tenant, optionally filtered to a date range. Data is not guaranteed to be retrieved in any specific order.\n\nThis endpoint requires the `Telemetry.Shield.Read`, or `Telemetry.Shield.Read.All` scope (permission). This endpoint is also only accessible from the `SHI` and `SHI Lab` tenants. End user access is restricted.", + "description": "Retrieves the SHIELD event records that have been reported for the specified tenant, optionally filtered to a date range. Data is not guaranteed to be retrieved in any specific order.\n\nThis endpoint requires the `Telemetry.Shield.Read.All`, or `Telemetry.Shield.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI` and `SHI Lab` tenants. End user access is restricted.", "operationId": "/Api/Telemetry/Shield/Event/Tenant/:tenantId/Get", "parameters": [ { From 73e215c753e7ad1370147ac8150129147bed2f28 Mon Sep 17 00:00:00 2001 From: Jagdish Khunti <66874579+JagdishKhunti@users.noreply.github.com> Date: Wed, 9 Sep 2026 15:48:14 +0100 Subject: [PATCH 3/5] Clarify SHIELD telemetry schema descriptions This change updates the Data Gateway schema descriptions for SHIELD event types and records to make the wording more concise and consistent. It removes redundant 'telemetry' phrasing and clarifies that the eventId uniquely identifies the event itself. --- specs/Data-Gateway.json | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/specs/Data-Gateway.json b/specs/Data-Gateway.json index 304ba43..57d3bc0 100644 --- a/specs/Data-Gateway.json +++ b/specs/Data-Gateway.json @@ -2081,7 +2081,7 @@ ] }, "Telemetry.Shield.EventName": { - "description": "Enumeration of SHIELD telemetry event names that can be recorded for a tenant.", + "description": "Enumeration of SHIELD event names that can be recorded for a tenant.", "type": "string", "enum": [ "license_report_saved", @@ -2095,12 +2095,12 @@ "title": "Application Telemetry - SHIELD Event Name" }, "Telemetry.Shield.Event": { - "description": "A single SHIELD telemetry event recorded for a tenant.", + "description": "A single SHIELD event recorded for a tenant.", "type": "object", "properties": { "eventId": { "$ref": "#/components/schemas/Uuid", - "description": "Unique identifier for the event record.", + "description": "Unique identifier for the event.", "readOnly": true }, "eventName": { From 17a2476bcd8be8c8bbd68e76eda586b05ae127e9 Mon Sep 17 00:00:00 2001 From: Jagdish Khunti <66874579+JagdishKhunti@users.noreply.github.com> Date: Wed, 9 Sep 2026 16:16:42 +0100 Subject: [PATCH 4/5] Bump Data Gateway to 3.4.0 Update the Data Gateway OpenAPI specification and TypeScript SDK package metadata to version 3.4.0, keeping the published API version and generated package artifacts in sync. --- specs/Data-Gateway.json | 2 +- src/dataGateway/TypeScript/package-lock.json | 4 ++-- src/dataGateway/TypeScript/package.json | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/specs/Data-Gateway.json b/specs/Data-Gateway.json index 57d3bc0..58d3326 100644 --- a/specs/Data-Gateway.json +++ b/specs/Data-Gateway.json @@ -5763,7 +5763,7 @@ }, "description": "Collects data from the various SHI Lab products and makes it available in a standardized way.", "title": "SHI - Data Gateway", - "version": "3.3.2" + "version": "3.4.0" }, "openapi": "3.1.1", "paths": { diff --git a/src/dataGateway/TypeScript/package-lock.json b/src/dataGateway/TypeScript/package-lock.json index bb52b4b..5ce3dd5 100644 --- a/src/dataGateway/TypeScript/package-lock.json +++ b/src/dataGateway/TypeScript/package-lock.json @@ -1,12 +1,12 @@ { "name": "@software-hardware-integration-lab/sdk-data-gateway", - "version": "3.3.4", + "version": "3.4.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@software-hardware-integration-lab/sdk-data-gateway", - "version": "3.3.4", + "version": "3.4.0", "license": "MIT", "dependencies": { "@microsoft/kiota-authentication-azure": "~1.0.0-preview.103", diff --git a/src/dataGateway/TypeScript/package.json b/src/dataGateway/TypeScript/package.json index 4c7c94e..e22839a 100644 --- a/src/dataGateway/TypeScript/package.json +++ b/src/dataGateway/TypeScript/package.json @@ -1,6 +1,6 @@ { "name": "@software-hardware-integration-lab/sdk-data-gateway", - "version": "3.3.4", + "version": "3.4.0", "type": "module", "main": "bin/index.js", "description": "SDK client used to interface with the SHI Data Gateway service.", From bf065d9a6cbb1ca13b8b5a6dba4a2a751c7d3ba3 Mon Sep 17 00:00:00 2001 From: Jagdish Khunti <66874579+JagdishKhunti@users.noreply.github.com> Date: Thu, 10 Sep 2026 10:52:01 +0100 Subject: [PATCH 5/5] Add examples for Shield telemetry events This change adds example payloads for Shield event arrays in the Data-Gateway OpenAPI spec. The examples illustrate common event lifecycle entries such as installation and license report progress, improving discoverability and documentation for API consumers. --- specs/Data-Gateway.json | 50 +++++++++++++++++++++++++++++++++++++++-- 1 file changed, 48 insertions(+), 2 deletions(-) diff --git a/specs/Data-Gateway.json b/specs/Data-Gateway.json index 57d45a4..70740b1 100644 --- a/specs/Data-Gateway.json +++ b/specs/Data-Gateway.json @@ -8255,7 +8255,30 @@ "items": { "$ref": "#/components/schemas/Telemetry.Shield.Event" }, - "minItems": 0 + "minItems": 0, + "examples": [ + { + "eventId": "c1a2b3d4-5e6f-4789-9abc-def012345678", + "eventName": "shield_installed", + "tenantId": "46759f55-fb42-49e3-83ab-93de2a39bc1d", + "createdAt": "2026-01-01T00:00:00.000Z", + "updatedAt": "2026-01-01T00:00:00.000Z" + }, + { + "eventId": "d2b3c4e5-6f7a-4890-abcd-ef0123456789", + "eventName": "license_report_started", + "tenantId": "a7159bdc-678d-4726-901e-cd6d018d46e2", + "createdAt": "2026-01-02T08:15:00.000Z", + "updatedAt": "2026-01-02T08:15:00.000Z" + }, + { + "eventId": "e3c4d5f6-7a8b-4901-bcde-f01234567890", + "eventName": "license_report_saved", + "tenantId": "a7159bdc-678d-4726-901e-cd6d018d46e2", + "createdAt": "2026-01-02T08:20:00.000Z", + "updatedAt": "2026-01-02T08:20:00.000Z" + } + ] } } }, @@ -8330,7 +8353,30 @@ "items": { "$ref": "#/components/schemas/Telemetry.Shield.Event" }, - "minItems": 0 + "minItems": 0, + "examples": [ + { + "eventId": "c1a2b3d4-5e6f-4789-9abc-def012345678", + "eventName": "shield_installed", + "tenantId": "46759f55-fb42-49e3-83ab-93de2a39bc1d", + "createdAt": "2026-01-01T00:00:00.000Z", + "updatedAt": "2026-01-01T00:00:00.000Z" + }, + { + "eventId": "d2b3c4e5-6f7a-4890-abcd-ef0123456789", + "eventName": "license_report_started", + "tenantId": "46759f55-fb42-49e3-83ab-93de2a39bc1d", + "createdAt": "2026-01-02T08:15:00.000Z", + "updatedAt": "2026-01-02T08:15:00.000Z" + }, + { + "eventId": "e3c4d5f6-7a8b-4901-bcde-f01234567890", + "eventName": "license_report_saved", + "tenantId": "46759f55-fb42-49e3-83ab-93de2a39bc1d", + "createdAt": "2026-01-02T08:20:00.000Z", + "updatedAt": "2026-01-02T08:20:00.000Z" + } + ] } } },