diff --git a/specs/Data-Gateway.json b/specs/Data-Gateway.json index aa6ef54..b76f6ee 100644 --- a/specs/Data-Gateway.json +++ b/specs/Data-Gateway.json @@ -437,77 +437,7 @@ "title": "Report - Feature Breakdown", "type": "object" }, - "LicenseReport.CorrelationRecord": { - "description": "Metadata that describes the execution session (run) that is used to tie/relate all of the license report together.", - "examples": [ - { - "auditTenantAccount": "priv-user@example.com", - "correlationId": "9d838115-0868-45d4-b8a5-98adc1af7e42", - "reportTenantAccount": "ent-user@example.com", - "tenantId": "7e536189-b2dd-4c8b-98b1-9b174777883f", - "createdAt": "2024-08-01T21:13:12.821Z", - "updatedAt": "2024-08-01T21:13:12.821Z" - } - ], - "properties": { - "auditTenantAccount": { - "description": "The user account used to retrieve the license information in the tenant being audited.", - "examples": [ - "admin-user@example.com" - ], - "format": "email", - "type": "string" - }, - "correlationId": { - "description": "The ID of the execution session (run) that is used to tie/relate all of the data together.", - "examples": [ - "88da2253-758f-4135-9d37-64448c8b65c1" - ], - "format": "uuid", - "type": "string", - "pattern": "^\\w+-\\w+-\\w+-\\w+-\\w+$" - }, - "reportTenantAccount": { - "description": "User account used to store/report the license report to the SHI Lab cloud service.", - "examples": [ - "generic-user@example.com" - ], - "format": "email", - "type": "string" - }, - "tenantId": { - "description": "Unique ID of customer's Microsoft tenant that the license report is for.", - "examples": [ - "0e1fe83f-a33f-4250-8546-225b8d45ae01" - ], - "format": "uuid", - "type": "string", - "pattern": "^\\w+-\\w+-\\w+-\\w+-\\w+$" - }, - "createdAt": { - "description": "Timestamp of when the report was created.", - "examples": [ - "2024-08-01T21:12:22.148Z" - ], - "format": "date-time", - "type": "string" - }, - "updatedAt": { - "description": "Timestamp of when the report was last updated.", - "examples": [ - "2024-08-01T21:12:22.148Z" - ], - "format": "date-time", - "type": "string" - } - }, - "required": [ - "auditTenantAccount" - ], - "title": "License Report - Correlation Record", - "type": "object" - }, - "LicenseReport.LicenseData": { + "LicenseReportV0.LicenseData": { "type": "object", "properties": { "assignedLicense": { @@ -657,7 +587,7 @@ ], "title": "License Report - License Data" }, - "LicenseReport": { + "LicenseReportV0": { "description": "Completely calculated license report structure that is the result of a complete run.", "examples": [ { @@ -712,11 +642,11 @@ "type": "object" }, "correlation": { - "$ref": "#/components/schemas/LicenseReport.CorrelationRecord" + "$ref": "#/components/schemas/Report.CorrelationRecordV0" }, "licenseData": { "additionalProperties": { - "$ref": "#/components/schemas/LicenseReport.LicenseData" + "$ref": "#/components/schemas/LicenseReportV0.LicenseData" } } }, @@ -923,6 +853,76 @@ ], "title": "License Report V1 - Complete Object" }, + "Report.CorrelationRecordV0": { + "description": "Metadata that describes the execution session (run) that is used to tie/relate report versions together.", + "examples": [ + { + "auditTenantAccount": "priv-user@example.com", + "correlationId": "9d838115-0868-45d4-b8a5-98adc1af7e42", + "reportTenantAccount": "ent-user@example.com", + "tenantId": "7e536189-b2dd-4c8b-98b1-9b174777883f", + "createdAt": "2024-08-01T21:13:12.821Z", + "updatedAt": "2024-08-01T21:13:12.821Z" + } + ], + "properties": { + "auditTenantAccount": { + "description": "The user account used to retrieve the information in the tenant being audited.", + "examples": [ + "admin-user@example.com" + ], + "format": "email", + "type": "string" + }, + "correlationId": { + "description": "The ID of the execution session (run) that is used to tie/relate all of the data together.", + "examples": [ + "88da2253-758f-4135-9d37-64448c8b65c1" + ], + "format": "uuid", + "type": "string", + "pattern": "^\\w+-\\w+-\\w+-\\w+-\\w+$" + }, + "reportTenantAccount": { + "description": "User account used to store/report the report to the SHI Lab cloud service.", + "examples": [ + "generic-user@example.com" + ], + "format": "email", + "type": "string" + }, + "tenantId": { + "description": "Unique ID of customer's Microsoft tenant that the report is auditing.", + "examples": [ + "0e1fe83f-a33f-4250-8546-225b8d45ae01" + ], + "format": "uuid", + "type": "string", + "pattern": "^\\w+-\\w+-\\w+-\\w+-\\w+$" + }, + "createdAt": { + "description": "Timestamp of when the report was created.", + "examples": [ + "2024-08-01T21:12:22.148Z" + ], + "format": "date-time", + "type": "string" + }, + "updatedAt": { + "description": "Timestamp of when the report was last updated.", + "examples": [ + "2024-08-01T21:12:22.148Z" + ], + "format": "date-time", + "type": "string" + } + }, + "required": [ + "auditTenantAccount" + ], + "title": "License Report - Correlation Record", + "type": "object" + }, "Report.CorrelationRecordV1": { "description": "Metadata that describes the execution session (run) that is used to tie/relate report versions together.", "examples": [ @@ -1009,14 +1009,13 @@ } }, "required": [ - "auditTenantAccount", - "reportTenantAccount" + "auditTenantAccount" ], "title": "Report - Correlation Record V1", "type": "object" }, "Report.PrincipalData": { - "description": "Contains user and device records included in the license report, detailing assigned services, licenses, consumed services, and related metadata for each principal. ", + "description": "Contains user and device records included in the report, detailing assigned services, licenses, consumed services, and related metadata for each principal.", "type": "object", "required": [ "device", @@ -2227,112 +2226,282 @@ ] } ] - } - }, - "securitySchemes": { - "EntraID": { - "type": "http", - "scheme": "bearer", - "bearerFormat": "JWT", - "description": "The Access Token from Entra ID. Please note required scopes (permissions) in each endpoint." - } - } - }, - "externalDocs": { - "description": "Official Documentation", - "url": "https://docs.shilab.com" - }, - "info": { - "contact": { - "email": "elliot_huffman@shi.com", - "name": "SHI - Lab" - }, - "description": "Collects data from the various SHI Lab products and makes it available in a standardized way.", - "title": "SHI Data Gateway", - "version": "2.3.1" - }, - "openapi": "3.1.1", - "paths": { - "/Api/Core/Health": { - "get": { - "description": "Check the health of the various components of the data gateway and report back. Useful for automated health probing.", - "operationId": "/Api/ServiceHealth/Get", - "responses": { - "201": { - "description": "Service is operational!" + }, + "ArchitectureReportV1": { + "description": "Completely calculated architecture report structure that is the result of a complete run.", + "type": "object", + "properties": { + "correlation": { + "$ref": "#/components/schemas/Report.CorrelationRecordV1" }, - "500": { - "description": "Service has a failure described with following report.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/Core.HealthReport" - }, - "examples": { - "Auth system failure": { - "summary": "Example health report - Auth failure", - "description": "An example health report returned indicates the authentication components are not working.", - "value": { - "authClient": false, - "authServer": false, - "bulkStorage": true, - "database": true - } - }, - "Storage system failure": { - "summary": "Example health report - Storage failure", - "description": "An example health report returned indicates the storage components are not working.", - "value": { - "authClient": true, - "authServer": true, - "bulkStorage": false, - "database": false - } - } - } - } - } + "principalData": { + "$ref": "#/components/schemas/ArchitectureReport.PrincipalData" + }, + "tenantMetadata": { + "$ref": "#/components/schemas/ArchitectureReportV1.TenantMetadata" + }, + "schemaVersion": { + "type": "integer", + "format": "int32", + "description": "Version number of the license report schema.", + "examples": [ + 1 + ] } }, - "tags": [ - "Core System" + "required": [ + "correlation", + "tenantMetadata", + "principalData", + "schemaVersion" ], - "security": [], - "summary": "Health of the Service for Probing" - } - }, - "/Api/LicenseReport": { - "post": { - "description": "Store the results of a license analytics run.\n\nThis endpoint requires the `LicenseReport.ReadWrite`, or `LicenseReport.ReadWrite.All` scope (permission).", - "operationId": "/Api/LicenseReport/Post", - "requestBody": { - "content": { - "application/json": { - "examples": { - "License Report": { - "description": "Sample, truncated report from an example customer environment. The request body is the License Report that to be stored.", - "summary": "Example License Report Request", - "value": { - "availableLicense": { - "3d282045-ec7f-4813-88e2-29b74ee609f7": 123456, - "5888a922-9f5b-45fd-bd5f-de3283d6a79e": 99999999, - "a4b2e176-d63d-4081-9e21-226e2ac624b9": 5, - "547404d4-8734-415f-a7ca-e9c1ffb95e48": 25, - "d76878d6-1495-4243-a334-a82bb9818cd0": 500 - }, - "correlation": { - "auditTenantAccount": "somebodyThatI@UsedToKnow.com" - }, - "licenseData": { - "250844e1-a7ab-4f21-8e3f-58f51b5983a3": { - "assignedLicense": { - "5888a922-9f5b-45fd-bd5f-de3283d6a79e": null, - "3d282045-ec7f-4813-88e2-29b74ee609f7": null - }, - "assignedService": { - "a4b2e176-d63d-4081-9e21-226e2ac624b9": null, - "d76878d6-1495-4243-a334-a82bb9818cd0": null - }, + "examples": [ + { + "correlation": { + "auditTenantAccount": "user@example.com", + "correlationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "createdAt": "2023-11-19T10:00:00.000Z", + "isMigrating": false, + "reportTenantAccount": "user@example.com", + "schemaVersion": 1, + "tenantId": "123e4567-e89b-12d3-a456-426614174000", + "updatedAt": "2023-11-19T10:05:00.000Z" + }, + "principalData": { + "user": { + "e7b8c8a2-1f2e-4c3a-9b6a-2d8e4f8a9b7c": { + "assignedService": { + "3d282045-ec7f-4813-88e2-29b74ee609f7": { + "featureA": true, + "featureB": false + } + }, + "assignedLicense": [ + { + "id": "3d282045-ec7f-4813-88e2-29b74ee609f7", + "servicePlanList": [ + "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + ] + } + ], + "consumedService": { + "3d282045-ec7f-4813-88e2-29b74ee609f7": { + "featureA": true, + "featureB": false + } + }, + "llmInferred": { + "isServiceAccount": false, + "isFrontlineWorker": true, + "isTempWorker": null + }, + "principalMetadata": { + "sharedMailbox": false + }, + "enhancedData": { + "userPrincipalName": "user@example.com", + "idpJobTitle": "Engineer", + "idpDepartment": "IT", + "idpOfficeLocation": "HQ", + "idpEmployeeType": "Full-Time" + } + } + }, + "device": { + "f1e2d3c4-b5a6-7890-1234-56789abcdef0": { + "assignedService": { + "3d282045-ec7f-4813-88e2-29b74ee609f7": 5 + }, + "assignedLicense": [ + { + "id": "3d282045-ec7f-4813-88e2-29b74ee609f7", + "servicePlanList": [ + "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + ] + } + ], + "consumedService": { + "3d282045-ec7f-4813-88e2-29b74ee609f7": 5 + }, + "principalMetadata": { + "sharedComputer": true + } + } + } + }, + "tenantMetadata": { + "totalDeviceCount": 1, + "totalGuestCount": 1, + "totalMemberCount": 1, + "totalUserCount": 1 + }, + "schemaVersion": 1 + } + ], + "title": "Architecture Report V1 - Complete Object" + }, + "ArchitectureReportV1.TenantMetadata": { + "description": "This is the the tenant data calculated for the architecture report", + "examples": [ + { + "totalDeviceCount": 1, + "totalGuestCount": 1, + "totalMemberCount": 1, + "totalUserCount": 1 + } + ], + "properties": { + "totalDeviceCount": { + "description": "The count of total devices within the tenant", + "examples": [ + 1 + ], + "format": "int32", + "type": "integer" + }, + "totalGuestCount": { + "description": "The count of total guests within the tenant", + "examples": [ + 1 + ], + "format": "int32", + "type": "integer" + }, + "totalMemberCount": { + "description": "The count of total members within the tenant", + "examples": [ + 1 + ], + "format": "int32", + "type": "integer" + }, + "totalUserCount": { + "description": "The count of total users within the tenant", + "examples": [ + 1 + ], + "format": "int32", + "type": "integer" + } + }, + "required": [ + "totalDeviceCount", + "totalGuestCount", + "totalMemberCount", + "totalUserCount" + ], + "title": "Architecture Report V1 - Tenant Metadata" + }, + "ArchitectureReport.PrincipalData": { + "description": "Contains user and device records included in the architecture report, detailing assigned services, licenses, consumed services, and related metadata for each principal.", + "$ref": "#/components/schemas/Report.PrincipalData", + "title": "Architecture Report - Principal Data" + } + }, + "securitySchemes": { + "EntraID": { + "type": "http", + "scheme": "bearer", + "bearerFormat": "JWT", + "description": "The Access Token from Entra ID. Please note required scopes (permissions) in each endpoint." + } + } + }, + "externalDocs": { + "description": "Official Documentation", + "url": "https://docs.shilab.com" + }, + "info": { + "contact": { + "email": "elliot_huffman@shi.com", + "name": "SHI - Lab" + }, + "description": "Collects data from the various SHI Lab products and makes it available in a standardized way.", + "title": "SHI Data Gateway", + "version": "2.3.1" + }, + "openapi": "3.1.1", + "paths": { + "/Api/Core/Health": { + "get": { + "description": "Check the health of the various components of the data gateway and report back. Useful for automated health probing.", + "operationId": "/Api/ServiceHealth/Get", + "responses": { + "201": { + "description": "Service is operational!" + }, + "500": { + "description": "Service has a failure described with following report.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/Core.HealthReport" + }, + "examples": { + "Auth system failure": { + "summary": "Example health report - Auth failure", + "description": "An example health report returned indicates the authentication components are not working.", + "value": { + "authClient": false, + "authServer": false, + "bulkStorage": true, + "database": true + } + }, + "Storage system failure": { + "summary": "Example health report - Storage failure", + "description": "An example health report returned indicates the storage components are not working.", + "value": { + "authClient": true, + "authServer": true, + "bulkStorage": false, + "database": false + } + } + } + } + } + } + }, + "tags": [ + "Core System" + ], + "security": [], + "summary": "Health of the Service for Probing" + } + }, + "/Api/LicenseReport": { + "post": { + "description": "Store the results of a license analytics run.\n\nThis endpoint requires the `LicenseReport.ReadWrite`, or `LicenseReport.ReadWrite.All` scope (permission).", + "operationId": "/Api/LicenseReport/Post", + "requestBody": { + "content": { + "application/json": { + "examples": { + "License Report": { + "description": "Sample, truncated report from an example customer environment. The request body is the License Report that to be stored.", + "summary": "Example License Report Request", + "value": { + "availableLicense": { + "3d282045-ec7f-4813-88e2-29b74ee609f7": 123456, + "5888a922-9f5b-45fd-bd5f-de3283d6a79e": 99999999, + "a4b2e176-d63d-4081-9e21-226e2ac624b9": 5, + "547404d4-8734-415f-a7ca-e9c1ffb95e48": 25, + "d76878d6-1495-4243-a334-a82bb9818cd0": 500 + }, + "correlation": { + "auditTenantAccount": "somebodyThatI@UsedToKnow.com" + }, + "licenseData": { + "250844e1-a7ab-4f21-8e3f-58f51b5983a3": { + "assignedLicense": { + "5888a922-9f5b-45fd-bd5f-de3283d6a79e": null, + "3d282045-ec7f-4813-88e2-29b74ee609f7": null + }, + "assignedService": { + "a4b2e176-d63d-4081-9e21-226e2ac624b9": null, + "d76878d6-1495-4243-a334-a82bb9818cd0": null + }, "consumedService": { "e0d101e8-6f1e-40a9-a66f-cad4112c9a59": null, "c63b7a2d-6573-4c37-9ca8-e12b954d3198": { @@ -2367,7 +2536,7 @@ } }, "schema": { - "$ref": "#/components/schemas/LicenseReport" + "$ref": "#/components/schemas/LicenseReportV0" } } } @@ -2433,7 +2602,7 @@ } }, "schema": { - "$ref": "#/components/schemas/LicenseReport" + "$ref": "#/components/schemas/LicenseReportV0" } } }, @@ -2499,7 +2668,7 @@ "type": "array", "minItems": 0, "items": { - "$ref": "#/components/schemas/LicenseReport.CorrelationRecord" + "$ref": "#/components/schemas/Report.CorrelationRecordV0" }, "examples": [ [ @@ -2586,7 +2755,7 @@ "type": "array", "minItems": 0, "items": { - "$ref": "#/components/schemas/LicenseReport.CorrelationRecord" + "$ref": "#/components/schemas/Report.CorrelationRecordV0" }, "examples": [ [ @@ -2699,7 +2868,7 @@ } }, "schema": { - "$ref": "#/components/schemas/LicenseReport" + "$ref": "#/components/schemas/LicenseReportV0" } } }, @@ -2821,7 +2990,7 @@ } }, "schema": { - "$ref": "#/components/schemas/LicenseReport" + "$ref": "#/components/schemas/LicenseReportV0" } } }, @@ -2896,8 +3065,7 @@ } ], "correlation": { - "auditTenantAccount": "user@example.com", - "reportTenantAccount": "user@example.com" + "auditTenantAccount": "user@example.com" }, "principalData": { "user": { @@ -2977,7 +3145,7 @@ } }, "responses": { - "201": { + "200": { "content": { "application/json": { "examples": { @@ -3446,9 +3614,6 @@ "201": { "description": "Deleted successfully" }, - "204": { - "description": "Deleted successfully" - }, "400": { "$ref": "#/components/responses/400" }, @@ -3618,9 +3783,6 @@ "201": { "description": "Deleted successfully" }, - "204": { - "description": "Deleted successfully" - }, "400": { "$ref": "#/components/responses/400" }, @@ -5996,36 +6158,718 @@ "Tenant Records" ] } - } - }, - "security": [ - { - "EntraID": [] - } - ], - "servers": [ - { - "description": "Server the hosts the API described in the document.", - "url": "https://api.shilab.com" - } - ], - "tags": [ - { - "description": "Routes for the core data gateway system.", - "name": "Core System", - "externalDocs": { - "description": "Data Gateway Documentation", - "url": "https://docs.shilab.com/Date-Gateway/" - } }, - { - "description": "Manages the list of tenants that have interacted with the Data Gateway in the past.", - "name": "Tenant Records" - }, - { - "description": "Collects and reports data from the license analytics product.", - "name": "License Analytics", - "externalDocs": { + "/Api/V1/ArchitectureReport": { + "post": { + "description": "Stores the results of an Architecture report.\n\nThis endpoint requires the `ArchitectureReport.ReadWrite`, `ArchitectureReport.ReadWrite.All` scope (permission).", + "operationId": "/Api/V1/ArchitectureReport/Post", + "requestBody": { + "required": true, + "content": { + "application/json": { + "examples": { + "Architecture Report V1": { + "description": "Sample, truncated report from an example customer environment. This will return the same report as the request input.", + "summary": "Example of license report stored.", + "value": { + "correlation": { + "auditTenantAccount": "user@example.com" + }, + "principalData": { + "user": { + "e7b8c8a2-1f2e-4c3a-9b6a-2d8e4f8a9b7c": { + "assignedService": { + "3d282045-ec7f-4813-88e2-29b74ee609f7": { + "featureA": true, + "featureB": false + } + }, + "assignedLicense": [ + { + "id": "3d282045-ec7f-4813-88e2-29b74ee609f7", + "servicePlanList": [ + "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + ] + } + ], + "consumedService": { + "3d282045-ec7f-4813-88e2-29b74ee609f7": { + "featureA": true, + "featureB": false + } + }, + "llmInferred": { + "isServiceAccount": false, + "isFrontlineWorker": true, + "isTempWorker": null + }, + "principalMetadata": { + "sharedMailbox": false + }, + "enhancedData": { + "userPrincipalName": "user@example.com", + "idpJobTitle": "Engineer", + "idpDepartment": "IT", + "idpOfficeLocation": "HQ", + "idpEmployeeType": "Full-Time" + } + } + }, + "device": { + "f1e2d3c4-b5a6-7890-1234-56789abcdef0": { + "assignedService": { + "3d282045-ec7f-4813-88e2-29b74ee609f7": 5 + }, + "assignedLicense": [ + { + "id": "3d282045-ec7f-4813-88e2-29b74ee609f7", + "servicePlanList": [ + "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + ] + } + ], + "consumedService": { + "3d282045-ec7f-4813-88e2-29b74ee609f7": 5 + }, + "principalMetadata": { + "sharedComputer": true + } + } + } + }, + "tenantMetadata": { + "totalDeviceCount": 1, + "totalGuestCount": 1, + "totalMemberCount": 1, + "totalUserCount": 1 + }, + "schemaVersion": 1 + } + } + }, + "schema": { + "$ref": "#/components/schemas/ArchitectureReportV1" + } + } + } + }, + "responses": { + "200": { + "description": "Architecture Report V1 submitted successfully.", + "content": { + "application/json": { + "examples": { + "Architecture Report V1": { + "description": "Sample, truncated report from an example customer environment. This will return the same report as the request input.", + "summary": "Example of license report stored.", + "value": { + "correlation": { + "auditTenantAccount": "user@example.com", + "correlationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "createdAt": "2023-11-19T10:00:00.000Z", + "isMigrating": false, + "reportTenantAccount": "user@example.com", + "schemaVersion": 1, + "tenantId": "123e4567-e89b-12d3-a456-426614174000", + "updatedAt": "2023-11-19T10:05:00.000Z" + }, + "principalData": { + "user": { + "e7b8c8a2-1f2e-4c3a-9b6a-2d8e4f8a9b7c": { + "assignedService": { + "3d282045-ec7f-4813-88e2-29b74ee609f7": { + "featureA": true, + "featureB": false + } + }, + "assignedLicense": [ + { + "id": "3d282045-ec7f-4813-88e2-29b74ee609f7", + "servicePlanList": [ + "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + ] + } + ], + "consumedService": { + "3d282045-ec7f-4813-88e2-29b74ee609f7": { + "featureA": true, + "featureB": false + } + }, + "llmInferred": { + "isServiceAccount": false, + "isFrontlineWorker": true, + "isTempWorker": null + }, + "principalMetadata": { + "sharedMailbox": false + }, + "enhancedData": { + "userPrincipalName": "user@example.com", + "idpJobTitle": "Engineer", + "idpDepartment": "IT", + "idpOfficeLocation": "HQ", + "idpEmployeeType": "Full-Time" + } + } + }, + "device": { + "f1e2d3c4-b5a6-7890-1234-56789abcdef0": { + "assignedService": { + "3d282045-ec7f-4813-88e2-29b74ee609f7": 5 + }, + "assignedLicense": [ + { + "id": "3d282045-ec7f-4813-88e2-29b74ee609f7", + "servicePlanList": [ + "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + ] + } + ], + "consumedService": { + "3d282045-ec7f-4813-88e2-29b74ee609f7": 5 + }, + "principalMetadata": { + "sharedComputer": true + } + } + } + }, + "tenantMetadata": { + "totalDeviceCount": 1, + "totalGuestCount": 1, + "totalMemberCount": 1, + "totalUserCount": 1 + }, + "schemaVersion": 1 + } + } + }, + "schema": { + "$ref": "#/components/schemas/ArchitectureReportV1" + } + } + } + }, + "400": { + "$ref": "#/components/responses/400" + }, + "500": { + "$ref": "#/components/responses/500" + } + }, + "tags": [ + "Architecture Reporting" + ], + "summary": "Submit Architecture Report V1" + } + }, + "/Api/V1/ArchitectureReport/Correlation": { + "get": { + "description": "Retrieves the list of correlation records for the authenticated tenant. Can use filters targeting creation date to limit results. Correlation records store the metadata for a specific architecture report.\n\nThis endpoint requires the `ArchitectureReport.Read`, `ArchitectureReport.Read.All`, `ArchitectureReport.ReadWrite`, or `ArchitectureReport.ReadWrite.All` scope (permission).", + "operationId": "/Api/V1/ArchitectureReport/Correlation/Get", + "parameters": [ + { + "$ref": "#/components/parameters/dateStart" + }, + { + "$ref": "#/components/parameters/dateEnd" + } + ], + "responses": { + "200": { + "description": "A list of correlation records.", + "content": { + "application/json": { + "examples": { + "Example Correlation Records": { + "description": "Sample list of correlation records for the current authenticated tenant.", + "summary": "Available Correlation Records", + "value": [ + { + "auditTenantAccount": "user@example.com", + "correlationId": "3d282045-ec7f-4813-88e2-29b74ee609f7", + "createdAt": "2023-11-19T10:00:00.000Z", + "isMigrating": false, + "reportTenantAccount": "user@example.com", + "schemaVersion": 1, + "tenantId": "123e4567-e89b-12d3-a456-426614174000", + "updatedAt": "2023-11-19T10:05:00.000Z" + }, + { + "auditTenantAccount": "user@example.com", + "correlationId": "5888a922-9f5b-45fd-bd5f-de3283d6a79e", + "createdAt": "2023-12-19T10:00:00.000Z", + "isMigrating": false, + "reportTenantAccount": "user@example.com", + "schemaVersion": 1, + "tenantId": "123e4567-e89b-12d3-a456-426614174000", + "updatedAt": "2023-11-19T10:05:00.000Z" + } + ] + } + }, + "schema": { + "examples": [ + [ + { + "auditTenantAccount": "user@example.com", + "correlationId": "3d282045-ec7f-4813-88e2-29b74ee609f7", + "createdAt": "2023-11-19T10:00:00.000Z", + "isMigrating": false, + "reportTenantAccount": "user@example.com", + "schemaVersion": 1, + "tenantId": "123e4567-e89b-12d3-a456-426614174000", + "updatedAt": "2023-11-19T10:05:00.000Z" + }, + { + "auditTenantAccount": "user@example.com", + "correlationId": "5888a922-9f5b-45fd-bd5f-de3283d6a79e", + "createdAt": "2023-12-19T10:00:00.000Z", + "isMigrating": false, + "reportTenantAccount": "user@example.com", + "schemaVersion": 1, + "tenantId": "123e4567-e89b-12d3-a456-426614174000", + "updatedAt": "2023-11-19T10:05:00.000Z" + } + ] + ], + "items": { + "$ref": "#/components/schemas/Report.CorrelationRecordV1" + }, + "minItems": 0, + "type": "array" + } + } + } + }, + "400": { + "$ref": "#/components/responses/400" + }, + "500": { + "$ref": "#/components/responses/500" + } + }, + "tags": [ + "Architecture Reporting" + ], + "summary": "Get Correlation Records" + } + }, + "/Api/V1/ArchitectureReport/Correlation/Tenant/{tenantId}": { + "get": { + "description": "Retrieves the list of correlation records for the specified tenant. Can use filters targeting creation date to limit results. Correlation records store the metadata for a specific architecture report.\n\nThis endpoint requires the `ArchitectureReport.Read.All`, or `ArchitectureReport.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI` and `SHI Lab` tenants. End user access is restricted.", + "operationId": "/Api/V1/ArchitectureReport/Correlation/Tenant/:tenantId/Get", + "parameters": [ + { + "$ref": "#/components/parameters/tenantId" + }, + { + "$ref": "#/components/parameters/dateStart" + }, + { + "$ref": "#/components/parameters/dateEnd" + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "Example Correlation Records": { + "description": "Sample list of correlation records for the specified tenant.", + "summary": "Available Correlation Records", + "value": [ + { + "auditTenantAccount": "user@example.com", + "correlationId": "3d282045-ec7f-4813-88e2-29b74ee609f7", + "createdAt": "2023-11-19T10:00:00.000Z", + "isMigrating": false, + "reportTenantAccount": "user@example.com", + "schemaVersion": 1, + "tenantId": "123e4567-e89b-12d3-a456-426614174000", + "updatedAt": "2023-11-19T10:05:00.000Z" + }, + { + "auditTenantAccount": "user@example.com", + "correlationId": "e0d101e8-6f1e-40a9-a66f-cad4112c9a59", + "createdAt": "2023-11-19T10:00:00.000Z", + "isMigrating": false, + "reportTenantAccount": "user@example.com", + "schemaVersion": 1, + "tenantId": "123e4567-e89b-12d3-a456-426614174000", + "updatedAt": "2023-11-19T10:05:00.000Z" + } + ] + } + }, + "schema": { + "type": "array", + "minItems": 0, + "items": { + "$ref": "#/components/schemas/ArchitectureReportV1.CorrelationRecord" + }, + "examples": [ + [ + { + "auditTenantAccount": "user@example.com", + "correlationId": "3d282045-ec7f-4813-88e2-29b74ee609f7", + "createdAt": "2023-11-19T10:00:00.000Z", + "isMigrating": false, + "reportTenantAccount": "user@example.com", + "schemaVersion": 1, + "tenantId": "123e4567-e89b-12d3-a456-426614174000", + "updatedAt": "2023-11-19T10:05:00.000Z" + }, + { + "auditTenantAccount": "user@example.com", + "correlationId": "e0d101e8-6f1e-40a9-a66f-cad4112c9a59", + "createdAt": "2023-11-19T10:00:00.000Z", + "isMigrating": false, + "reportTenantAccount": "user@example.com", + "schemaVersion": 1, + "tenantId": "123e4567-e89b-12d3-a456-426614174000", + "updatedAt": "2023-11-19T10:05:00.000Z" + } + ] + ] + } + } + }, + "description": "A list of correlation records for the specified tenant." + }, + "400": { + "$ref": "#/components/responses/400" + }, + "500": { + "$ref": "#/components/responses/500" + } + }, + "summary": "Get Correlation Records by Tenant", + "tags": [ + "Architecture Reporting" + ] + } + }, + "/Api/V1/ArchitectureReport/Correlation/{correlationId}/Data": { + "delete": { + "description": "Deletes the full architecture report v1 for the specified correlation ID.\n\nThis endpoint requires the `ArchitectureReport.ReadWrite`, or `ArchitectureReport.ReadWrite.All` scope (permission).", + "operationId": "/Api/V1/ArchitectureReport/Correlation/:correlationId/Data/Delete", + "parameters": [ + { + "$ref": "#/components/parameters/correlationId" + } + ], + "responses": { + "204": { + "description": "Architecture report data deleted successfully." + }, + "400": { + "$ref": "#/components/responses/400" + }, + "500": { + "$ref": "#/components/responses/500" + } + }, + "summary": "Delete Architecture Report Data by Correlation ID", + "tags": [ + "Architecture Reporting" + ] + }, + "get": { + "description": "Retrieves the full architecture report v1 for the specified correlation ID in the authenticated tenant. The architecture report v1 contains all of the tenant metadata and user/device data with the required correlation data.\n\nThis endpoint requires the `ArchitectureReport.Read`, `ArchitectureReport.Read.All`, `ArchitectureReport.ReadWrite`, or `ArchitectureReport.ReadWrite.All` scope (permission).", + "operationId": "/Api/V1/ArchitectureReport/Correlation/:correlationId/Data/Get", + "parameters": [ + { + "$ref": "#/components/parameters/correlationId" + } + ], + "responses": { + "200": { + "description": "The architecture report data for the specified correlation ID.", + "content": { + "application/json": { + "examples": { + "Example Architecture Report V1": { + "correlation": { + "auditTenantAccount": "user@example.com", + "correlationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "createdAt": "2023-11-19T10:00:00.000Z", + "isMigrating": false, + "reportTenantAccount": "user@example.com", + "schemaVersion": 1, + "tenantId": "123e4567-e89b-12d3-a456-426614174000", + "updatedAt": "2023-11-19T10:05:00.000Z" + }, + "principalData": { + "user": { + "e7b8c8a2-1f2e-4c3a-9b6a-2d8e4f8a9b7c": { + "assignedService": { + "3d282045-ec7f-4813-88e2-29b74ee609f7": { + "featureA": true, + "featureB": false + } + }, + "assignedLicense": [ + { + "id": "3d282045-ec7f-4813-88e2-29b74ee609f7", + "servicePlanList": [ + "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + ] + } + ], + "consumedService": { + "3d282045-ec7f-4813-88e2-29b74ee609f7": { + "featureA": true, + "featureB": false + } + }, + "llmInferred": { + "isServiceAccount": false, + "isFrontlineWorker": true, + "isTempWorker": null + }, + "principalMetadata": { + "sharedMailbox": false + }, + "enhancedData": { + "userPrincipalName": "user@example.com", + "idpJobTitle": "Engineer", + "idpDepartment": "IT", + "idpOfficeLocation": "HQ", + "idpEmployeeType": "Full-Time" + } + } + }, + "device": { + "f1e2d3c4-b5a6-7890-1234-56789abcdef0": { + "assignedService": { + "3d282045-ec7f-4813-88e2-29b74ee609f7": 5 + }, + "assignedLicense": [ + { + "id": "3d282045-ec7f-4813-88e2-29b74ee609f7", + "servicePlanList": [ + "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + ] + } + ], + "consumedService": { + "3d282045-ec7f-4813-88e2-29b74ee609f7": 5 + }, + "principalMetadata": { + "sharedComputer": true + } + } + } + }, + "tenantMetadata": { + "totalDeviceCount": 1, + "totalGuestCount": 1, + "totalMemberCount": 1, + "totalUserCount": 1 + }, + "schemaVersion": 1 + } + }, + "schema": { + "$ref": "#/components/schemas/ArchitectureReportV1" + } + } + } + }, + "400": { + "$ref": "#/components/responses/400" + }, + "500": { + "$ref": "#/components/responses/500" + } + }, + "summary": "Retrieve the specified Architecture Report V1 by Correlation ID", + "tags": [ + "Architecture Reporting" + ] + } + }, + "/Api/V1/ArchitectureReport/Correlation/{correlationId}/Tenant/{tenantId}/Data": { + "delete": { + "summary": "Delete the specified Architecture Report V1 for specified tenant", + "description": "Deletes the full architecture report v1 for the specified correlation ID and tenant.\n\nThis endpoint requires the `ArchitectureReport.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI` and `SHI Lab` tenants. End user access is restricted.", + "operationId": "/Api/V1/ArchitectureReport/Correlation/:correlationId/Tenant/:tenantId/Data/Delete", + "parameters": [ + { + "$ref": "#/components/parameters/correlationId", + "required": true + }, + { + "$ref": "#/components/parameters/tenantId", + "required": true + } + ], + "responses": { + "204": { + "description": "Architecture report data deleted successfully." + }, + "400": { + "$ref": "#/components/responses/400" + }, + "500": { + "$ref": "#/components/responses/500" + } + }, + "tags": [ + "Architecture Reporting" + ] + }, + "get": { + "summary": "Get Architecture Report v1 Data by Correlation ID and Tenant ID", + "description": "Retrieves the architecture report data associated with the specified correlation ID and tenant ID.\n\nThis endpoint requires the `ArchitectureReport.Read.All`, `ArchitectureReport.ReadWrite.All` scope (permission). This endpoint is also only accessible from the `SHI` and `SHI Lab` tenants. End user access is restricted.", + "operationId": "/Api/V1/ArchitectureReport/Correlation/:correlationId/Tenant/:tenantId/Data/Get", + "parameters": [ + { + "$ref": "#/components/parameters/correlationId", + "required": true + }, + { + "$ref": "#/components/parameters/tenantId", + "required": true + } + ], + "responses": { + "200": { + "content": { + "application/json": { + "examples": { + "Architecture Report V1": { + "correlation": { + "auditTenantAccount": "user@example.com", + "correlationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "createdAt": "2023-11-19T10:00:00.000Z", + "isMigrating": false, + "reportTenantAccount": "user@example.com", + "schemaVersion": 1, + "tenantId": "123e4567-e89b-12d3-a456-426614174000", + "updatedAt": "2023-11-19T10:05:00.000Z" + }, + "principalData": { + "user": { + "e7b8c8a2-1f2e-4c3a-9b6a-2d8e4f8a9b7c": { + "assignedService": { + "3d282045-ec7f-4813-88e2-29b74ee609f7": { + "featureA": true, + "featureB": false + } + }, + "assignedLicense": [ + { + "id": "3d282045-ec7f-4813-88e2-29b74ee609f7", + "servicePlanList": [ + "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + ] + } + ], + "consumedService": { + "3d282045-ec7f-4813-88e2-29b74ee609f7": { + "featureA": true, + "featureB": false + } + }, + "llmInferred": { + "isServiceAccount": false, + "isFrontlineWorker": true, + "isTempWorker": null + }, + "principalMetadata": { + "sharedMailbox": false + }, + "enhancedData": { + "userPrincipalName": "user@example.com", + "idpJobTitle": "Engineer", + "idpDepartment": "IT", + "idpOfficeLocation": "HQ", + "idpEmployeeType": "Full-Time" + } + } + }, + "device": { + "f1e2d3c4-b5a6-7890-1234-56789abcdef0": { + "assignedService": { + "3d282045-ec7f-4813-88e2-29b74ee609f7": 5 + }, + "assignedLicense": [ + { + "id": "3d282045-ec7f-4813-88e2-29b74ee609f7", + "servicePlanList": [ + "a1b2c3d4-e5f6-7890-abcd-ef1234567890" + ] + } + ], + "consumedService": { + "3d282045-ec7f-4813-88e2-29b74ee609f7": 5 + }, + "principalMetadata": { + "sharedComputer": true + } + } + } + }, + "tenantMetadata": { + "totalDeviceCount": 1, + "totalGuestCount": 1, + "totalMemberCount": 1, + "totalUserCount": 1 + }, + "schemaVersion": 1 + } + }, + "schema": { + "$ref": "#/components/schemas/ArchitectureReportV1" + } + } + }, + "description": "The architecture report data for the specified correlation ID and tenant ID." + }, + "400": { + "$ref": "#/components/responses/400" + }, + "500": { + "$ref": "#/components/responses/500" + } + }, + "tags": [ + "Architecture Reporting" + ] + } + } + }, + "security": [ + { + "EntraID": [] + } + ], + "servers": [ + { + "description": "Server the hosts the API described in the document.", + "url": "https://api.shilab.com" + } + ], + "tags": [ + { + "description": "Routes for the core data gateway system.", + "name": "Core System", + "externalDocs": { + "description": "Data Gateway Documentation", + "url": "https://docs.shilab.com/Date-Gateway/" + } + }, + { + "description": "Manages the list of tenants that have interacted with the Data Gateway in the past.", + "name": "Tenant Records" + }, + { + "description": "Collects and reports data from the license analytics product.", + "name": "License Analytics", + "externalDocs": { "description": "License Analytics Documentation", "url": "https://docs.shilab.com/License-Analytics/" } @@ -6034,6 +6878,10 @@ "description": "Manages and reports the list of purchased licenses for the various SHI Lab Products.", "name": "License Entitlement" }, + { + "description": "Collects and reports data about a tenant's architecture.", + "name": "Architecture Reporting" + }, { "description": "Collects data from the various SHI Lab products.", "name": "Telemetry"