From 6ec0068b818adf7353e0de97812fe9244e8a0b0e Mon Sep 17 00:00:00 2001 From: alyssarcano <63893679+alyssarcano@users.noreply.github.com> Date: Fri, 19 Jun 2026 11:37:39 -0500 Subject: [PATCH 1/8] Implement OpenAPI specs for /Api/CloudMatrix/Audits --- specs/Data-Gateway.json | 358 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 358 insertions(+) diff --git a/specs/Data-Gateway.json b/specs/Data-Gateway.json index 9ca9165..a2c80bb 100644 --- a/specs/Data-Gateway.json +++ b/specs/Data-Gateway.json @@ -180,6 +180,77 @@ "value": "5a2f4c89-7d68-4f2e-8d40-2dca5d5a5c11" } } + }, + "auditActor": { + "name": "actor", + "in": "query", + "description": "Optional actor display name filter.", + "required": false, + "schema": { + "type": "string" + } + }, + "auditEntityType": { + "name": "entityType", + "in": "query", + "description": "Optional logical entity type filter.", + "required": false, + "schema": { + "type": "string" + } + }, + "auditEntityId": { + "name": "entityId", + "in": "query", + "description": "Optional entity identifier filter. Must be a GUID when provided.", + "required": false, + "schema": { + "type": "string", + "format": "uuid" + } + }, + "auditStartDate": { + "name": "startDate", + "in": "query", + "description": "Optional inclusive lower bound for event timestamp filtering.", + "required": false, + "schema": { + "type": "string", + "format": "date-time" + } + }, + "auditEndDate": { + "name": "endDate", + "in": "query", + "description": "Optional inclusive upper bound for event timestamp filtering.", + "required": false, + "schema": { + "type": "string", + "format": "date-time" + } + }, + "auditOffset": { + "name": "offset", + "in": "query", + "description": "Zero-based pagination offset.", + "required": false, + "schema": { + "type": "integer", + "minimum": 0, + "default": 0 + } + }, + "auditLimit": { + "name": "limit", + "in": "query", + "description": "Page size. Must be between 1 and 1000.", + "required": false, + "schema": { + "type": "integer", + "minimum": 1, + "maximum": 1000, + "default": 50 + } } }, "responses": { @@ -4957,6 +5028,225 @@ } } ] + }, + "CloudMatrix.AuditActor": { + "type": "object", + "additionalProperties": false, + "required": [ + "aadObjectId", + "displayName", + "type" + ], + "properties": { + "aadObjectId": { + "type": "string", + "format": "uuid" + }, + "displayName": { + "type": "string" + }, + "type": { + "type": "string", + "enum": [ + "User", + "ServicePrincipal", + "System" + ] + } + } + }, + "CloudMatrix.AuditEventOperation": { + "type": "object", + "additionalProperties": false, + "required": [ + "action", + "entityType", + "entityId", + "blobPath" + ], + "properties": { + "action": { + "type": "string", + "enum": [ + "CREATE", + "UPDATE", + "DELETE" + ] + }, + "entityType": { + "type": "string" + }, + "entityId": { + "type": "string", + "format": "uuid" + }, + "blobPath": { + "type": [ + "string", + "null" + ] + } + } + }, + "CloudMatrix.AuditEventChanges": { + "type": "object", + "additionalProperties": false, + "required": [ + "changedFields", + "before", + "after" + ], + "properties": { + "changedFields": { + "type": "array", + "items": { + "type": "string" + } + }, + "before": { + "type": [ + "object", + "null" + ], + "additionalProperties": true + }, + "after": { + "type": [ + "object", + "null" + ], + "additionalProperties": true + } + } + }, + "CloudMatrix.AuditEventContext": { + "type": "object", + "additionalProperties": false, + "required": [ + "correlationId", + "source", + "application" + ], + "properties": { + "correlationId": { + "type": [ + "string", + "null" + ], + "format": "uuid" + }, + "source": { + "type": "string" + }, + "application": { + "type": "string" + } + } + }, + "CloudMatrix.AuditEvent": { + "type": "object", + "additionalProperties": false, + "required": [ + "auditId", + "timestampUtc", + "actor", + "operation", + "changes", + "context" + ], + "properties": { + "auditId": { + "type": "string", + "format": "uuid" + }, + "timestampUtc": { + "type": "string", + "format": "date-time" + }, + "actor": { + "$ref": "#/components/schemas/CloudMatrix.AuditActor" + }, + "operation": { + "$ref": "#/components/schemas/CloudMatrix.AuditEventOperation" + }, + "changes": { + "$ref": "#/components/schemas/CloudMatrix.AuditEventChanges" + }, + "context": { + "$ref": "#/components/schemas/CloudMatrix.AuditEventContext" + } + }, + "example": { + "auditId": "8c9d7e36-8b71-4b46-b4da-7d1f7fd9a001", + "timestampUtc": "2026-03-09T09:30:16.000Z", + "actor": { + "aadObjectId": "3e4d5c6b-7a81-4f01-9a2b-1234567890ab", + "displayName": "Joe Bloggs", + "type": "User" + }, + "operation": { + "action": "UPDATE", + "entityType": "Cloud Matrix Template", + "entityId": "a12f2907-c781-4bf1-b912-b91510853052", + "blobPath": "cloud-matrix/templates/microsoft-enterprise/6.0.1.1.json" + }, + "changes": { + "changedFields": [ + "name", + "email", + "lastName" + ], + "before": { + "name": "Claudine Potter", + "email": "claudine.potter@acme_widgets.com", + "lastName": "Potter" + }, + "after": { + "name": "Claudine Moore", + "email": "claudine.moore@acme_widgets.com", + "lastName": "Moore" + } + }, + "context": { + "correlationId": "7d9b8d8f-08bb-46f7-b3cb-5d5df18b1d77", + "source": "Cloud Matrix", + "application": "CM Admin" + } + } + }, + "CloudMatrix.AuditEventListResponse": { + "type": "object", + "additionalProperties": false, + "required": [ + "items", + "offset", + "limit", + "nextOffset" + ], + "properties": { + "items": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CloudMatrix.AuditEvent" + } + }, + "offset": { + "type": "integer", + "minimum": 0 + }, + "limit": { + "type": "integer", + "minimum": 1, + "maximum": 1000 + }, + "nextOffset": { + "type": [ + "integer", + "null" + ], + "minimum": 0 + } + } } }, "securitySchemes": { @@ -11742,6 +12032,74 @@ ], "summary": "Upload and Replace the List of Cloud Matrix Third-Party Publishers" } + }, + "/Api/CloudMatrix/Audits": { + "get": { + "tags": [ + "Cloud Matrix" + ], + "summary": "Get Cloud Matrix audit events", + "description": "Returns a filtered, paginated list of Cloud Matrix audit events.", + "operationId": "getCloudMatrixAuditEvents", + "security": [ + { + "EntraID": [] + } + ], + "parameters": [ + { + "$ref": "#/components/parameters/auditActor" + }, + { + "$ref": "#/components/parameters/auditEntityType" + }, + { + "$ref": "#/components/parameters/auditEntityId" + }, + { + "$ref": "#/components/parameters/auditStartDate" + }, + { + "$ref": "#/components/parameters/auditEndDate" + }, + { + "$ref": "#/components/parameters/auditOffset" + }, + { + "$ref": "#/components/parameters/auditLimit" + } + ], + "responses": { + "200": { + "description": "Cloud Matrix audit events retrieved successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CloudMatrix.AuditEventListResponse" + } + } + } + }, + "400": { + "$ref": "#/components/responses/400" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403" + }, + "500": { + "$ref": "#/components/responses/500" + }, + "503": { + "$ref": "#/components/responses/503" + }, + "525": { + "$ref": "#/components/responses/525" + } + } + } } }, "security": [ From 3b4b841a97584286f7941f8d32c633802d7d1941 Mon Sep 17 00:00:00 2001 From: alyssarcano <63893679+alyssarcano@users.noreply.github.com> Date: Fri, 19 Jun 2026 11:51:28 -0500 Subject: [PATCH 2/8] fixing fields to match rest of file --- specs/Data-Gateway.json | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/specs/Data-Gateway.json b/specs/Data-Gateway.json index a2c80bb..4c4a2e2 100644 --- a/specs/Data-Gateway.json +++ b/specs/Data-Gateway.json @@ -215,8 +215,7 @@ "description": "Optional inclusive lower bound for event timestamp filtering.", "required": false, "schema": { - "type": "string", - "format": "date-time" + "$ref": "#/components/schemas/DateTimeStringType" } }, "auditEndDate": { @@ -225,8 +224,7 @@ "description": "Optional inclusive upper bound for event timestamp filtering.", "required": false, "schema": { - "type": "string", - "format": "date-time" + "$ref": "#/components/schemas/DateTimeStringType" } }, "auditOffset": { @@ -12040,7 +12038,7 @@ ], "summary": "Get Cloud Matrix audit events", "description": "Returns a filtered, paginated list of Cloud Matrix audit events.", - "operationId": "getCloudMatrixAuditEvents", + "operationId": "/Api/CloudMatrix/Audits/Get", "security": [ { "EntraID": [] From b7cbaef311cf6573f01f4f2349d27cb55a16c8d8 Mon Sep 17 00:00:00 2001 From: alyssarcano <63893679+alyssarcano@users.noreply.github.com> Date: Fri, 19 Jun 2026 14:38:22 -0500 Subject: [PATCH 3/8] Implemented OpenAPI Specifications for GET specified audit event endpoint --- specs/Data-Gateway.json | 184 +++++++++++++++++++++++++++------------- 1 file changed, 124 insertions(+), 60 deletions(-) diff --git a/specs/Data-Gateway.json b/specs/Data-Gateway.json index 4c4a2e2..bff4cde 100644 --- a/specs/Data-Gateway.json +++ b/specs/Data-Gateway.json @@ -249,6 +249,22 @@ "maximum": 1000, "default": 50 } + }, + "auditId": { + "description": "The unique identifier of the Cloud Matrix audit event.", + "in": "path", + "name": "auditId", + "required": true, + "schema": { + "$ref": "#/components/schemas/Uuid" + }, + "examples": { + "Valid Audit ID": { + "summary": "Example Valid Audit ID", + "description": "An example UUID string that represents a valid Cloud Matrix audit event ID.", + "value": "8c9d7e36-8b71-4b46-b4da-7d1f7fd9a001" + } + } } }, "responses": { @@ -12033,70 +12049,118 @@ }, "/Api/CloudMatrix/Audits": { "get": { - "tags": [ - "Cloud Matrix" - ], - "summary": "Get Cloud Matrix audit events", - "description": "Returns a filtered, paginated list of Cloud Matrix audit events.", - "operationId": "/Api/CloudMatrix/Audits/Get", - "security": [ - { - "EntraID": [] - } - ], - "parameters": [ - { - "$ref": "#/components/parameters/auditActor" - }, - { - "$ref": "#/components/parameters/auditEntityType" - }, - { - "$ref": "#/components/parameters/auditEntityId" - }, - { - "$ref": "#/components/parameters/auditStartDate" - }, - { - "$ref": "#/components/parameters/auditEndDate" - }, - { - "$ref": "#/components/parameters/auditOffset" - }, - { - "$ref": "#/components/parameters/auditLimit" - } - ], - "responses": { - "200": { - "description": "Cloud Matrix audit events retrieved successfully.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/CloudMatrix.AuditEventListResponse" + "tags": [ + "Cloud Matrix" + ], + "summary": "Get Cloud Matrix audit events", + "description": "Returns a filtered, paginated list of Cloud Matrix audit events.", + "operationId": "/Api/CloudMatrix/Audits/Get", + "security": [ + { + "EntraID": [] } + ], + "parameters": [ + { + "$ref": "#/components/parameters/auditActor" + }, + { + "$ref": "#/components/parameters/auditEntityType" + }, + { + "$ref": "#/components/parameters/auditEntityId" + }, + { + "$ref": "#/components/parameters/auditStartDate" + }, + { + "$ref": "#/components/parameters/auditEndDate" + }, + { + "$ref": "#/components/parameters/auditOffset" + }, + { + "$ref": "#/components/parameters/auditLimit" + } + ], + "responses": { + "200": { + "description": "Cloud Matrix audit events retrieved successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CloudMatrix.AuditEventListResponse" + } + } + } + }, + "400": { + "$ref": "#/components/responses/400" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403" + }, + "500": { + "$ref": "#/components/responses/500" + }, + "503": { + "$ref": "#/components/responses/503" + }, + "525": { + "$ref": "#/components/responses/525" } - } - }, - "400": { - "$ref": "#/components/responses/400" - }, - "401": { - "$ref": "#/components/responses/401" - }, - "403": { - "$ref": "#/components/responses/403" - }, - "500": { - "$ref": "#/components/responses/500" - }, - "503": { - "$ref": "#/components/responses/503" - }, - "525": { - "$ref": "#/components/responses/525" } } + }, + "/Api/CloudMatrix/Audits/{auditId}": { + "get": { + "tags": [ + "Cloud Matrix" + ], + "summary": "Get a specific Cloud Matrix audit event", + "description": "Returns the specified Cloud Matrix audit event by audit ID.", + "operationId": "/Api/CloudMatrix/Audits/:auditId/Get", + "parameters": [ + { + "$ref": "#/components/parameters/auditId" + } + ], + "responses": { + "200": { + "description": "Cloud Matrix audit event retrieved successfully.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CloudMatrix.AuditEvent" + } + } + } + }, + "400": { + "$ref": "#/components/responses/400" + }, + "401": { + "$ref": "#/components/responses/401" + }, + "403": { + "$ref": "#/components/responses/403" + }, + "404": { + "$ref": "#/components/responses/404" + }, + "500": { + "$ref": "#/components/responses/500" + }, + "503": { + "$ref": "#/components/responses/503" + }, + "525": { + "$ref": "#/components/responses/525" + } + } } } }, From c59f76178610ac6af6aee5561e941750fd664477 Mon Sep 17 00:00:00 2001 From: alyssarcano <63893679+alyssarcano@users.noreply.github.com> Date: Fri, 19 Jun 2026 15:00:37 -0500 Subject: [PATCH 4/8] Fixed indentation, comments, and referenced proper UUID --- specs/Data-Gateway.json | 351 ++++++++++++++++++++-------------------- 1 file changed, 176 insertions(+), 175 deletions(-) diff --git a/specs/Data-Gateway.json b/specs/Data-Gateway.json index bff4cde..d5e609f 100644 --- a/specs/Data-Gateway.json +++ b/specs/Data-Gateway.json @@ -205,8 +205,7 @@ "description": "Optional entity identifier filter. Must be a GUID when provided.", "required": false, "schema": { - "type": "string", - "format": "uuid" + "$ref": "#/components/schemas/Uuid" } }, "auditStartDate": { @@ -260,9 +259,9 @@ }, "examples": { "Valid Audit ID": { - "summary": "Example Valid Audit ID", - "description": "An example UUID string that represents a valid Cloud Matrix audit event ID.", - "value": "8c9d7e36-8b71-4b46-b4da-7d1f7fd9a001" + "summary": "Example Valid Audit ID", + "description": "An example UUID string that represents a valid Cloud Matrix audit event ID.", + "value": "8c9d7e36-8b71-4b46-b4da-7d1f7fd9a001" } } } @@ -3394,7 +3393,7 @@ "contractValue": 5003 } ], - "replacementDate": "2026-12-31T00:00:00Z" + "replacementDate": "2026-12-31T00:00:00Z" }, "notes": "Example notes" } @@ -5047,219 +5046,221 @@ "type": "object", "additionalProperties": false, "required": [ - "aadObjectId", - "displayName", - "type" + "aadObjectId", + "displayName", + "type" ], "properties": { - "aadObjectId": { - "type": "string", - "format": "uuid" - }, - "displayName": { - "type": "string" - }, - "type": { - "type": "string", - "enum": [ - "User", - "ServicePrincipal", - "System" - ] - } + "aadObjectId": { + "type": "string", + "format": "uuid" + }, + "displayName": { + "type": "string" + }, + "type": { + "type": "string", + "enum": [ + "User", + "ServicePrincipal", + "System" + ] + } } }, "CloudMatrix.AuditEventOperation": { "type": "object", "additionalProperties": false, "required": [ - "action", - "entityType", - "entityId", - "blobPath" + "action", + "entityType", + "entityId", + "blobPath" ], "properties": { - "action": { - "type": "string", - "enum": [ - "CREATE", - "UPDATE", - "DELETE" - ] - }, - "entityType": { - "type": "string" - }, - "entityId": { - "type": "string", - "format": "uuid" - }, - "blobPath": { - "type": [ - "string", - "null" - ] - } + "action": { + "type": "string", + "enum": [ + "CREATE", + "UPDATE", + "DELETE" + ] + }, + "entityType": { + "type": "string" + }, + "entityId": { + "type": "string", + "format": "uuid" + }, + "blobPath": { + "type": [ + "string", + "null" + ] + } } }, "CloudMatrix.AuditEventChanges": { "type": "object", "additionalProperties": false, "required": [ - "changedFields", - "before", - "after" + "changedFields", + "before", + "after" ], "properties": { - "changedFields": { - "type": "array", - "items": { - "type": "string" + "changedFields": { + "type": "array", + "items": { + "type": "string" + } + }, + "before": { + "type": [ + "object", + "null" + ], + "additionalProperties": true + }, + "after": { + "type": [ + "object", + "null" + ], + "additionalProperties": true } - }, - "before": { - "type": [ - "object", - "null" - ], - "additionalProperties": true - }, - "after": { - "type": [ - "object", - "null" - ], - "additionalProperties": true - } } }, "CloudMatrix.AuditEventContext": { "type": "object", "additionalProperties": false, "required": [ - "correlationId", - "source", - "application" + "correlationId", + "source", + "application" ], "properties": { - "correlationId": { - "type": [ - "string", - "null" - ], - "format": "uuid" - }, - "source": { - "type": "string" - }, - "application": { - "type": "string" - } + "correlationId": { + "type": [ + "string", + "null" + ], + "format": "uuid" + }, + "source": { + "type": "string" + }, + "application": { + "type": "string" + } } }, "CloudMatrix.AuditEvent": { "type": "object", "additionalProperties": false, "required": [ - "auditId", - "timestampUtc", - "actor", - "operation", - "changes", - "context" + "auditId", + "timestampUtc", + "actor", + "operation", + "changes", + "context" ], "properties": { - "auditId": { - "type": "string", - "format": "uuid" - }, - "timestampUtc": { - "type": "string", - "format": "date-time" - }, - "actor": { - "$ref": "#/components/schemas/CloudMatrix.AuditActor" - }, - "operation": { - "$ref": "#/components/schemas/CloudMatrix.AuditEventOperation" - }, - "changes": { - "$ref": "#/components/schemas/CloudMatrix.AuditEventChanges" - }, - "context": { - "$ref": "#/components/schemas/CloudMatrix.AuditEventContext" - } - }, - "example": { - "auditId": "8c9d7e36-8b71-4b46-b4da-7d1f7fd9a001", - "timestampUtc": "2026-03-09T09:30:16.000Z", - "actor": { - "aadObjectId": "3e4d5c6b-7a81-4f01-9a2b-1234567890ab", - "displayName": "Joe Bloggs", - "type": "User" - }, - "operation": { - "action": "UPDATE", - "entityType": "Cloud Matrix Template", - "entityId": "a12f2907-c781-4bf1-b912-b91510853052", - "blobPath": "cloud-matrix/templates/microsoft-enterprise/6.0.1.1.json" - }, - "changes": { - "changedFields": [ - "name", - "email", - "lastName" - ], - "before": { - "name": "Claudine Potter", - "email": "claudine.potter@acme_widgets.com", - "lastName": "Potter" + "auditId": { + "type": "string", + "format": "uuid" }, - "after": { - "name": "Claudine Moore", - "email": "claudine.moore@acme_widgets.com", - "lastName": "Moore" + "timestampUtc": { + "type": "string", + "format": "date-time" + }, + "actor": { + "$ref": "#/components/schemas/CloudMatrix.AuditActor" + }, + "operation": { + "$ref": "#/components/schemas/CloudMatrix.AuditEventOperation" + }, + "changes": { + "$ref": "#/components/schemas/CloudMatrix.AuditEventChanges" + }, + "context": { + "$ref": "#/components/schemas/CloudMatrix.AuditEventContext" } }, - "context": { - "correlationId": "7d9b8d8f-08bb-46f7-b3cb-5d5df18b1d77", - "source": "Cloud Matrix", - "application": "CM Admin" - } - } + "examples": [ + { + "auditId": "8c9d7e36-8b71-4b46-b4da-7d1f7fd9a001", + "timestampUtc": "2026-03-09T09:30:16.000Z", + "actor": { + "aadObjectId": "3e4d5c6b-7a81-4f01-9a2b-1234567890ab", + "displayName": "Joe Bloggs", + "type": "User" + }, + "operation": { + "action": "UPDATE", + "entityType": "Cloud Matrix Template", + "entityId": "a12f2907-c781-4bf1-b912-b91510853052", + "blobPath": "cloud-matrix/templates/microsoft-enterprise/6.0.1.1.json" + }, + "changes": { + "changedFields": [ + "name", + "email", + "lastName" + ], + "before": { + "name": "Claudine Potter", + "email": "claudine.potter@acme_widgets.com", + "lastName": "Potter" + }, + "after": { + "name": "Claudine Moore", + "email": "claudine.moore@acme_widgets.com", + "lastName": "Moore" + } + }, + "context": { + "correlationId": "7d9b8d8f-08bb-46f7-b3cb-5d5df18b1d77", + "source": "Cloud Matrix", + "application": "CM Admin" + } + } + ] }, "CloudMatrix.AuditEventListResponse": { "type": "object", "additionalProperties": false, "required": [ - "items", - "offset", - "limit", - "nextOffset" + "items", + "offset", + "limit", + "nextOffset" ], "properties": { - "items": { - "type": "array", "items": { - "$ref": "#/components/schemas/CloudMatrix.AuditEvent" + "type": "array", + "items": { + "$ref": "#/components/schemas/CloudMatrix.AuditEvent" + } + }, + "offset": { + "type": "integer", + "minimum": 0 + }, + "limit": { + "type": "integer", + "minimum": 1, + "maximum": 1000 + }, + "nextOffset": { + "type": [ + "integer", + "null" + ], + "minimum": 0 } - }, - "offset": { - "type": "integer", - "minimum": 0 - }, - "limit": { - "type": "integer", - "minimum": 1, - "maximum": 1000 - }, - "nextOffset": { - "type": [ - "integer", - "null" - ], - "minimum": 0 - } } } }, @@ -12053,7 +12054,7 @@ "Cloud Matrix" ], "summary": "Get Cloud Matrix audit events", - "description": "Returns a filtered, paginated list of Cloud Matrix audit events.", + "description": "Returns a filtered, paginated list of Cloud Matrix audit events.\n\nThis endpoint requires the `CloudMatrix.Read`, `CloudMatrix.Read.Del`, `CloudMatrix.Read.All`, `CloudMatrix.ReadWrite`, or `CloudMatrix.ReadWrite.All` scope (permission).", "operationId": "/Api/CloudMatrix/Audits/Get", "security": [ { @@ -12121,7 +12122,7 @@ "Cloud Matrix" ], "summary": "Get a specific Cloud Matrix audit event", - "description": "Returns the specified Cloud Matrix audit event by audit ID.", + "description": "Returns the specified Cloud Matrix audit event by audit ID.\n\nThis endpoint requires the `CloudMatrix.Read`, `CloudMatrix.Read.Del`, `CloudMatrix.Read.All`, `CloudMatrix.ReadWrite`, or `CloudMatrix.ReadWrite.All` scope (permission).", "operationId": "/Api/CloudMatrix/Audits/:auditId/Get", "parameters": [ { @@ -12221,4 +12222,4 @@ "name": "Cloud Matrix" } ] -} +} \ No newline at end of file From f0f0b9a1349f62ad442bc4f2fcb536e9b5f4c5f0 Mon Sep 17 00:00:00 2001 From: Craig Whittington Date: Tue, 23 Jun 2026 14:28:39 +0100 Subject: [PATCH 5/8] Updated actor to lastUpdatedBy --- specs/Data-Gateway.json | 48 ++++++++++------------------------------- 1 file changed, 11 insertions(+), 37 deletions(-) diff --git a/specs/Data-Gateway.json b/specs/Data-Gateway.json index d5e609f..877fe69 100644 --- a/specs/Data-Gateway.json +++ b/specs/Data-Gateway.json @@ -181,10 +181,10 @@ } } }, - "auditActor": { - "name": "actor", + "auditLastUpdatedBy": { + "name": "lastUpdatedBy", "in": "query", - "description": "Optional actor display name filter.", + "description": "Optional last updated by user filter.", "required": false, "schema": { "type": "string" @@ -5042,31 +5042,9 @@ } ] }, - "CloudMatrix.AuditActor": { - "type": "object", - "additionalProperties": false, - "required": [ - "aadObjectId", - "displayName", - "type" - ], - "properties": { - "aadObjectId": { - "type": "string", - "format": "uuid" - }, - "displayName": { - "type": "string" - }, - "type": { - "type": "string", - "enum": [ - "User", - "ServicePrincipal", - "System" - ] - } - } + "CloudMatrix.LastUpdatedBy": { + "type": "string", + "description": "User who last updated the entity." }, "CloudMatrix.AuditEventOperation": { "type": "object", @@ -5162,7 +5140,7 @@ "required": [ "auditId", "timestampUtc", - "actor", + "lastUpdatedBy", "operation", "changes", "context" @@ -5176,8 +5154,8 @@ "type": "string", "format": "date-time" }, - "actor": { - "$ref": "#/components/schemas/CloudMatrix.AuditActor" + "lastUpdatedBy": { + "$ref": "#/components/schemas/CloudMatrix.LastUpdatedBy" }, "operation": { "$ref": "#/components/schemas/CloudMatrix.AuditEventOperation" @@ -5193,11 +5171,7 @@ { "auditId": "8c9d7e36-8b71-4b46-b4da-7d1f7fd9a001", "timestampUtc": "2026-03-09T09:30:16.000Z", - "actor": { - "aadObjectId": "3e4d5c6b-7a81-4f01-9a2b-1234567890ab", - "displayName": "Joe Bloggs", - "type": "User" - }, + "lastUpdatedBy": "Joe Bloggs", "operation": { "action": "UPDATE", "entityType": "Cloud Matrix Template", @@ -12063,7 +12037,7 @@ ], "parameters": [ { - "$ref": "#/components/parameters/auditActor" + "$ref": "#/components/parameters/auditLastUpdatedBy" }, { "$ref": "#/components/parameters/auditEntityType" From f70da23cd3e2baea9ba5a7a285cec061f173037b Mon Sep 17 00:00:00 2001 From: Craig Whittington Date: Tue, 23 Jun 2026 15:11:02 +0100 Subject: [PATCH 6/8] Refactor audit event schemas to enhance clarity and structure, adding new properties and examples for better documentation. --- specs/Data-Gateway.json | 338 +++++++++++++++++++++++++++++----------- 1 file changed, 249 insertions(+), 89 deletions(-) diff --git a/specs/Data-Gateway.json b/specs/Data-Gateway.json index 877fe69..dd30ee8 100644 --- a/specs/Data-Gateway.json +++ b/specs/Data-Gateway.json @@ -5046,159 +5046,319 @@ "type": "string", "description": "User who last updated the entity." }, - "CloudMatrix.AuditEventOperation": { + "CloudMatrix.AuditValue": { + "description": "An audit value that can contain any JSON-compatible value." + }, + "CloudMatrix.AuditOperation": { + "type": "string", + "enum": [ + "CREATE", + "UPDATE", + "DELETE" + ] + }, + "CloudMatrix.AuditEventChange": { "type": "object", "additionalProperties": false, "required": [ - "action", - "entityType", - "entityId", - "blobPath" + "path" ], "properties": { - "action": { - "type": "string", - "enum": [ - "CREATE", - "UPDATE", - "DELETE" - ] + "path": { + "type": "string" }, + "oldValue": { + "$ref": "#/components/schemas/CloudMatrix.AuditValue" + }, + "newValue": { + "$ref": "#/components/schemas/CloudMatrix.AuditValue" + } + } + }, + "CloudMatrix.AuditEventContext": { + "type": "object", + "additionalProperties": true, + "required": [ + "entityType", + "entityId" + ], + "properties": { "entityType": { "type": "string" }, "entityId": { - "type": "string", - "format": "uuid" - }, - "blobPath": { - "type": [ - "string", - "null" - ] + "type": "string" } } }, - "CloudMatrix.AuditEventChanges": { + "CloudMatrix.AuditEvent": { "type": "object", "additionalProperties": false, "required": [ - "changedFields", - "before", - "after" + "auditId", + "timestampUtc", + "lastUpdatedBy", + "operation", + "changes", + "context" ], "properties": { - "changedFields": { + "auditId": { + "type": "string", + "format": "uuid" + }, + "timestampUtc": { + "type": "string", + "format": "date-time" + }, + "lastUpdatedBy": { + "$ref": "#/components/schemas/CloudMatrix.LastUpdatedBy" + }, + "operation": { + "$ref": "#/components/schemas/CloudMatrix.AuditOperation" + }, + "changes": { "type": "array", "items": { - "type": "string" + "$ref": "#/components/schemas/CloudMatrix.AuditEventChange" } }, - "before": { - "type": [ - "object", - "null" - ], - "additionalProperties": true - }, - "after": { - "type": [ - "object", - "null" + "context": { + "$ref": "#/components/schemas/CloudMatrix.AuditEventContext" + } + }, + "examples": [ + { + "auditId": "8c9d7e36-8b71-4b46-b4da-7d1f7fd9a001", + "timestampUtc": "2026-03-09T09:30:16.000Z", + "lastUpdatedBy": "Joe Bloggs", + "operation": "UPDATE", + "changes": [ + { + "path": "$.name", + "oldValue": "Claudine Potter", + "newValue": "Claudine Moore" + }, + { + "path": "$.email", + "oldValue": "claudine.potter@acme_widgets.com", + "newValue": "claudine.moore@acme_widgets.com" + } ], - "additionalProperties": true + "context": { + "entityType": "Cloud Matrix Template", + "entityId": "a12f2907-c781-4bf1-b912-b91510853052", + "correlationId": "7d9b8d8f-08bb-46f7-b3cb-5d5df18b1d77" + } } - } + ] }, - "CloudMatrix.AuditEventContext": { + "CloudMatrix.AuditDiffEntryType": { + "type": "string", + "enum": [ + "ADD", + "REMOVE", + "UPDATE", + "MOVE" + ] + }, + "CloudMatrix.AuditDiffEntry": { "type": "object", "additionalProperties": false, "required": [ - "correlationId", - "source", - "application" + "path", + "type", + "valueType" ], "properties": { - "correlationId": { + "path": { + "type": "string" + }, + "type": { + "$ref": "#/components/schemas/CloudMatrix.AuditDiffEntryType" + }, + "oldValue": { + "$ref": "#/components/schemas/CloudMatrix.AuditValue" + }, + "newValue": { + "$ref": "#/components/schemas/CloudMatrix.AuditValue" + }, + "valueType": { "type": [ "string", "null" - ], - "format": "uuid" + ] }, - "source": { + "leftPath": { "type": "string" }, - "application": { + "rightPath": { "type": "string" + }, + "fromIndex": { + "type": "integer" + }, + "toIndex": { + "type": "integer" } } }, - "CloudMatrix.AuditEvent": { + "CloudMatrix.AuditDiffSummary": { + "type": "object", + "additionalProperties": false, + "required": [ + "totalChanges", + "adds", + "removes", + "updates", + "moves" + ], + "properties": { + "totalChanges": { + "type": "integer" + }, + "adds": { + "type": "integer" + }, + "removes": { + "type": "integer" + }, + "updates": { + "type": "integer" + }, + "moves": { + "type": "integer" + } + } + }, + "CloudMatrix.AuditDiff": { + "type": "object", + "additionalProperties": false, + "required": [ + "summary", + "changes" + ], + "properties": { + "summary": { + "$ref": "#/components/schemas/CloudMatrix.AuditDiffSummary" + }, + "changes": { + "type": "array", + "items": { + "$ref": "#/components/schemas/CloudMatrix.AuditDiffEntry" + } + } + } + }, + "CloudMatrix.AuditSummary": { "type": "object", "additionalProperties": false, "required": [ "auditId", - "timestampUtc", + "auditFilename", + "lastUpdated", "lastUpdatedBy", - "operation", - "changes", - "context" + "version", + "auditArea" ], "properties": { "auditId": { "type": "string", "format": "uuid" }, - "timestampUtc": { + "auditFilename": { + "type": "string" + }, + "lastUpdated": { "type": "string", "format": "date-time" }, "lastUpdatedBy": { "$ref": "#/components/schemas/CloudMatrix.LastUpdatedBy" }, - "operation": { - "$ref": "#/components/schemas/CloudMatrix.AuditEventOperation" + "version": { + "type": "string" }, - "changes": { - "$ref": "#/components/schemas/CloudMatrix.AuditEventChanges" + "auditArea": { + "type": "string" + } + } + }, + "CloudMatrix.AuditDetail": { + "allOf": [ + { + "$ref": "#/components/schemas/CloudMatrix.AuditSummary" }, - "context": { - "$ref": "#/components/schemas/CloudMatrix.AuditEventContext" + { + "type": "object", + "additionalProperties": false, + "required": [ + "template", + "originalRecord", + "updatedRecord", + "diff" + ], + "properties": { + "template": { + "type": "string" + }, + "reasonForUpdate": { + "type": "string" + }, + "originalRecord": { + "$ref": "#/components/schemas/CloudMatrix.AuditValue" + }, + "updatedRecord": { + "$ref": "#/components/schemas/CloudMatrix.AuditValue" + }, + "diff": { + "$ref": "#/components/schemas/CloudMatrix.AuditDiff" + } + } } - }, + ], "examples": [ { "auditId": "8c9d7e36-8b71-4b46-b4da-7d1f7fd9a001", - "timestampUtc": "2026-03-09T09:30:16.000Z", + "auditFilename": "cloud-matrix-template-update.json", + "lastUpdated": "2026-03-09T09:30:16.000Z", "lastUpdatedBy": "Joe Bloggs", - "operation": { - "action": "UPDATE", - "entityType": "Cloud Matrix Template", - "entityId": "a12f2907-c781-4bf1-b912-b91510853052", - "blobPath": "cloud-matrix/templates/microsoft-enterprise/6.0.1.1.json" + "version": "6.0.1.1", + "auditArea": "Cloud Matrix Template", + "template": "Microsoft Enterprise", + "reasonForUpdate": "Updated display name and contact email.", + "originalRecord": { + "name": "Claudine Potter", + "email": "claudine.potter@acme_widgets.com" }, - "changes": { - "changedFields": [ - "name", - "email", - "lastName" - ], - "before": { - "name": "Claudine Potter", - "email": "claudine.potter@acme_widgets.com", - "lastName": "Potter" - }, - "after": { - "name": "Claudine Moore", - "email": "claudine.moore@acme_widgets.com", - "lastName": "Moore" - } + "updatedRecord": { + "name": "Claudine Moore", + "email": "claudine.moore@acme_widgets.com" }, - "context": { - "correlationId": "7d9b8d8f-08bb-46f7-b3cb-5d5df18b1d77", - "source": "Cloud Matrix", - "application": "CM Admin" + "diff": { + "summary": { + "totalChanges": 2, + "adds": 0, + "removes": 0, + "updates": 2, + "moves": 0 + }, + "changes": [ + { + "path": "$.name", + "type": "UPDATE", + "oldValue": "Claudine Potter", + "newValue": "Claudine Moore", + "valueType": "string" + }, + { + "path": "$.email", + "type": "UPDATE", + "oldValue": "claudine.potter@acme_widgets.com", + "newValue": "claudine.moore@acme_widgets.com", + "valueType": "string" + } + ] } } ] @@ -12109,7 +12269,7 @@ "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/CloudMatrix.AuditEvent" + "$ref": "#/components/schemas/CloudMatrix.AuditDetail" } } } @@ -12196,4 +12356,4 @@ "name": "Cloud Matrix" } ] -} \ No newline at end of file +} From 5b3200437aea84a2ff19f32db23fa66691f0a5e8 Mon Sep 17 00:00:00 2001 From: Craig Whittington Date: Wed, 24 Jun 2026 12:04:07 +0100 Subject: [PATCH 7/8] Refine OpenAPI specifications for Cloud Matrix audit events, simplifying security requirements and descriptions. --- specs/Data-Gateway.json | 14 ++------------ 1 file changed, 2 insertions(+), 12 deletions(-) diff --git a/specs/Data-Gateway.json b/specs/Data-Gateway.json index dd30ee8..e545b8b 100644 --- a/specs/Data-Gateway.json +++ b/specs/Data-Gateway.json @@ -12188,13 +12188,8 @@ "Cloud Matrix" ], "summary": "Get Cloud Matrix audit events", - "description": "Returns a filtered, paginated list of Cloud Matrix audit events.\n\nThis endpoint requires the `CloudMatrix.Read`, `CloudMatrix.Read.Del`, `CloudMatrix.Read.All`, `CloudMatrix.ReadWrite`, or `CloudMatrix.ReadWrite.All` scope (permission).", + "description": "Returns a filtered, paginated list of Cloud Matrix audit events.\n\nThis endpoint requires the `CloudMatrix.Read` scope (permission).", "operationId": "/Api/CloudMatrix/Audits/Get", - "security": [ - { - "EntraID": [] - } - ], "parameters": [ { "$ref": "#/components/parameters/auditLastUpdatedBy" @@ -12256,7 +12251,7 @@ "Cloud Matrix" ], "summary": "Get a specific Cloud Matrix audit event", - "description": "Returns the specified Cloud Matrix audit event by audit ID.\n\nThis endpoint requires the `CloudMatrix.Read`, `CloudMatrix.Read.Del`, `CloudMatrix.Read.All`, `CloudMatrix.ReadWrite`, or `CloudMatrix.ReadWrite.All` scope (permission).", + "description": "Returns the specified Cloud Matrix audit event by audit ID.\n\nThis endpoint requires the `CloudMatrix.Read`.", "operationId": "/Api/CloudMatrix/Audits/:auditId/Get", "parameters": [ { @@ -12299,11 +12294,6 @@ } } }, - "security": [ - { - "EntraID": [] - } - ], "servers": [ { "description": "Server the hosts the API described in the document.", From afd30e3745d1f6890a656e80ae138d73209844ce Mon Sep 17 00:00:00 2001 From: Craig Whittington Date: Wed, 24 Jun 2026 12:31:33 +0100 Subject: [PATCH 8/8] Added back in security scope and updated description text --- specs/Data-Gateway.json | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/specs/Data-Gateway.json b/specs/Data-Gateway.json index e545b8b..903fba1 100644 --- a/specs/Data-Gateway.json +++ b/specs/Data-Gateway.json @@ -12251,7 +12251,7 @@ "Cloud Matrix" ], "summary": "Get a specific Cloud Matrix audit event", - "description": "Returns the specified Cloud Matrix audit event by audit ID.\n\nThis endpoint requires the `CloudMatrix.Read`.", + "description": "Returns the specified Cloud Matrix audit event by audit ID.\n\nThis endpoint requires the `CloudMatrix.Read` scope (permission).", "operationId": "/Api/CloudMatrix/Audits/:auditId/Get", "parameters": [ { @@ -12294,6 +12294,11 @@ } } }, + "security": [ + { + "EntraID": [] + } + ], "servers": [ { "description": "Server the hosts the API described in the document.",