Incident REST API (1.0.0)

Download OpenAPI specification:Download

handles communication between the MyIT incident system and partner systems.

create a new incident

creates a new incident in myIT and returns said incident.

Authorizations:

BasicAuth

Request Body schema: application/json

The values to intially write to the incident.

partnerId required	string the id of the partner system, agreed upon with the MyIT team.
partnerIncidentId required	string 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.
channel required	string 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'.
description required	string the descriptive title of the incident.
short_description required	string the description of the incident, describing the situation in detail.
location	string the name or sys-id of the concerned location. If you don't know what to put here, please ask your swisspost contact.
cmdb_ci	string the name or sys-id of the concerned configuration item. If you don't know what to put here, please ask your swisspost contact.
causing_ci	string 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'.
	Array of objects any attachments you'd like to add to the incident. The content must be base64 encoded.

Responses

Request samples

Payload

Content type

application/json

{"partnerId": "SystemX",
"partnerIncidentId": "1234567890",
"channel": "vendor",
"description": "Some problem with something",
"short_description": "There is a complicated problem with the incident rest api - HELP!",
"location": "afeeadcb8776c6103efc00000000",
"cmdb_ci": "w010xq",
"causing_ci": "w010xq",
"attachments": [{"fileName": "picture_of_the_problem.png",
"content_type": "image/png",
"content": "c25lYWt5"
}
]
}

Response samples

200
400
401
500

Content type

application/json

{"metadata": {"config": "SystemX",
"partnerId": "SystemX",
"server_system_time": "2020-10-24T06:23:41.089Z"
},
"message": "Incident 00000000000000000000000000000001 created.",
"data": {"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"
},
"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"
},
"name": "example hostname",
"operational_status": 1,
"serial_number": "ABCD12345",
"sys_id": "acba0c3f87ff75503ef0000000000000"
},
"attachments": [{"filename": "thisIsAFileName.pdf",
"content_type": "application/pdf",
"download_url": "https://<MyIT-url>/sys_attachment.do?sys_id=12f0297d87544e12334567890000000",
"sys_id": "12f0297d87544e12334567890000000"
},
{"filename": "picture_of_the_problem.png",
"content_type": "image/png",
"download_url": "https://<MyIT-url>/sys_attachment.do?sys_id=12f0297d87544e12334567890000001",
"sys_id": "12f0297d87544e12334567890000001"
}
]
}
}

fetch an existing incident

Requires 'partnerId' AND either 'incidentId' OR 'partnerIncidentId' and returns the corresponding incident.

Authorizations:

BasicAuth

query Parameters

partnerId required	string Example: partnerId=SystemX The id of the partner system, to be agreed upon with the MyIT team.
incidentId required	string Example: incidentId=6d101e0487e3ca903ef00000000000 The MyIT-internal id of the incident.
partnerIncidentId required	string Example: partnerIncidentId=1234567890 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.

Responses

Response samples

200
400
401

Content type

application/json

{"metadata": {"config": "SystemX",
"partnerId": "SystemX",
"server_system_time": "2020-10-24T06:23:41.089Z"
},
"data": {"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"
},
"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://<MyIT-url>/sys_attachment.do?sys_id=12f0297d87544e12334567890000000",
"sys_id": "12f0297d87544e12334567890000000"
}
]
}
}

update an incident

updates an incident that already exists in myIT. 'partnerId' AND 'incidentId' OR 'partnerIncidentId' must either be in the body or the query params.

Authorizations:

BasicAuth

Request Body schema: application/json

partnerId required	string the id of the partner system, agreed upon with the MyIT team.
incidentId required	string The MyIT-internal id of the incident.
partnerIncidentId required	string 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.
short_description	string example field to update

Responses

Request samples

Payload

Content type

application/json

{"partnerId": "SystemX",
"incidentId": "43c569a98771f5106dc8630000000000",
"partnerIncidentId": "1234567890",
"short_description": "this is an updated description of the problem"
}

Response samples

200
400
401

Content type

application/json

{"metadata": {"config": "SystemX",
"partnerId": "SystemX",
"server_system_time": "2020-10-24T06:23:41.089Z"
},
"message": "Incident 43c569a98771f5106dc8630000000000 updated.",
"data": {"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"
},
"name": "example hostname",
"operational_status": 1,
"serial_number": "ABCD12345",
"sys_id": "acba0c3f87ff75503ef0000000000000"
},
"attachments": [{"filename": "thisIsAFileName.pdf",
"content_type": "application/pdf",
"download_url": "https://<MyIT-url>/sys_attachment.do?sys_id=12f0297d87544e12334567890000000",
"sys_id": "12f0297d87544e12334567890000000"
}
]
}
}

add attachments

adds attachments to an incident that already exists in myIT. 'partnerId' AND either 'incidentId' OR 'partnerIncidentId' must either be in the body or the query params. Any attachments must be base64 encoded.

Authorizations:

BasicAuth

Request Body schema: application/json

partnerId	string the id of the partner system, agreed upon with the MyIT team.
incidentId	string The MyIT-internal id of the incident.
partnerIncidentId	string 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.
	Array of objects any attachments you'd like to add to the incident. The content must be base64 encoded.

Responses

Request samples

Payload

Content type

application/json

