From f35a6b7ae79c5b044c635fa5ec6841419e219cd7 Mon Sep 17 00:00:00 2001 From: Ferry To Date: Thu, 9 Apr 2026 12:25:37 +0100 Subject: [PATCH 01/17] feat: Add POST Cloud Matrix Assessment template endpoint specification. --- specs/Data-Gateway.json | 408 +++++++++++++++++++++++++++++++++++++++- 1 file changed, 407 insertions(+), 1 deletion(-) diff --git a/specs/Data-Gateway.json b/specs/Data-Gateway.json index 84f2d71..3c6b241 100644 --- a/specs/Data-Gateway.json +++ b/specs/Data-Gateway.json @@ -4507,6 +4507,204 @@ ] } ] + }, + "CloudMatrix.TemplateUploadRequest": { + "title": "Value Assessment Template Upload Request", + "description": "Request body for uploading a value assessment template to the data gateway.", + "type": "object", + "properties": { + "templateName": { + "type": "string", + "minLength": 2, + "maxLength": 100, + "pattern": "^[A-Za-z0-9][A-Za-z0-9_ -]*[A-Za-z0-9]$", + "description": "A valid template name allows alphanumeric characters, spaces, underscores, and hyphens, but may not start or end with special characters.", + "examples": [ + "Microsoft Enterprise", + "Microsoft_Academic", + "Google-Workspace" + ] + }, + "templateContent": { + "$ref": "#/components/schemas/CloudMatrix.BulkCloudMatrix" + } + }, + "required": [ + "templateName", + "templateContent" + ], + "examples": [ + { + "templateName": "Microsoft Enterprise", + "templateContent": { + "title": "CloudMatrix Value Assessment - Microsoft Enterprise", + "description": "MICROSOFT CLOUD ADOPTION MATRIX v5.0 for Microsoft Enterprise", + "version": "5.0.14", + "valueAssessment": { + "actionPlan": { + "accountName": "New Account", + "discoveryDate": "2026-01-01T00:00:00Z", + "accountManager": "John Smith", + "consultant": "MSAG Consultant", + "licensingExecutive": "Jane Doe", + "customerSuccessManager": "John Doe", + "notesAndObjectives": "Sample notes and objectives for the account.", + "accountId": "fd9a6a53-594d-41aa-950a-b21ff41d4688", + "createdDate": "2026-01-01T00:00:00Z", + "modifiedDate": "2026-01-01T00:00:00Z", + "primaryPublisher": "Microsoft" + }, + "userProfiles": [ + { + "id": "00000000-0000-0000-0000-000000000001", + "name": "Profile Details", + "details": [ + { + "name": "Profile Details", + "values": [ + { + "name": "Profile Name", + "value": "Knowledge Worker" + } + ] + } + ] + } + ], + "assessments": [ + { + "metadata": { + "name": "M365 Apps for Enterprise - Mobile/Online", + "breakoutId": null, + "category": "USER EXPERIENCE", + "subCategory": "Productivity", + "help": "Brief: Common applications available through a browser used for business purposes typically bundled together by software vendors like Microsoft and Google. i.e., spreadsheets, slide presentations, word processor, etc.", + "licensingProduct": "M365 Mobile Apps", + "licensingProductHelp": "Mobile Apps The Microsoft 365 mobile app combines Word, Excel, and PowerPoint into a single app for iOS and Android devices. It offers features like creating, editing, and sharing documents on the go, scanning and signing PDFs, and using voice commands for quick tasks. You can also connect your email accounts and calendars in one convenient spot1.\n\nWeb Apps Microsoft 365 for the web includes online versions of Word, Excel, PowerPoint, OneNote, and Outlook. These web apps allow you to create, edit, and share documents directly from your browser without needing to install any software. You can access your documents from anywhere with an internet connection, making it easy to collaborate with others in real-time2.", + "isAddon": false, + "isStrategicAddon": false, + "isTenantBased": false, + "availability": null, + "notes": "", + "startYearConfig": { + "value": null, + "userProfileIds": null, + "isDeepDive": false, + "altProduct": null, + "publisher": null, + "useCase": null + }, + "yearPlusOneConfig": { + "value": null, + "userProfileIds": null, + "isDeepDive": false, + "altProduct": null, + "publisher": null, + "useCase": null + }, + "yearPlusTwoConfig": { + "value": null, + "userProfileIds": null, + "isDeepDive": false, + "altProduct": null, + "publisher": null, + "useCase": null + }, + "yearPlusThreeConfig": { + "value": null, + "userProfileIds": null, + "isDeepDive": false, + "altProduct": null, + "publisher": null, + "useCase": null + }, + "sourceValue": 0.0 + }, + "profiles": [ + { + "name": "Microsoft E5", + "abbreviation": "ME5P", + "value": 5.0 + } + ], + "features": [ + { + "licensing": "M365 SMB", + "products": [ + { + "product": "PS", + "value": "na", + "comment": "" + } + ] + } + ] + } + ], + "displacements": [ + { + "name": "Example displacement opportunity", + "currentProvider": { + "name": "Microsoft", + "terms": "5 Years", + "contractNumber": "C12345678", + "expiryDate": "2026-01-01T00:00:00Z", + "costs": { + "monthlyCost": 5001, + "annualCost": 5002, + "contractValue": 5003 + } + }, + "displacement": { + "name": "Google", + "terms": "3 Years", + "contractNumber": "C87654321", + "expiryDate": "2026-01-01T00:00:00Z", + "costs": [ + { + "monthlyCost": 5001, + "annualCost": 5002, + "contractValue": 5003 + } + ], + "replacementDate": "2026-12-31T00:00:00Z" + }, + "notes": "Example notes" + } + ] + }, + "breakouts": [ + { + "title": "PORTAL APPS", + "breakoutId": "f1ebe6ab-1164-4ab8-8970-2d561ee7634f", + "breakoutName": "BREAKOUT -Portal Apps", + "features": [ + { + "roadmapElementPath": "User Experience /Productivity Apps/Extended Productivity App Ecosystem", + "elementSubdimension": "Productivity Apps", + "roadmapProduct": "Platform Only", + "feature": "Viva Insights - Personal", + "description": "Microsoft Lists is a Microsoft 365 app that helps you track information and organize work with customizable lists for tasks, projects, and more.", + "publisherLink": "", + "subscriptionFeatures": [ + { + "licensing": "M365 FLW", + "products": [ + { + "product": "F1", + "value": "na", + "comment": "" + } + ] + } + ] + } + ] + } + ] + } + } + ] } }, "securitySchemes": { @@ -9078,6 +9276,214 @@ "Cloud Matrix" ], "summary": "Get a Default Assessment Schema Object" + }, + "post": { + "description": "Add or update a value assessment template. When the specified template name exists, it will overwrite the existing template JSON file in blob storage.\n\nThis endpoint is only accessible from the `SHI` and `SHI Lab` tenants and requires the `CloudMatrix.ReadWrite.All` scope (permission).", + "operationId": "/Api/CloudMatrix/Template/Post", + "requestBody": { + "required": true, + "content": { + "application/json": { + "examples": { + "Sample value assessment template upload request": { + "description": "This is a sample request for uploading a value assessment template. Multiple invocations of this endpoint with the same template name will overwrite the existing template.", + "summary": "A sample value assessment template upload request for the Microsoft Enterprise template.", + "value": { + "templateName": "Microsoft Enterprise", + "templateContent": { + "title": "CloudMatrix Value Assessment - Microsoft Enterprise", + "description": "MICROSOFT CLOUD ADOPTION MATRIX v5.0 for Microsoft Enterprise", + "version": "5.0.14", + "valueAssessment": { + "actionPlan": { + "accountName": "New Account", + "discoveryDate": "2026-01-01T00:00:00Z", + "accountManager": "John Smith", + "consultant": "MSAG Consultant", + "licensingExecutive": "Jane Doe", + "customerSuccessManager": "John Doe", + "notesAndObjectives": "Sample notes and objectives for the account.", + "accountId": "fd9a6a53-594d-41aa-950a-b21ff41d4688", + "createdDate": "2026-01-01T00:00:00Z", + "modifiedDate": "2026-01-01T00:00:00Z", + "primaryPublisher": "Microsoft" + }, + "userProfiles": [ + { + "id": "00000000-0000-0000-0000-000000000001", + "name": "Profile Details", + "details": [ + { + "name": "Profile Details", + "values": [ + { + "name": "Profile Name", + "value": "Knowledge Worker" + } + ] + } + ] + } + ], + "assessments": [ + { + "metadata": { + "name": "M365 Apps for Enterprise - Mobile/Online", + "breakoutId": null, + "category": "USER EXPERIENCE", + "subCategory": "Productivity", + "help": "Brief: Common applications available through a browser used for business purposes typically bundled together by software vendors like Microsoft and Google. i.e., spreadsheets, slide presentations, word processor, etc.", + "licensingProduct": "M365 Mobile Apps", + "licensingProductHelp": "Mobile Apps The Microsoft 365 mobile app combines Word, Excel, and PowerPoint into a single app for iOS and Android devices. It offers features like creating, editing, and sharing documents on the go, scanning and signing PDFs, and using voice commands for quick tasks. You can also connect your email accounts and calendars in one convenient spot1.\n\nWeb Apps Microsoft 365 for the web includes online versions of Word, Excel, PowerPoint, OneNote, and Outlook. These web apps allow you to create, edit, and share documents directly from your browser without needing to install any software. You can access your documents from anywhere with an internet connection, making it easy to collaborate with others in real-time2.", + "isAddon": false, + "isStrategicAddon": false, + "isTenantBased": false, + "availability": null, + "notes": "", + "startYearConfig": { + "value": null, + "userProfileIds": null, + "isDeepDive": false, + "altProduct": null, + "publisher": null, + "useCase": null + }, + "yearPlusOneConfig": { + "value": null, + "userProfileIds": null, + "isDeepDive": false, + "altProduct": null, + "publisher": null, + "useCase": null + }, + "yearPlusTwoConfig": { + "value": null, + "userProfileIds": null, + "isDeepDive": false, + "altProduct": null, + "publisher": null, + "useCase": null + }, + "yearPlusThreeConfig": { + "value": null, + "userProfileIds": null, + "isDeepDive": false, + "altProduct": null, + "publisher": null, + "useCase": null + }, + "sourceValue": 0.0 + }, + "profiles": [ + { + "name": "Microsoft E5", + "abbreviation": "ME5P", + "value": 5.0 + } + ], + "features": [ + { + "licensing": "M365 SMB", + "products": [ + { + "product": "PS", + "value": "na", + "comment": "" + } + ] + } + ] + } + ], + "displacements": [ + { + "name": "Example displacement opportunity", + "currentProvider": { + "name": "Microsoft", + "terms": "5 Years", + "contractNumber": "C12345678", + "expiryDate": "2026-01-01T00:00:00Z", + "costs": { + "monthlyCost": 5001, + "annualCost": 5002, + "contractValue": 5003 + } + }, + "displacement": { + "name": "Google", + "terms": "3 Years", + "contractNumber": "C87654321", + "expiryDate": "2026-01-01T00:00:00Z", + "costs": [ + { + "monthlyCost": 5001, + "annualCost": 5002, + "contractValue": 5003 + } + ], + "replacementDate": "2026-12-31T00:00:00Z" + }, + "notes": "Example notes" + } + ] + }, + "breakouts": [ + { + "title": "PORTAL APPS", + "breakoutId": "f1ebe6ab-1164-4ab8-8970-2d561ee7634f", + "breakoutName": "BREAKOUT -Portal Apps", + "features": [ + { + "roadmapElementPath": "User Experience /Productivity Apps/Extended Productivity App Ecosystem", + "elementSubdimension": "Productivity Apps", + "roadmapProduct": "Platform Only", + "feature": "Viva Insights - Personal", + "description": "Microsoft Lists is a Microsoft 365 app that helps you track information and organize work with customizable lists for tasks, projects, and more.", + "publisherLink": "", + "subscriptionFeatures": [ + { + "licensing": "M365 FLW", + "products": [ + { + "product": "F1", + "value": "na", + "comment": "" + } + ] + } + ] + } + ] + } + ] + } + } + } + }, + "schema": { + "$ref": "#/components/schemas/CloudMatrix.TemplateUploadRequest" + } + } + } + }, + "responses": { + "201": { + "description": "Upserted the value assessment template successfully." + }, + "400": { + "$ref": "#/components/responses/400" + }, + "415": { + "description": "Unsupported Media Type - The request payload must use the application/json media type." + }, + "500": { + "$ref": "#/components/responses/500" + } + }, + "tags": [ + "Cloud Matrix" + ], + "summary": "Upload Cloud Matrix Assessment Template" } }, "/Api/CloudMatrix/Assessment": { @@ -10708,4 +11114,4 @@ "name": "Cloud Matrix" } ] -} +} \ No newline at end of file From 096939e049d7f4a556593f2d7b6e97dfcd8a178d Mon Sep 17 00:00:00 2001 From: Ferry To Date: Thu, 9 Apr 2026 13:17:28 +0100 Subject: [PATCH 02/17] fix: Handle created and overwritten case of uploading value assessment template. --- specs/Data-Gateway.json | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/specs/Data-Gateway.json b/specs/Data-Gateway.json index 3c6b241..ed8e906 100644 --- a/specs/Data-Gateway.json +++ b/specs/Data-Gateway.json @@ -9467,8 +9467,11 @@ } }, "responses": { + "200": { + "description": "Value assessment template overwritten successfully." + }, "201": { - "description": "Upserted the value assessment template successfully." + "description": "Value assessment template created successfully." }, "400": { "$ref": "#/components/responses/400" From 47afb339986142bef9c05c8cb1a0a7cd4117d0fa Mon Sep 17 00:00:00 2001 From: JD-ghforme Date: Mon, 13 Apr 2026 12:23:17 -0400 Subject: [PATCH 03/17] initial check-in --- specs/Data-Gateway.json | 94 ++++++++++++++++++++++++++++++++++++++++- 1 file changed, 93 insertions(+), 1 deletion(-) diff --git a/specs/Data-Gateway.json b/specs/Data-Gateway.json index ed8e906..33292a3 100644 --- a/specs/Data-Gateway.json +++ b/specs/Data-Gateway.json @@ -4705,6 +4705,53 @@ } } ] + }, + "CloudMatrix.TemplateMetadata": { + "title": "Template Metadata", + "description": "Metadata information for a value CloudMatrix template in the data gateway.", + "type": "object", + "properties": { + "name": { + "type": "string", + "description": "A valid template name allows alphanumeric characters, spaces, underscores, and hyphens, but may not start or end with special characters.", + "examples": [ + "cloud-matrix", + "google" + ] + }, + "createdOn": { + "$ref": "#/components/schemas/DateTimeStringType", + "description": "Date when the template was created." + }, + "lastModified": { + "$ref": "#/components/schemas/DateTimeStringType", + "description": "Date when the template was last modified." + }, + "type": { + "type": "string", + "description": "A valid template type allows alphanumeric characters, spaces, underscores, and hyphens, but may not start or end with special characters." + } + }, + "required": [ + "createdOn", + "name", + "lastModified", + "type" + ], + "examples": [ + { + "createdOn": "2026-03-24T16:56:43.000Z", + "name": "cloudMatrix", + "lastModified": "2026-03-24T16:56:43.000Z", + "type": "" + }, + { + "createdOn": "2026-04-08T14:15:44.000Z", + "name": "CloudMatrixPremium", + "lastModified": "2026-04-08T14:15:44.000Z", + "type": "" + } + ] } }, "securitySchemes": { @@ -11058,6 +11105,51 @@ "Cloud Matrix" ] } + }, + "/Api/CloudMatrix/Template/List": { + "get": { + "description": "Get a list of all available templates from CM storage. \n\nThis endpoint requires the `CloudMatrix.Read`, `CloudMatrix.Read.Del`, `CloudMatrix.Read.All`, `CloudMatrix.ReadWrite`, or `CloudMatrix.ReadWrite.All` scope (permission).", + "operationId": "/Api/CloudMatrix/Template/List/Get", + "responses": { + "200": { + "description": "List of TemplateFileMetadata objects.", + "content": { + "application/json": { + "examples": { + "Default Output": { + "description": "A list (metadata) templates that are stored in blob storage. This is the default output when there are two templates stored in blob storage.", + "summary": "Default Output", + "value": [ + { + "createdOn": "2026-03-24T16:56:43.000Z", + "name": "cloudMatrix", + "lastModified": "2026-03-24T16:56:43.000Z", + "type": "" + }, + { + "createdOn": "2026-04-08T14:15:44.000Z", + "name": "Google", + "lastModified": "2026-04-08T14:15:44.000Z", + "type": "" + } + ] + } + } + }, + "schema": { + "$ref": "#/components/schemas/CloudMatrix.TemplateMetadata" + } + } + }, + "500": { + "$ref": "#/components/responses/500" + } + }, + "tags": [ + "Cloud Matrix" + ], + "summary": "Get a list of all available CM template objects" + } } }, "security": [ @@ -11117,4 +11209,4 @@ "name": "Cloud Matrix" } ] -} \ No newline at end of file +} From 2a090a26f0b95980f57ec3fa0b340a2d0bd799ce Mon Sep 17 00:00:00 2001 From: JD-ghforme Date: Mon, 13 Apr 2026 13:39:32 -0400 Subject: [PATCH 04/17] more copilot fixes --- specs/Data-Gateway.json | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/specs/Data-Gateway.json b/specs/Data-Gateway.json index 33292a3..a688e24 100644 --- a/specs/Data-Gateway.json +++ b/specs/Data-Gateway.json @@ -4708,7 +4708,7 @@ }, "CloudMatrix.TemplateMetadata": { "title": "Template Metadata", - "description": "Metadata information for a value CloudMatrix template in the data gateway.", + "description": "Metadata information for a valid CloudMatrix template in the data gateway.", "type": "object", "properties": { "name": { @@ -4743,13 +4743,13 @@ "createdOn": "2026-03-24T16:56:43.000Z", "name": "cloudMatrix", "lastModified": "2026-03-24T16:56:43.000Z", - "type": "" + "type": "Standard" }, { "createdOn": "2026-04-08T14:15:44.000Z", "name": "CloudMatrixPremium", "lastModified": "2026-04-08T14:15:44.000Z", - "type": "" + "type": "Premium" } ] } @@ -11124,20 +11124,20 @@ "createdOn": "2026-03-24T16:56:43.000Z", "name": "cloudMatrix", "lastModified": "2026-03-24T16:56:43.000Z", - "type": "" + "type": "Standard" }, { "createdOn": "2026-04-08T14:15:44.000Z", "name": "Google", "lastModified": "2026-04-08T14:15:44.000Z", - "type": "" + "type": "Premium" } ] } + }, + "schema": { + "$ref": "#/components/schemas/CloudMatrix.TemplateMetadata" } - }, - "schema": { - "$ref": "#/components/schemas/CloudMatrix.TemplateMetadata" } } }, From 1acf9f2325dae74970ba2ff3dc1c5552432d03b1 Mon Sep 17 00:00:00 2001 From: JD-ghforme Date: Mon, 13 Apr 2026 13:50:57 -0400 Subject: [PATCH 05/17] a couple more copilot fixes --- specs/Data-Gateway.json | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/specs/Data-Gateway.json b/specs/Data-Gateway.json index a688e24..cd54256 100644 --- a/specs/Data-Gateway.json +++ b/specs/Data-Gateway.json @@ -4713,6 +4713,8 @@ "properties": { "name": { "type": "string", + "minLength": 2, + "maxLength": 100, "description": "A valid template name allows alphanumeric characters, spaces, underscores, and hyphens, but may not start or end with special characters.", "examples": [ "cloud-matrix", @@ -11117,7 +11119,7 @@ "application/json": { "examples": { "Default Output": { - "description": "A list (metadata) templates that are stored in blob storage. This is the default output when there are two templates stored in blob storage.", + "description": "A list of template metadata that is stored in blob storage. This is the default output when there are two templates stored in blob storage.", "summary": "Default Output", "value": [ { From 9b7c37652c0f875dca0ab03882b66fa7ccb77bc8 Mon Sep 17 00:00:00 2001 From: Jagdish Khunti <66874579+JagdishKhunti@users.noreply.github.com> Date: Wed, 15 Apr 2026 09:01:53 +0100 Subject: [PATCH 06/17] LAB-1922A: Added templateName GET route and bump SDK version - Update OpenAPI spec to support retrieving Cloud Matrix templates by name: - Add a required path parameter `templateName`, change the GET path to `/Api/CloudMatrix/Template/{templateName}` (with updated operationId, descriptions and examples), and adjust response summaries. - Preserve the POST endpoint for creating/updating templates. - Also bump the TypeScript SDK package version from 3.2.0 to 3.2.1. --- specs/Data-Gateway.json | 49 ++++++++++++++++++++----- src/dataGateway/TypeScript/package.json | 2 +- 2 files changed, 40 insertions(+), 11 deletions(-) diff --git a/specs/Data-Gateway.json b/specs/Data-Gateway.json index ed8e906..efe0d86 100644 --- a/specs/Data-Gateway.json +++ b/specs/Data-Gateway.json @@ -164,6 +164,28 @@ "value": "9b2c13f4-6e7a-4e8e-9c9a-a5b9c3f6ad12" } } + }, + "templateName": { + "description": "Name of the Cloud Matrix template to retrieve.", + "in": "path", + "name": "templateName", + "required": true, + "schema": { + "type": "string", + "minLength": 2, + "maxLength": 100, + "pattern": "^[A-Za-z0-9][A-Za-z0-9_ -]*[A-Za-z0-9]$", + "examples": [ + "Microsoft Enterprise" + ] + }, + "examples": { + "valid template name": { + "summary": "Example Valid Template Name", + "description": "An example string of a valid template name.", + "value": "Microsoft Enterprise" + } + } } }, "responses": { @@ -9075,19 +9097,24 @@ "summary": "Get Cloud Matrix Correlation Records" } }, - "/Api/CloudMatrix/Template": { + "/Api/CloudMatrix/Template/{templateName}": { "get": { - "description": "Get a default assessment schema object as schema structure reference. \n\nThis endpoint requires the `CloudMatrix.Read`, `CloudMatrix.Read.Del`, `CloudMatrix.Read.All`, `CloudMatrix.ReadWrite`, or `CloudMatrix.ReadWrite.All` scope (permission).", - "operationId": "/Api/CloudMatrix/Template/Get", + "description": "Retrieves the specified Cloud Matrix assessment template by template name. \n\nThis endpoint requires the `CloudMatrix.Read`, `CloudMatrix.Read.Del`, `CloudMatrix.Read.All`, `CloudMatrix.ReadWrite`, or `CloudMatrix.ReadWrite.All` scope (permission).", + "operationId": "/Api/CloudMatrix/Template/:templateName/Get", + "parameters": [ + { + "$ref": "#/components/parameters/templateName" + } + ], "responses": { "200": { - "description": "The default assessment schema object.", + "description": "The requested assessment template object.", "content": { "application/json": { "examples": { - "Default Output": { - "description": "Always returns the default schema template that stored in blob storage. This has been trimmed to contain one element for brevity.", - "summary": "Default Output", + "Named Template Output": { + "description": "Returns the requested template stored in blob storage. This has been trimmed to contain one element for brevity.", + "summary": "Named Template Output", "value": { "title": "CloudMatrix Value Assessment", "description": "MICROSOFT CLOUD ADOPTION MATRIX v5.0", @@ -9275,8 +9302,10 @@ "tags": [ "Cloud Matrix" ], - "summary": "Get a Default Assessment Schema Object" - }, + "summary": "Get a Specific Assessment Template Schema Object" + } + }, + "/Api/CloudMatrix/Template": { "post": { "description": "Add or update a value assessment template. When the specified template name exists, it will overwrite the existing template JSON file in blob storage.\n\nThis endpoint is only accessible from the `SHI` and `SHI Lab` tenants and requires the `CloudMatrix.ReadWrite.All` scope (permission).", "operationId": "/Api/CloudMatrix/Template/Post", @@ -11117,4 +11146,4 @@ "name": "Cloud Matrix" } ] -} \ No newline at end of file +} diff --git a/src/dataGateway/TypeScript/package.json b/src/dataGateway/TypeScript/package.json index fba3a48..03b9e21 100644 --- a/src/dataGateway/TypeScript/package.json +++ b/src/dataGateway/TypeScript/package.json @@ -1,6 +1,6 @@ { "name": "@shi-corp/sdk-data-gateway", - "version": "3.2.0", + "version": "3.2.1", "type": "module", "main": "bin/index.js", "description": "SDK client used to interface with the SHI Data Gateway service.", From 3daf3193d1d4165cacbfe3fab364cce73cb8ccc3 Mon Sep 17 00:00:00 2001 From: Jagdish Khunti <66874579+JagdishKhunti@users.noreply.github.com> Date: Wed, 15 Apr 2026 10:30:50 +0100 Subject: [PATCH 07/17] Update Data-Gateway.json --- specs/Data-Gateway.json | 33 +++++++++++++++------------------ 1 file changed, 15 insertions(+), 18 deletions(-) diff --git a/specs/Data-Gateway.json b/specs/Data-Gateway.json index efe0d86..4e60a5c 100644 --- a/specs/Data-Gateway.json +++ b/specs/Data-Gateway.json @@ -171,16 +171,10 @@ "name": "templateName", "required": true, "schema": { - "type": "string", - "minLength": 2, - "maxLength": 100, - "pattern": "^[A-Za-z0-9][A-Za-z0-9_ -]*[A-Za-z0-9]$", - "examples": [ - "Microsoft Enterprise" - ] + "$ref": "#/components/schemas/CloudMatrix.TemplateName" }, "examples": { - "valid template name": { + "Valid Template Name": { "summary": "Example Valid Template Name", "description": "An example string of a valid template name.", "value": "Microsoft Enterprise" @@ -4536,16 +4530,7 @@ "type": "object", "properties": { "templateName": { - "type": "string", - "minLength": 2, - "maxLength": 100, - "pattern": "^[A-Za-z0-9][A-Za-z0-9_ -]*[A-Za-z0-9]$", - "description": "A valid template name allows alphanumeric characters, spaces, underscores, and hyphens, but may not start or end with special characters.", - "examples": [ - "Microsoft Enterprise", - "Microsoft_Academic", - "Google-Workspace" - ] + "$ref": "#/components/schemas/CloudMatrix.TemplateName" }, "templateContent": { "$ref": "#/components/schemas/CloudMatrix.BulkCloudMatrix" @@ -4727,6 +4712,18 @@ } } ] + }, + "CloudMatrix.TemplateName": { + "type": "string", + "minLength": 2, + "maxLength": 100, + "pattern": "^[A-Za-z0-9][A-Za-z0-9_ -]*[A-Za-z0-9]$", + "description": "A valid template name allows alphanumeric characters, spaces, underscores, and hyphens, but may not start or end with special characters.", + "examples": [ + "Microsoft Enterprise", + "Microsoft_Academic", + "Google-Workspace" + ] } }, "securitySchemes": { From eeafdae938ad277c854087da578bfa69f32fe44a Mon Sep 17 00:00:00 2001 From: JD-ghforme Date: Wed, 15 Apr 2026 09:00:58 -0400 Subject: [PATCH 08/17] fixing endpoint path to match Gateway --- specs/Data-Gateway.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specs/Data-Gateway.json b/specs/Data-Gateway.json index cd54256..17679ad 100644 --- a/specs/Data-Gateway.json +++ b/specs/Data-Gateway.json @@ -11108,10 +11108,10 @@ ] } }, - "/Api/CloudMatrix/Template/List": { + "/Api/CloudMatrix/TemplateMetadata/List": { "get": { "description": "Get a list of all available templates from CM storage. \n\nThis endpoint requires the `CloudMatrix.Read`, `CloudMatrix.Read.Del`, `CloudMatrix.Read.All`, `CloudMatrix.ReadWrite`, or `CloudMatrix.ReadWrite.All` scope (permission).", - "operationId": "/Api/CloudMatrix/Template/List/Get", + "operationId": "/Api/CloudMatrix/TemplateMetadata/List/Get", "responses": { "200": { "description": "List of TemplateFileMetadata objects.", From f48404a19f6e18f693b777896ae74e1084cd4549 Mon Sep 17 00:00:00 2001 From: JD-ghforme Date: Wed, 15 Apr 2026 10:55:24 -0400 Subject: [PATCH 09/17] update to match Gateway changes to endpoint --- specs/Data-Gateway.json | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/specs/Data-Gateway.json b/specs/Data-Gateway.json index 985fc19..818a93f 100644 --- a/specs/Data-Gateway.json +++ b/specs/Data-Gateway.json @@ -4724,6 +4724,35 @@ "Microsoft_Academic", "Google-Workspace" ] + }, + "CloudMatrix.TemplateMetadata": { + "title": "Cloud Matrix Template File Metadata", + "type": "object", + "description": "Information about Cloud Matrix template files.", + "properties": { + "createdOn": { + "$ref": "#/components/schemas/DateTimeStringType", + "description": "Creation date of the template file.", + }, + "name": { + "type": "string", + "description": "Name of available template.", + "examples": [ + "cloud-matrix" + ] + }, + "lastModified": { + "$ref": "#/components/schemas/DateTimeStringType", + "description": "Last modified date of the template file.", + }, + "type": { + "type": "string", + "description": "Type of the template.", + "examples": [ + "Microsoft Cloud Adoption Matrix Template" + ] + } + } } }, "securitySchemes": { From b95f99dd5a183b338902f018f4a2830e99b0555d Mon Sep 17 00:00:00 2001 From: JD-ghforme Date: Wed, 15 Apr 2026 12:00:31 -0400 Subject: [PATCH 10/17] cleanup --- specs/Data-Gateway.json | 31 +++++++++++++++++++++++-------- 1 file changed, 23 insertions(+), 8 deletions(-) diff --git a/specs/Data-Gateway.json b/specs/Data-Gateway.json index 818a93f..19cba05 100644 --- a/specs/Data-Gateway.json +++ b/specs/Data-Gateway.json @@ -4732,18 +4732,15 @@ "properties": { "createdOn": { "$ref": "#/components/schemas/DateTimeStringType", - "description": "Creation date of the template file.", + "description": "Creation date of the template file." }, "name": { - "type": "string", - "description": "Name of available template.", - "examples": [ - "cloud-matrix" - ] + "$ref": "#/components/schemas/CloudMatrix.TemplateName", + "description": "Name of available template." }, "lastModified": { "$ref": "#/components/schemas/DateTimeStringType", - "description": "Last modified date of the template file.", + "description": "Last modified date of the template file." }, "type": { "type": "string", @@ -4752,7 +4749,25 @@ "Microsoft Cloud Adoption Matrix Template" ] } - } + }, + "required": [ + "name", + "type" + ], + "examples": [ + { + "createdOn": "2025-12-15T21:13:12.821Z", + "name": "Microsoft Enterprise", + "lastModified": "2025-12-15T21:13:12.821Z", + "type": "Microsoft Cloud Adoption Matrix Template" + }, + { + "createdOn": "2025-12-15T21:13:12.821Z", + "name": "Google-Workspace", + "lastModified": "2025-12-15T21:13:12.821Z", + "type": "Microsoft Cloud Adoption Matrix Template" + } + ] } }, "securitySchemes": { From edf39845fdbd6e7da87d0eb2606880caacf5d43f Mon Sep 17 00:00:00 2001 From: JD-ghforme Date: Wed, 15 Apr 2026 12:10:09 -0400 Subject: [PATCH 11/17] fixing copilot suggestions --- specs/Data-Gateway.json | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/specs/Data-Gateway.json b/specs/Data-Gateway.json index 19cba05..0c591f4 100644 --- a/specs/Data-Gateway.json +++ b/specs/Data-Gateway.json @@ -11159,7 +11159,11 @@ } }, "schema": { - "$ref": "#/components/schemas/CloudMatrix.TemplateMetadata" + "type": "array", + "minItems": 0, + "items": { + "$ref": "#/components/schemas/CloudMatrix.TemplateMetadata" + } } } } From 1be02f5d002b14869a090084bd6f46eb8c58f615 Mon Sep 17 00:00:00 2001 From: Jagdish Khunti <66874579+JagdishKhunti@users.noreply.github.com> Date: Thu, 16 Apr 2026 10:29:44 +0100 Subject: [PATCH 12/17] Clarify templateName encoding and scopes Document that templateName is sent as a path segment and must be URL-encoded (update parameter description and example to use "Microsoft%20Enterprise"). Also tighten the documented required permission for template-related endpoints to only `CloudMatrix.Read` for /Api/CloudMatrix/Template/{templateName} and /Api/CloudMatrix/TemplateMetadata/List. --- specs/Data-Gateway.json | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/specs/Data-Gateway.json b/specs/Data-Gateway.json index 0c591f4..ffb27d7 100644 --- a/specs/Data-Gateway.json +++ b/specs/Data-Gateway.json @@ -166,7 +166,7 @@ } }, "templateName": { - "description": "Name of the Cloud Matrix template to retrieve.", + "description": "Name of the Cloud Matrix template to retrieve. Because this value is sent as a path segment, clients must URL-encode spaces and other reserved characters.", "in": "path", "name": "templateName", "required": true, @@ -175,9 +175,9 @@ }, "examples": { "Valid Template Name": { - "summary": "Example Valid Template Name", - "description": "An example string of a valid template name.", - "value": "Microsoft Enterprise" + "summary": "Example URL-Encoded Template Name", + "description": "An example of a valid template name as it appears in the request path after URL encoding.", + "value": "Microsoft%20Enterprise" } } } @@ -9140,7 +9140,7 @@ }, "/Api/CloudMatrix/Template/{templateName}": { "get": { - "description": "Retrieves the specified Cloud Matrix assessment template by template name. \n\nThis endpoint requires the `CloudMatrix.Read`, `CloudMatrix.Read.Del`, `CloudMatrix.Read.All`, `CloudMatrix.ReadWrite`, or `CloudMatrix.ReadWrite.All` scope (permission).", + "description": "Retrieves the specified Cloud Matrix assessment template by template name. \n\nThis endpoint requires the `CloudMatrix.Read` scope (permission).", "operationId": "/Api/CloudMatrix/Template/:templateName/Get", "parameters": [ { @@ -11131,7 +11131,7 @@ }, "/Api/CloudMatrix/TemplateMetadata/List": { "get": { - "description": "Get a list of all available templates from CM storage. \n\nThis endpoint requires the `CloudMatrix.Read`, `CloudMatrix.Read.Del`, `CloudMatrix.Read.All`, `CloudMatrix.ReadWrite`, or `CloudMatrix.ReadWrite.All` scope (permission).", + "description": "Get a list of all available templates from CM storage. \n\nThis endpoint requires the `CloudMatrix.Read` scope (permission).", "operationId": "/Api/CloudMatrix/TemplateMetadata/List/Get", "responses": { "200": { From 19c28ecea6e2f474927c437c1097d4d9e2c89a55 Mon Sep 17 00:00:00 2001 From: JD-ghforme Date: Thu, 16 Apr 2026 13:11:55 -0400 Subject: [PATCH 13/17] fix TemplateMetadata endpoint name --- specs/Data-Gateway.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specs/Data-Gateway.json b/specs/Data-Gateway.json index ffb27d7..71fd41b 100644 --- a/specs/Data-Gateway.json +++ b/specs/Data-Gateway.json @@ -11129,10 +11129,10 @@ ] } }, - "/Api/CloudMatrix/TemplateMetadata/List": { + "/Api/CloudMatrix/TemplateMetadata": { "get": { "description": "Get a list of all available templates from CM storage. \n\nThis endpoint requires the `CloudMatrix.Read` scope (permission).", - "operationId": "/Api/CloudMatrix/TemplateMetadata/List/Get", + "operationId": "/Api/CloudMatrix/TemplateMetadata/Get", "responses": { "200": { "description": "List of TemplateFileMetadata objects.", From 32bfc8ca8953d64afafd1d80a92dcbb714ab4abe Mon Sep 17 00:00:00 2001 From: JD-ghforme Date: Fri, 17 Apr 2026 08:15:06 -0400 Subject: [PATCH 14/17] fixes review comments --- specs/Data-Gateway.json | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/specs/Data-Gateway.json b/specs/Data-Gateway.json index 71fd41b..7faa546 100644 --- a/specs/Data-Gateway.json +++ b/specs/Data-Gateway.json @@ -4751,7 +4751,9 @@ } }, "required": [ + "createdOn", "name", + "lastModified", "type" ], "examples": [ @@ -11131,7 +11133,7 @@ }, "/Api/CloudMatrix/TemplateMetadata": { "get": { - "description": "Get a list of all available templates from CM storage. \n\nThis endpoint requires the `CloudMatrix.Read` scope (permission).", + "description": "Get a list of all template metadata objects for available templates from CM storage. \n\nThis endpoint requires the `CloudMatrix.Read` scope (permission).", "operationId": "/Api/CloudMatrix/TemplateMetadata/Get", "responses": { "200": { @@ -11147,13 +11149,13 @@ "createdOn": "2026-03-24T16:56:43.000Z", "name": "cloudMatrix", "lastModified": "2026-03-24T16:56:43.000Z", - "type": "Standard" + "type": "Microsoft Cloud Adoption Matrix Template" }, { "createdOn": "2026-04-08T14:15:44.000Z", "name": "Google", "lastModified": "2026-04-08T14:15:44.000Z", - "type": "Premium" + "type": "Microsoft Cloud Adoption Matrix Template" } ] } @@ -11175,7 +11177,7 @@ "tags": [ "Cloud Matrix" ], - "summary": "Get a list of all available CM template objects" + "summary": "Get a List of Template Metadata Objects" } } }, From cecbd735dd54bff46cd45d32e4ee5d169608e3e5 Mon Sep 17 00:00:00 2001 From: JD-ghforme Date: Fri, 17 Apr 2026 09:06:38 -0400 Subject: [PATCH 15/17] fixing copilot suggestions --- specs/Data-Gateway.json | 13 ++++++++----- src/dataGateway/TypeScript/package-lock.json | 4 ++-- 2 files changed, 10 insertions(+), 7 deletions(-) diff --git a/specs/Data-Gateway.json b/specs/Data-Gateway.json index 7faa546..3f62cbc 100644 --- a/specs/Data-Gateway.json +++ b/specs/Data-Gateway.json @@ -175,9 +175,9 @@ }, "examples": { "Valid Template Name": { - "summary": "Example URL-Encoded Template Name", - "description": "An example of a valid template name as it appears in the request path after URL encoding.", - "value": "Microsoft%20Enterprise" + "summary": "Example Valid Template Name", + "description": "An example of a valid template name before URL encoding for use in the request path.", + "value": "Microsoft Enterprise" } } } @@ -4792,7 +4792,7 @@ }, "description": "Collects data from the various SHI Lab products and makes it available in a standardized way.", "title": "SHI - Data Gateway", - "version": "3.2.0" + "version": "3.2.1" }, "openapi": "3.1.1", "paths": { @@ -9338,6 +9338,9 @@ } } }, + "400": { + "$ref": "#/components/responses/400" + }, "500": { "$ref": "#/components/responses/500" } @@ -11137,7 +11140,7 @@ "operationId": "/Api/CloudMatrix/TemplateMetadata/Get", "responses": { "200": { - "description": "List of TemplateFileMetadata objects.", + "description": "List of CloudMatrix TemplateMetadata objects.", "content": { "application/json": { "examples": { diff --git a/src/dataGateway/TypeScript/package-lock.json b/src/dataGateway/TypeScript/package-lock.json index 44787de..cd0e129 100644 --- a/src/dataGateway/TypeScript/package-lock.json +++ b/src/dataGateway/TypeScript/package-lock.json @@ -1,12 +1,12 @@ { "name": "@shi-corp/sdk-data-gateway", - "version": "3.2.0", + "version": "3.2.1", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@shi-corp/sdk-data-gateway", - "version": "3.2.0", + "version": "3.2.1", "license": "MIT", "dependencies": { "@microsoft/kiota-authentication-azure": "~1.0.0-preview.100", From afdb4ee7b2c9b6d4a88aefa03a4843d25108584b Mon Sep 17 00:00:00 2001 From: JD-ghforme Date: Fri, 17 Apr 2026 09:48:45 -0400 Subject: [PATCH 16/17] a few more copilot comments fixed --- 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 3f62cbc..7ac7d97 100644 --- a/specs/Data-Gateway.json +++ b/specs/Data-Gateway.json @@ -4525,8 +4525,8 @@ ] }, "CloudMatrix.TemplateUploadRequest": { - "title": "Value Assessment Template Upload Request", - "description": "Request body for uploading a value assessment template to the data gateway.", + "title": "Cloud Matrix Template Upload Request", + "description": "Request body for uploading a Cloud Matrix template to the data gateway.", "type": "object", "properties": { "templateName": { @@ -9348,7 +9348,7 @@ "tags": [ "Cloud Matrix" ], - "summary": "Get a Specific Assessment Template Schema Object" + "summary": "Get a Specific Cloud Matrix Assessment Template" } }, "/Api/CloudMatrix/Template": { From d2002800c175d9fae4a176d1588b1d228ca90f21 Mon Sep 17 00:00:00 2001 From: JD-ghforme Date: Fri, 17 Apr 2026 09:57:23 -0400 Subject: [PATCH 17/17] another CP change --- specs/Data-Gateway.json | 3 +++ 1 file changed, 3 insertions(+) diff --git a/specs/Data-Gateway.json b/specs/Data-Gateway.json index 7ac7d97..9fbc553 100644 --- a/specs/Data-Gateway.json +++ b/specs/Data-Gateway.json @@ -11173,6 +11173,9 @@ } } }, + "400": { + "$ref": "#/components/responses/400" + }, "500": { "$ref": "#/components/responses/500" }