From f945bf3a95745190984c7b2f33c857439a78f321 Mon Sep 17 00:00:00 2001 From: schaerentim Date: Mon, 16 Dec 2024 15:44:58 +0100 Subject: [PATCH] add info on worknotes and comments in responses --- incidentRestAPI.yml | 887 +++++++++++++++++++++++++------------------- 1 file changed, 499 insertions(+), 388 deletions(-) diff --git a/incidentRestAPI.yml b/incidentRestAPI.yml index 8213602..043e65c 100644 --- a/incidentRestAPI.yml +++ b/incidentRestAPI.yml @@ -3,7 +3,7 @@ info: title: Incident REST API description: | Handles communication between the MyIT incident system and partner systems. - + **State values:** - New: 1 - In progress: 2 @@ -18,7 +18,7 @@ servers: security: - BasicAuth: [] - + paths: /incident: post: @@ -34,35 +34,35 @@ paths: properties: partnerId: description: the id of the partner system, agreed upon with the MyIT team. - example: "SystemX" + example: 'SystemX' type: string partnerIncidentId: description: your internal id of the incident, for your reference. Note that this must be unique. Once an incident is closed however - the id is freed up again. - example: "1234567890" + example: '1234567890' type: string channel: description: possible values are 'monitoring' or 'vendor'. If you are an external vendor, please choose 'vendor'. If you are an internal event-monitoring system, please choose 'monitoring'. - example: "vendor" + example: 'vendor' type: string description: description: the descriptive title of the incident. - example: "Some problem with something" + example: 'Some problem with something' type: string short_description: description: the description of the incident, describing the situation in detail. - example: "There is a complicated problem with the incident rest api - HELP!" + example: 'There is a complicated problem with the incident rest api - HELP!' type: string location: description: the name or sys-id of the concerned location. If you don't know what to put here, please ask your swisspost contact. - example: "afeeadcb8776c6103efc00000000" + example: 'afeeadcb8776c6103efc00000000' type: string cmdb_ci: description: the name or sys-id of the concerned configuration item. If you don't know what to put here, please ask your swisspost contact. - example: "w010xq" + example: 'w010xq' type: string causing_ci: description: the name or sys-id of the underlying causing configuration item. If you don't know what to put here, please ask your swisspost contact. This is mandatory only for systems of channel 'monitoring'. - example: "w010xq" + example: 'w010xq' type: string attachments: description: any attachments you'd like to add to the incident. The content must be base64 encoded. @@ -72,11 +72,11 @@ paths: properties: fileName: description: the name of the file - example: "picture_of_the_problem.png" + example: 'picture_of_the_problem.png' type: string content_type: description: the mime type of the file - example: "image/png" + example: 'image/png' type: string content: type: string @@ -98,74 +98,98 @@ paths: schema: type: object properties: - metadata: type: object - example: { - "config": "SystemX", - "partnerId": "SystemX", - "server_system_time": "2020-10-24T06:23:41.089Z" - } + example: + { + 'config': 'SystemX', + 'partnerId': 'SystemX', + 'server_system_time': '2020-10-24T06:23:41.089Z' + } message: type: string - example: "Incident 00000000000000000000000000000001 created." + example: 'Incident 00000000000000000000000000000001 created.' data: type: object - example: { - "incidentId": "6d101e0487e3ca903ef00000000000", - "number": "INC0000001", - "channel" : "vendor", - "partnerIncidentId": "1234567890", - "description" : "Some problem with something", - "short_description": "There is a complicated problem with the incident rest api - HELP!", - "state": 1, - "opened_at": "1997-09-08T05:55:00Z", - "sys_updated_on": "2024-07-17T14:36:59Z", - "opened_by": { - "first_name": "Example", - "last_name": "Name", - "user_name": "example_name" + example: + { + 'incidentId': '6d101e0487e3ca903ef00000000000', + 'number': 'INC0000001', + 'channel': 'vendor', + 'partnerIncidentId': '1234567890', + 'description': 'Some problem with something', + 'short_description': 'There is a complicated problem with the incident rest api - HELP!', + 'state': 1, + 'opened_at': '1997-09-08T05:55:00Z', + 'sys_updated_on': '2024-07-17T14:36:59Z', + 'opened_by': + { + 'first_name': 'Example', + 'last_name': 'Name', + 'user_name': 'example_name' + }, + 'assignment_group': + { + 'description': 'Example group', + 'name': 'Example groupname' }, - "assignment_group": { - "description": "Example group", - "name": "Example groupname" - }, - "location": { - "city": "Bern", - "cmn_location_type": "room", - "country": "Switzerland", - "full_name": "CH/Bern/Viktoriastrasse 21/Viktoriastrasse 21/1.UG/001", - "name": "001" - }, - "causing_ci": { - "asset_tag": "123456789", - "model_id": { - "display_name": "Lenovo ThinkPad P16 Gen1", - "name": "ThinkPad P16 Gen1", - "sys_id": "70a44cbf87f739d06d000000000000", + 'location': + { + 'city': 'Bern', + 'cmn_location_type': 'room', + 'country': 'Switzerland', + 'full_name': 'CH/Bern/Viktoriastrasse 21/Viktoriastrasse 21/1.UG/001', + 'name': '001' }, - "name": "example hostname", - "operational_status": 1, - "serial_number": "ABCD12345", - "sys_id": "acba0c3f87ff75503ef0000000000000", - }, - "attachments": [ - { - "filename": "thisIsAFileName.pdf", - "content_type": "application/pdf", - "download_url": "https:///sys_attachment.do?sys_id=12f0297d87544e12334567890000000", - "sys_id": "12f0297d87544e12334567890000000" - }, - { - "filename": "picture_of_the_problem.png", - "content_type": "image/png", - "download_url": "https:///sys_attachment.do?sys_id=12f0297d87544e12334567890000001", - "sys_id": "12f0297d87544e12334567890000001" - }, - ] - } + 'causing_ci': + { + 'asset_tag': '123456789', + 'model_id': + { + 'display_name': 'Lenovo ThinkPad P16 Gen1', + 'name': 'ThinkPad P16 Gen1', + 'sys_id': '70a44cbf87f739d06d000000000000' + }, + 'name': 'example hostname', + 'operational_status': 1, + 'serial_number': 'ABCD12345', + 'sys_id': 'acba0c3f87ff75503ef0000000000000' + }, + 'attachments': + [ + { + 'filename': 'thisIsAFileName.pdf', + 'content_type': 'application/pdf', + 'download_url': 'https:///sys_attachment.do?sys_id=12f0297d87544e12334567890000000', + 'sys_id': '12f0297d87544e12334567890000000' + }, + { + 'filename': 'picture_of_the_problem.png', + 'content_type': 'image/png', + 'download_url': 'https:///sys_attachment.do?sys_id=12f0297d87544e12334567890000001', + 'sys_id': '12f0297d87544e12334567890000001' + } + ], + 'worknotes': + [ + { + 'element': 'comments', + 'sys_created_by': 'technical_user_xyz', + 'sys_created_on': '2024-11-29T14:24:25Z', + 'sys_id': '33defc09876612d06dc8635400000000', + 'value': "External system:\nthis is a comment" + }, + { + 'element': 'work_notes', + 'sys_created_by': 'technical_user_xyz', + 'sys_created_on': '2024-11-29T12:18:56Z', + 'sys_id': '7c32be1b87de5e103efcec2300000001', + 'value': "External system:\nthis is a worknote" + } + ] + } '400': description: bad request @@ -176,7 +200,7 @@ paths: properties: name: type: string - example: "MyItRestException" + example: 'MyItRestException' message: type: string example: "'partnerId' not specified" @@ -185,33 +209,34 @@ paths: example: 400 '401': description: unauthorized - content: + content: application/json: schema: type: object properties: error: type: object - example: { - "message": "User Not Authenticated", - "detail": "Required to provide Auth information" - } + example: + { + 'message': 'User Not Authenticated', + 'detail': 'Required to provide Auth information' + } status: type: string - example: "failure" + example: 'failure' '500': description: internal server error - content: + content: application/json: schema: type: object properties: name: type: string - example: "MyItRestException" + example: 'MyItRestException' message: type: string - example: "The action failed due to a business rule. Message: [\"short_description is mandatory.\",\"partnerIncidentId is mandatory.\"]" + example: 'The action failed due to a business rule. Message: ["short_description is mandatory.","partnerIncidentId is mandatory."]' status: type: integer example: 500 @@ -224,7 +249,7 @@ paths: in: query required: true description: The id of the partner system, to be agreed upon with the MyIT team. - example: "SystemX" + example: 'SystemX' schema: type: string - name: incidentId @@ -238,75 +263,99 @@ paths: in: query required: true description: your internal id of the incident, for your reference. Note that this must be unique. Once an incident is closed however - the id is freed up again. - example: "1234567890" + example: '1234567890' schema: type: string responses: '200': description: the incident corresponding to the incidentId or partnerIncidentId. - content: + content: application/json: schema: type: object properties: metadata: type: object - example: { - "config": "SystemX", - "partnerId": "SystemX", - "server_system_time": "2020-10-24T06:23:41.089Z" - } + example: + { + 'config': 'SystemX', + 'partnerId': 'SystemX', + 'server_system_time': '2020-10-24T06:23:41.089Z' + } data: type: object - example: { - "incidentId": "6d101e0487e3ca903ef00000000000", - "number": "INC0000001", - "partnerIncidentId": "12345", - "short_description": "descriptive text", - "state": 1, - "opened_at": "1997-09-08T05:55:00Z", - "sys_updated_on": "2024-07-17T14:36:59Z", - "u_current_workplace": "workplace 123", - "opened_by": { - "first_name": "Example", - "last_name": "Name", - "user_name": "example_name" + example: + { + 'incidentId': '6d101e0487e3ca903ef00000000000', + 'number': 'INC0000001', + 'partnerIncidentId': '12345', + 'short_description': 'descriptive text', + 'state': 1, + 'opened_at': '1997-09-08T05:55:00Z', + 'sys_updated_on': '2024-07-17T14:36:59Z', + 'u_current_workplace': 'workplace 123', + 'opened_by': + { + 'first_name': 'Example', + 'last_name': 'Name', + 'user_name': 'example_name' + }, + 'assignment_group': + { + 'description': 'Example group', + 'name': 'Example groupname' }, - "assignment_group": { - "description": "Example group", - "name": "Example groupname" - }, - "causing_ci": { - "asset_tag": "123456789", - "model_id": { - "display_name": "Lenovo ThinkPad P16 Gen1", - "name": "ThinkPad P16 Gen1", - "sys_id": "70a44cbf87f739d06d000000000000", + 'causing_ci': + { + 'asset_tag': '123456789', + 'model_id': + { + 'display_name': 'Lenovo ThinkPad P16 Gen1', + 'name': 'ThinkPad P16 Gen1', + 'sys_id': '70a44cbf87f739d06d000000000000' + }, + 'name': 'example hostname', + 'operational_status': 1, + 'serial_number': 'ABCD12345', + 'sys_id': 'acba0c3f87ff75503ef0000000000000' }, - "name": "example hostname", - "operational_status": 1, - "serial_number": "ABCD12345", - "sys_id": "acba0c3f87ff75503ef0000000000000", - }, - "attachments": [ - { - "filename": "thisIsAFileName.pdf", - "content_type": "application/pdf", - "download_url": "https:///sys_attachment.do?sys_id=12f0297d87544e12334567890000000", - "sys_id": "12f0297d87544e12334567890000000" - } - ] - } + 'attachments': + [ + { + 'filename': 'thisIsAFileName.pdf', + 'content_type': 'application/pdf', + 'download_url': 'https:///sys_attachment.do?sys_id=12f0297d87544e12334567890000000', + 'sys_id': '12f0297d87544e12334567890000000' + } + ], + 'worknotes': + [ + { + 'element': 'comments', + 'sys_created_by': 'technical_user_xyz', + 'sys_created_on': '2024-11-29T14:24:25Z', + 'sys_id': '33defc09876612d06dc8635400000000', + 'value': 'this is a comment' + }, + { + 'element': 'work_notes', + 'sys_created_by': 'technical_user_xyz', + 'sys_created_on': '2024-11-29T12:18:56Z', + 'sys_id': '7c32be1b87de5e103efcec2300000001', + 'value': 'this is a worknote' + } + ] + } '400': description: bad request - content: + content: application/json: schema: type: object properties: error: type: object - example: "MyItRestException" + example: 'MyItRestException' message: type: string example: "'partnerId' not specified" @@ -315,21 +364,22 @@ paths: example: 400 '401': description: unauthorized - content: + content: application/json: schema: type: object properties: error: type: object - example: { - "message": "User Not Authenticated", - "detail": "Required to provide Auth information" - } + example: + { + 'message': 'User Not Authenticated', + 'detail': 'Required to provide Auth information' + } status: type: string - example: "failure" - + example: 'failure' + patch: summary: update an incident description: updates an incident that already exists in myIT. 'partnerId' AND 'incidentId' OR 'partnerIncidentId' must either be in the body or the query params. @@ -341,7 +391,7 @@ paths: properties: partnerId: description: the id of the partner system, agreed upon with the MyIT team. - example: "SystemX" + example: 'SystemX' type: string incidentId: description: The MyIT-internal id of the incident. @@ -349,7 +399,7 @@ paths: type: string partnerIncidentId: description: your internal id of the incident, for your reference. Note that this must be unique. Once an incident is closed however - the id is freed up again. - example: "1234567890" + example: '1234567890' type: string short_description: type: string @@ -371,67 +421,74 @@ paths: properties: metadata: type: object - example: { - "config": "SystemX", - "partnerId": "SystemX", - "server_system_time": "2020-10-24T06:23:41.089Z" - } + example: + { + 'config': 'SystemX', + 'partnerId': 'SystemX', + 'server_system_time': '2020-10-24T06:23:41.089Z' + } message: type: string - example: "Incident 43c569a98771f5106dc8630000000000 updated." + example: 'Incident 43c569a98771f5106dc8630000000000 updated.' data: type: object - example: { - "incidentId": "6d101e0487e3ca903ef00000000000", - "number": "INC0000001", - "partnerIncidentId": "1234567890", - "short_description": "this is an updated description of the problem", - "state": 1, - "opened_at": "1997-09-08T05:55:00Z", - "sys_updated_on": "2024-07-17T14:36:59Z", - "opened_by": { - "first_name": "Example", - "last_name": "Name", - "user_name": "example_name" + example: + { + 'incidentId': '6d101e0487e3ca903ef00000000000', + 'number': 'INC0000001', + 'partnerIncidentId': '1234567890', + 'short_description': 'this is an updated description of the problem', + 'state': 1, + 'opened_at': '1997-09-08T05:55:00Z', + 'sys_updated_on': '2024-07-17T14:36:59Z', + 'opened_by': + { + 'first_name': 'Example', + 'last_name': 'Name', + 'user_name': 'example_name' }, - "assignment_group": { - "description": "Example group", - "name": "Example groupname" - }, - "causing_ci": { - "asset_tag": "123456789", - "model_id": { - "display_name": "Lenovo ThinkPad P16 Gen1", - "name": "ThinkPad P16 Gen1", - "sys_id": "70a44cbf87f739d06d000000000000", + 'assignment_group': + { + 'description': 'Example group', + 'name': 'Example groupname' }, - "name": "example hostname", - "operational_status": 1, - "serial_number": "ABCD12345", - "sys_id": "acba0c3f87ff75503ef0000000000000", - }, - "attachments": [ - { - "filename": "thisIsAFileName.pdf", - "content_type": "application/pdf", - "download_url": "https:///sys_attachment.do?sys_id=12f0297d87544e12334567890000000", - "sys_id": "12f0297d87544e12334567890000000" - } - ] - } + 'causing_ci': + { + 'asset_tag': '123456789', + 'model_id': + { + 'display_name': 'Lenovo ThinkPad P16 Gen1', + 'name': 'ThinkPad P16 Gen1', + 'sys_id': '70a44cbf87f739d06d000000000000' + }, + 'name': 'example hostname', + 'operational_status': 1, + 'serial_number': 'ABCD12345', + 'sys_id': 'acba0c3f87ff75503ef0000000000000' + }, + 'attachments': + [ + { + 'filename': 'thisIsAFileName.pdf', + 'content_type': 'application/pdf', + 'download_url': 'https:///sys_attachment.do?sys_id=12f0297d87544e12334567890000000', + 'sys_id': '12f0297d87544e12334567890000000' + } + ] + } '400': description: bad request - content: + content: application/json: schema: type: object properties: name: type: string - example: "MyItRestException" + example: 'MyItRestException' message: type: string example: "'partnerId' not specified" @@ -440,20 +497,21 @@ paths: example: 400 '401': description: unauthorized - content: + content: application/json: schema: type: object properties: error: type: object - example: { - "message": "User Not Authenticated", - "detail": "Required to provide Auth information" - } + example: + { + 'message': 'User Not Authenticated', + 'detail': 'Required to provide Auth information' + } status: type: string - example: "failure" + example: 'failure' /incident/addAttachment: patch: @@ -467,7 +525,7 @@ paths: properties: partnerId: description: the id of the partner system, agreed upon with the MyIT team. - example: "SystemX" + example: 'SystemX' type: string incidentId: description: The MyIT-internal id of the incident. @@ -475,7 +533,7 @@ paths: type: string partnerIncidentId: description: your internal id of the incident, for your reference. Note that this must be unique. Once an incident is closed however - the id is freed up again. - example: "1234567890" + example: '1234567890' type: string attachments: description: any attachments you'd like to add to the incident. The content must be base64 encoded. @@ -485,11 +543,11 @@ paths: properties: fileName: description: the name of the file - example: "picture_of_the_problem.png" + example: 'picture_of_the_problem.png' type: string content_type: description: the mime type of the file - example: "image/png" + example: 'image/png' type: string content: type: string @@ -507,78 +565,82 @@ paths: properties: metadata: type: object - example: { - "Caveat": "THIS IS PRE-ALPHA CODE AND SUBJECT TO CHANGE AT ANY TIM(E)!", - "git": "IncidentRestApi-0.0.1+70-dd86b01-dirty", - "build": "2023-10-24T14:54:24.706Z", - "config": "systemId", - "partnerId": "systemId", - "server_system_time": "2023-10-27T07:02:46.583Z" - } + example: + { + 'Caveat': 'THIS IS PRE-ALPHA CODE AND SUBJECT TO CHANGE AT ANY TIM(E)!', + 'git': 'IncidentRestApi-0.0.1+70-dd86b01-dirty', + 'build': '2023-10-24T14:54:24.706Z', + 'config': 'systemId', + 'partnerId': 'systemId', + 'server_system_time': '2023-10-27T07:02:46.583Z' + } message: type: string - example: "Attachment(s) added to Incident 43c569a98771f5106dc8630000000000." + example: 'Attachment(s) added to Incident 43c569a98771f5106dc8630000000000.' data: type: object - example: { - "number": "INC0000001", - "short_description": "short description", - "priority": 4, - "opened_by:": { - "active": true, - "sys_class_name": "sys_user", - "sys_id": "a6fb235587fc71503efcec000000000" + example: + { + 'number': 'INC0000001', + 'short_description': 'short description', + 'priority': 4, + 'opened_by:': + { + 'active': true, + 'sys_class_name': 'sys_user', + 'sys_id': 'a6fb235587fc71503efcec000000000' }, - "severity": 3, - "opened_at": "2023-10-10T07:22:04Z", - "category": "service_request", - "incident_id": "43c569a98771f5106dc8630000000000", - "class": "incident", - "attachments": [ + 'severity': 3, + 'opened_at': '2023-10-10T07:22:04Z', + 'category': 'service_request', + 'incident_id': '43c569a98771f5106dc8630000000000', + 'class': 'incident', + 'attachments': + [ { - "filename": "thisIsAFileName.txt", - "content_type": "application/json", - "download_url": "https:///sys_attachment.do?sys_id=af0192da874481234567890123456789", - "sys_id": "af0192da874481234567890123456789" + 'filename': 'thisIsAFileName.txt', + 'content_type': 'application/json', + 'download_url': 'https:///sys_attachment.do?sys_id=af0192da874481234567890123456789', + 'sys_id': 'af0192da874481234567890123456789' } ] - - } + } '400': description: bad request - content: + content: application/json: schema: type: object properties: name: type: string - example: "MyItRestException" + example: 'MyItRestException' message: type: string - example: "content of attachment thisIsAFileName.txt is not valid base64." + example: 'content of attachment thisIsAFileName.txt is not valid base64.' status: type: integer example: 400 '401': description: unauthorized - content: + content: application/json: schema: type: object properties: error: type: object - example: { - "message": "User Not Authenticated", - "detail": "Required to provide Auth information" - } + example: + { + 'message': 'User Not Authenticated', + 'detail': 'Required to provide Auth information' + } status: type: string - example: "failure" + example: 'failure' /incident/addWorknote: patch: @@ -609,77 +671,90 @@ paths: properties: metadata: type: object - example: { - "Caveat": "THIS IS PRE-ALPHA CODE AND SUBJECT TO CHANGE AT ANY TIM(E)!", - "git": "IncidentRestApi-0.0.1+70-dd86b01-dirty", - "build": "2023-10-24T14:54:24.706Z", - "config": "systemId", - "partnerId": "systemId", - "server_system_time": "2023-10-27T07:02:46.583Z" - } + example: + { + 'Caveat': 'THIS IS PRE-ALPHA CODE AND SUBJECT TO CHANGE AT ANY TIM(E)!', + 'git': 'IncidentRestApi-0.0.1+70-dd86b01-dirty', + 'build': '2023-10-24T14:54:24.706Z', + 'config': 'systemId', + 'partnerId': 'systemId', + 'server_system_time': '2023-10-27T07:02:46.583Z' + } message: type: string - example: "Worknote added to incident 43c569a98771f5106dc8630000000000." + example: 'Worknote added to incident 43c569a98771f5106dc8630000000000.' data: type: object - example: { - "number": "INC0000001", - "short_description": "short description", - "priority": 4, - "opened_by:": { - "active": true, - "sys_class_name": "sys_user", - "sys_id": "a6fb235587fc71503efcec000000000" + example: + { + 'number': 'INC0000001', + 'short_description': 'short description', + 'priority': 4, + 'opened_by:': + { + 'active': true, + 'sys_class_name': 'sys_user', + 'sys_id': 'a6fb235587fc71503efcec000000000' }, - "severity": 3, - "opened_at": "2023-10-10T07:22:04Z", - "category": "service_request", - "incident_id": "43c569a98771f5106dc8630000000000", - "class": "incident", - "worknotes": [ + 'severity': 3, + 'opened_at': '2023-10-10T07:22:04Z', + 'category': 'service_request', + 'incident_id': '43c569a98771f5106dc8630000000000', + 'class': 'incident', + 'worknotes': + [ + { + 'element': 'comments', + 'sys_created_by': 'technical_user_xyz', + 'sys_created_on': '2024-11-29T14:24:25Z', + 'sys_id': '33defc09876612d06dc8635400000000', + 'value': 'this is a comment' + }, { - "sys_id" : "ta6fb235587fc71503efcec000000123", - "sys_created_by" : "admin.user", - "sys_created_on" : "2024-01-24T06:29:35Z", - "value" : "worknote detailing progress on incident\r\nTest" + 'element': 'work_notes', + 'sys_created_by': 'technical_user_xyz', + 'sys_created_on': '2024-11-29T12:18:56Z', + 'sys_id': '7c32be1b87de5e103efcec2300000001', + 'value': 'this is a worknote' } ] - } + } '400': description: bad request - content: + content: application/json: schema: type: object properties: name: type: string - example: "MyItRestException" + example: 'MyItRestException' message: type: string - example: "No worknote found in request body." + example: 'No worknote found in request body.' status: type: integer example: 400 '401': description: unauthorized - content: + content: application/json: schema: type: object properties: error: type: object - example: { - "message": "User Not Authenticated", - "detail": "Required to provide Auth information" - } + example: + { + 'message': 'User Not Authenticated', + 'detail': 'Required to provide Auth information' + } status: type: string - example: "failure" + example: 'failure' /incident/addComment: patch: @@ -710,78 +785,91 @@ paths: properties: metadata: type: object - example: { - "Caveat": "THIS IS PRE-ALPHA CODE AND SUBJECT TO CHANGE AT ANY TIM(E)!", - "git": "IncidentRestApi-0.0.1+70-dd86b01-dirty", - "build": "2023-10-24T14:54:24.706Z", - "config": "systemId", - "partnerId": "systemId", - "server_system_time": "2023-10-27T07:02:46.583Z" - } + example: + { + 'Caveat': 'THIS IS PRE-ALPHA CODE AND SUBJECT TO CHANGE AT ANY TIM(E)!', + 'git': 'IncidentRestApi-0.0.1+70-dd86b01-dirty', + 'build': '2023-10-24T14:54:24.706Z', + 'config': 'systemId', + 'partnerId': 'systemId', + 'server_system_time': '2023-10-27T07:02:46.583Z' + } message: type: string - example: "Comment added to incident 43c569a98771f5106dc8630000000000." + example: 'Comment added to incident 43c569a98771f5106dc8630000000000.' data: type: object - example: { - "number": "INC0000001", - "short_description": "short description", - "priority": 4, - "opened_by:": { - "active": true, - "sys_class_name": "sys_user", - "sys_id": "a6fb235587fc71503efcec000000000" + example: + { + 'number': 'INC0000001', + 'short_description': 'short description', + 'priority': 4, + 'opened_by:': + { + 'active': true, + 'sys_class_name': 'sys_user', + 'sys_id': 'a6fb235587fc71503efcec000000000' }, - "severity": 3, - "opened_at": "2023-10-10T07:22:04Z", - "category": "service_request", - "incident_id": "43c569a98771f5106dc8630000000000", - "class": "incident", - "comments": [ + 'severity': 3, + 'opened_at': '2023-10-10T07:22:04Z', + 'category': 'service_request', + 'incident_id': '43c569a98771f5106dc8630000000000', + 'class': 'incident', + 'worknotes': + [ + { + 'element': 'comments', + 'sys_created_by': 'technical_user_xyz', + 'sys_created_on': '2024-11-29T14:24:25Z', + 'sys_id': '33defc09876612d06dc8635400000000', + 'value': 'this is a comment' + }, { - "sys_id" : "ta6fb235587fc71503efcec000000123", - "sys_created_by" : "admin.user", - "sys_created_on" : "2024-01-24T06:29:35Z", - "value" : "Customer-facing comment, detailing progress on incident\r\nTest" + 'element': 'work_notes', + 'sys_created_by': 'technical_user_xyz', + 'sys_created_on': '2024-11-29T12:18:56Z', + 'sys_id': '7c32be1b87de5e103efcec2300000001', + 'value': 'this is a worknote' } ] - } + } '400': description: bad request - content: + content: application/json: schema: type: object properties: name: type: string - example: "MyItRestException" + example: 'MyItRestException' message: type: string - example: "comment must be of type string." + example: 'comment must be of type string.' status: type: integer example: 400 '401': description: unauthorized - content: + content: application/json: schema: type: object properties: error: type: object - example: { - "message": "User Not Authenticated", - "detail": "Required to provide Auth information" - } + example: + { + 'message': 'User Not Authenticated', + 'detail': 'Required to provide Auth information' + } status: type: string - example: "failure" - + example: 'failure' + /incident/resolve: patch: summary: resolve an incident @@ -806,7 +894,6 @@ paths: - partnerIncidentId - worknote - responses: '200': description: the resolved incident @@ -817,77 +904,90 @@ paths: properties: metadata: type: object - example: { - "Caveat": "THIS IS PRE-ALPHA CODE AND SUBJECT TO CHANGE AT ANY TIM(E)!", - "git": "IncidentRestApi-0.0.1+70-dd86b01-dirty", - "build": "2023-10-24T14:54:24.706Z", - "config": "systemId", - "partnerId": "systemId", - "server_system_time": "2023-10-27T07:02:46.583Z" - } + example: + { + 'Caveat': 'THIS IS PRE-ALPHA CODE AND SUBJECT TO CHANGE AT ANY TIM(E)!', + 'git': 'IncidentRestApi-0.0.1+70-dd86b01-dirty', + 'build': '2023-10-24T14:54:24.706Z', + 'config': 'systemId', + 'partnerId': 'systemId', + 'server_system_time': '2023-10-27T07:02:46.583Z' + } message: type: string - example: "Incident 43c569a98771f5106dc8630000000000 resolved." + example: 'Incident 43c569a98771f5106dc8630000000000 resolved.' data: type: object - example: { - "number": "INC0000001", - "short_description": "short description", - "priority": 4, - "opened_by:": { - "active": true, - "sys_class_name": "sys_user", - "sys_id": "a6fb235587fc71503efcec000000000" + example: + { + 'number': 'INC0000001', + 'short_description': 'short description', + 'priority': 4, + 'opened_by:': + { + 'active': true, + 'sys_class_name': 'sys_user', + 'sys_id': 'a6fb235587fc71503efcec000000000' }, - "severity": 3, - "opened_at": "2023-10-10T07:22:04Z", - "category": "service_request", - "incident_id": "43c569a98771f5106dc8630000000000", - "class": "incident", - "worknotes": [ + 'severity': 3, + 'opened_at': '2023-10-10T07:22:04Z', + 'category': 'service_request', + 'incident_id': '43c569a98771f5106dc8630000000000', + 'class': 'incident', + 'worknotes': + [ + { + 'element': 'comments', + 'sys_created_by': 'technical_user_xyz', + 'sys_created_on': '2024-11-29T14:24:25Z', + 'sys_id': '33defc09876612d06dc8635400000000', + 'value': 'this is a comment' + }, { - "sys_id" : "ta6fb235587fc71503efcec000000123", - "sys_created_by" : "admin.user", - "sys_created_on" : "2024-01-24T06:29:35Z", - "value" : "reason for reopening incident\r\nTest" + 'element': 'work_notes', + 'sys_created_by': 'technical_user_xyz', + 'sys_created_on': '2024-11-29T12:18:56Z', + 'sys_id': '7c32be1b87de5e103efcec2300000001', + 'value': 'this is a worknote' } ] - } + } '400': description: bad request - content: + content: application/json: schema: type: object properties: name: type: string - example: "MyItRestException" + example: 'MyItRestException' message: type: string - example: "No worknote found in request body." + example: 'No worknote found in request body.' status: type: integer example: 400 '401': description: unauthorized - content: + content: application/json: schema: type: object properties: error: type: object - example: { - "message": "User Not Authenticated", - "detail": "Required to provide Auth information" - } + example: + { + 'message': 'User Not Authenticated', + 'detail': 'Required to provide Auth information' + } status: type: string - example: "failure" + example: 'failure' /incident/reopen: patch: @@ -913,7 +1013,6 @@ paths: - partnerIncidentId - worknote - responses: '200': description: the reopened incident @@ -924,77 +1023,90 @@ paths: properties: metadata: type: object - example: { - "Caveat": "THIS IS PRE-ALPHA CODE AND SUBJECT TO CHANGE AT ANY TIM(E)!", - "git": "IncidentRestApi-0.0.1+70-dd86b01-dirty", - "build": "2023-10-24T14:54:24.706Z", - "config": "systemId", - "partnerId": "systemId", - "server_system_time": "2023-10-27T07:02:46.583Z" - } + example: + { + 'Caveat': 'THIS IS PRE-ALPHA CODE AND SUBJECT TO CHANGE AT ANY TIM(E)!', + 'git': 'IncidentRestApi-0.0.1+70-dd86b01-dirty', + 'build': '2023-10-24T14:54:24.706Z', + 'config': 'systemId', + 'partnerId': 'systemId', + 'server_system_time': '2023-10-27T07:02:46.583Z' + } message: type: string - example: "Incident 43c569a98771f5106dc8630000000000 reopened." + example: 'Incident 43c569a98771f5106dc8630000000000 reopened.' data: type: object - example: { - "number": "INC0000001", - "short_description": "short description", - "priority": 4, - "opened_by:": { - "active": true, - "sys_class_name": "sys_user", - "sys_id": "a6fb235587fc71503efcec000000000" + example: + { + 'number': 'INC0000001', + 'short_description': 'short description', + 'priority': 4, + 'opened_by:': + { + 'active': true, + 'sys_class_name': 'sys_user', + 'sys_id': 'a6fb235587fc71503efcec000000000' }, - "severity": 3, - "opened_at": "2023-10-10T07:22:04Z", - "category": "service_request", - "incident_id": "43c569a98771f5106dc8630000000000", - "class": "incident", - "worknotes": [ + 'severity': 3, + 'opened_at': '2023-10-10T07:22:04Z', + 'category': 'service_request', + 'incident_id': '43c569a98771f5106dc8630000000000', + 'class': 'incident', + 'worknotes': + [ + { + 'element': 'comments', + 'sys_created_by': 'technical_user_xyz', + 'sys_created_on': '2024-11-29T14:24:25Z', + 'sys_id': '33defc09876612d06dc8635400000000', + 'value': 'this is a comment' + }, { - "sys_id" : "ta6fb235587fc71503efcec000000123", - "sys_created_by" : "admin.user", - "sys_created_on" : "2024-01-24T06:29:35Z", - "value" : "reason for reopening incident\r\nTest" + 'element': 'work_notes', + 'sys_created_by': 'technical_user_xyz', + 'sys_created_on': '2024-11-29T12:18:56Z', + 'sys_id': '7c32be1b87de5e103efcec2300000001', + 'value': 'this is a worknote' } ] - } + } '400': description: bad request - content: + content: application/json: schema: type: object properties: name: type: string - example: "MyItRestException" + example: 'MyItRestException' message: type: string - example: "No worknote found in request body." + example: 'No worknote found in request body.' status: type: integer example: 400 '401': description: unauthorized - content: + content: application/json: schema: type: object properties: error: type: object - example: { - "message": "User Not Authenticated", - "detail": "Required to provide Auth information" - } + example: + { + 'message': 'User Not Authenticated', + 'detail': 'Required to provide Auth information' + } status: type: string - example: "failure" + example: 'failure' /callback: post: @@ -1009,16 +1121,16 @@ paths: properties: metaData: type: string - example: "The incident has changed. This is the newest state:" + example: 'The incident has changed. This is the newest state:' number: type: string - example: "INC0000001" + example: 'INC0000001' time_worked: type: string - example: "1970-01-01 01:54:46" + example: '1970-01-01 01:54:46' short_description: type: string - example: "update" + example: 'update' priority: type: number example: 1 @@ -1027,16 +1139,16 @@ paths: example: 2 opened_at: type: string - example: "2023-11-23T09:16:47Z" + example: '2023-11-23T09:16:47Z' category: type: string - example: "service_request" + example: 'service_request' incident_id: type: string - example: "f806607f87a6f9d03efcec0000000000" + example: 'f806607f87a6f9d03efcec0000000000' class: type: string - example: "incident" + example: 'incident' responses: '200': description: Callback request description. Actual response handling is managed by the receiving system. @@ -1070,4 +1182,3 @@ components: BasicAuth: type: http scheme: basic -