Incident REST API (1.0.0)

Download OpenAPI specification:

Handles communication between the MyIT incident system and partner systems.

State values:

New: 1
In progress: 2
On hold: 3
Resolved: 6
Closed: 7
Cancelled: 8

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"
}
],
"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"
}
]
}
}

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"
}
],
"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"
}
]
}
}

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",
"opened_by:": {"active": true,
"sys_class_name": "sys_user",
"sys_id": "a6fb235587fc71503efcec000000000"
},
"opened_at": "2023-10-10T07:22:04Z",
"incident_id": "43c569a98771f5106dc8630000000000",
"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",
"opened_by:": {"active": true,
"sys_class_name": "sys_user",
"sys_id": "a6fb235587fc71503efcec000000000"
},
"opened_at": "2023-10-10T07:22:04Z",
"category": "service_request",
"incident_id": "43c569a98771f5106dc8630000000000",
"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"
}
]
}
}

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",
"opened_by:": {"active": true,
"sys_class_name": "sys_user",
"sys_id": "a6fb235587fc71503efcec000000000"
},
"opened_at": "2023-10-10T07:22:04Z",
"incident_id": "43c569a98771f5106dc8630000000000",
"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"
}
]
}
}

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",
"opened_by:": {"active": true,
"sys_class_name": "sys_user",
"sys_id": "a6fb235587fc71503efcec000000000"
},
"opened_at": "2023-10-10T07:22:04Z",
"incident_id": "43c569a98771f5106dc8630000000000",
"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"
}
]
}
}

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",
"opened_by:": {"active": true,
"sys_class_name": "sys_user",
"sys_id": "a6fb235587fc71503efcec000000000"
},
"opened_at": "2023-10-10T07:22:04Z",
"incident_id": "43c569a98771f5106dc8630000000000",
"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"
}
]
}
}

Receive concise info on new or changed incidents.

Sends a POST request to an endpoint provided by the partnersystem containing a callback URL, the partnersystem can use to get the incident data in their own time.

Authorizations:

BasicAuth

Request Body schema: application/json

The incident data sent to the endpoint provided to us by the partnersystem.

incident_id	string The ID of the incident that changed.
callbackUrl	string The readymade URL leading to the changed incident.
action	string value describing what the causing action of the notification incidents. Possible values are 'new', 'update', 'worknote', 'comment', 'attachment', 'cancel'.

Responses

Request samples

Payload

Content type

application/json

{"incident_id": "f806607f87a6f9d03efcec0000000000",
"callbackUrl": "https://<MyIT-url>/api/x_ssagd_inc_rest/rest/incident?partnerId=systemX&incidentId=f806607f87a6f9d03efcec0000000000",
"action": "new"
}

Receive detailed info on new or changed incidents.

Sends a POST request to an endpoint provided by the partnersystem containing the new or changed incident data.

Authorizations:

BasicAuth

Request Body schema: application/json

The incident data sent to the endpoint provided to us by the partnersystem.

metaData	string
number	string
time_worked	string
short_description	string
opened_at	string
incident_id	string
action	string value describing what the causing action of the notification incidents. Possible values are 'new', 'update', 'worknote', 'comment', 'attachment', 'cancel'.

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",
"opened_at": "2023-11-23T09:16:47Z",
"incident_id": "f806607f87a6f9d03efcec0000000000",
"action": "new"
}