{"partnerId": "SystemX",
"incidentId": "6d101e0487e3ca903ef00000000000",
"partnerIncidentId": "1234567890",
"attachments": [{"fileName": "picture_of_the_problem.png",
"content_type": "image/png",
"content": "c25lYWt5"
}
]
}

Response samples

200
400
401

Content type

application/json

{"metadata": {"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": "Attachment(s) added to Incident 43c569a98771f5106dc8630000000000.",
"data": {"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": [{"filename": "thisIsAFileName.txt",
"content_type": "application/json",
"download_url": "https://<MyIT-url>/sys_attachment.do?sys_id=af0192da874481234567890123456789",
"sys_id": "af0192da874481234567890123456789"
}
]
}
}

add a worknote

adds a worknote to an incident that already exists in myIT. PartnerId AND either IncidentId OR partnerIncidentId must either be in the body or the query params.

Authorizations:

BasicAuth

Request Body schema: application/json

partnerId	string
incidentId	string
partnerIncidentId	string
worknote	string

Responses

Request samples

Payload

Content type

application/json

{"partnerId": "string",
"incidentId": "string",
"partnerIncidentId": "string",
"worknote": "string"
}

Response samples

200
400
401

Content type

application/json

{"metadata": {"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": "Worknote added to incident 43c569a98771f5106dc8630000000000.",
"data": {"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": [{"sys_id": "ta6fb235587fc71503efcec000000123",
"sys_created_by": "admin.user",
"sys_created_on": "2024-01-24T06:29:35Z",
"value": "worknote detailing progress on incident\r\nTest"
}
]
}
}

add a comment

adds a comment to an incident that already exists in myIT. 'partnerId' AND either 'incidentId' OR 'partnerIncidentId' must either be in the body or the query params.

Authorizations:

BasicAuth

Request Body schema: application/json

partnerId	string
incidentId	string
partnerIncidentId	string
comment	string

Responses

Request samples

Payload

Content type

application/json

{"partnerId": "string",
"incidentId": "string",
"partnerIncidentId": "string",
"comment": "string"
}

Response samples

200
400
401

Content type

application/json

{"metadata": {"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": "Comment added to incident 43c569a98771f5106dc8630000000000.",
"data": {"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": [{"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"
}
]
}
}

resolve an incident

resolves an incident in myIT. Requires a worknote. PartnerId AND either IncidentId OR partnerIncidentId must either be in the body or the query params.

Authorizations:

BasicAuth

Request Body schema: application/json

partnerId required	string
incidentId required	string
partnerIncidentId required	string
worknote required	string

Responses

Request samples

Payload

Content type

application/json

{"partnerId": "string",
"incidentId": "string",
"partnerIncidentId": "string",
"worknote": "string"
}

Response samples

200
400
401

Content type

application/json

{"metadata": {"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": "Incident 43c569a98771f5106dc8630000000000 resolved.",
"data": {"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": [{"sys_id": "ta6fb235587fc71503efcec000000123",
"sys_created_by": "admin.user",
"sys_created_on": "2024-01-24T06:29:35Z",
"value": "reason for reopening incident\r\nTest"
}
]
}
}

reopen an incident

Reopens an incident in myIT that has status 'resolved'. Requires a worknote. PartnerId AND either IncidentId OR partnerIncidentId must either be in the body or the query params.

Authorizations:

BasicAuth

Request Body schema: application/json

partnerId required	string
incidentId required	string
partnerIncidentId required	string
worknote required	string

Responses

Request samples

Payload

Content type

application/json

{"partnerId": "string",
"incidentId": "string",
"partnerIncidentId": "string",
"worknote": "string"
}

Response samples

200
400
401

Content type

application/json

{"metadata": {"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": "Incident 43c569a98771f5106dc8630000000000 reopened.",
"data": {"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": [{"sys_id": "ta6fb235587fc71503efcec000000123",
"sys_created_by": "admin.user",
"sys_created_on": "2024-01-24T06:29:35Z",
"value": "reason for reopening incident\r\nTest"
}
]
}
}

Notification via POST request

Sends a POST request to the partner's callback URL when an incident changes containing the complete incident.

Authorizations:

BasicAuth

Request Body schema: application/json

The incident data sent to the callback URL.

metaData	string
number	string
time_worked	string
short_description	string
priority	number
severity	number
opened_at	string
category	string
incident_id	string
class	string

Responses

Request samples

Payload

Content type

application/json

{"metaData": "The incident has changed. This is the newest state:",
"number": "INC0000001",
"time_worked": "1970-01-01 01:54:46",
"short_description": "update",
"priority": 1,
"severity": 2,
"opened_at": "2023-11-23T09:16:47Z",
"category": "service_request",
"incident_id": "f806607f87a6f9d03efcec0000000000",
"class": "incident"
}

Notification via GET request

Sends a GET request to the partner's callback URL with incidentId and callbackUrl as query parameters when an incident changes. This URL can be queried with GET to then receive the changed incident.

Authorizations:

BasicAuth

query Parameters

incidentId	string Example: incidentId=f806607f87a6f9d03efcec0000000000 The ID of the incident that changed.
callbackUrl	string Example: callbackUrl=https://<MyIT-url>/api/x_ssagd_inc_rest/rest/incident?partnerId=systemX&incidentId=f806607f87a6f9d03efcec0000000000 The readymade URL leading to the changed incident.