@manyos/smileconnect-api 1.28.0

package/docs/howto/incidents.md

@@ -0,0 +1,244 @@
+---
+layout: page
+title: Incident handling
+subtitle: In this guide you will learn to do the basic operations with an incident.
+use-site-title: true
+gh-badge: [star, fork, follow]
+gh-repo: daattali/beautiful-jekyll
+---
+
+In this guide we model the full lifecylce of a simple inbound API that delivers Incidents into your system. First we'll create one. We will then read it again and later resolve it. 
+
+# Create an Incident
+
+Let's assume we're an external system and we want to create incidents in the ITSM Suite.
+
+## Request Definition
+
+To create an incident you need to do a POST to the /v1/incidents endpoint of your API
+
+### URL
+
+*URL*: https://*api-fqdn*/v1/incidents
+
+*api-fqdn*: The hostname of your API Server
+
+### Headers
+
+*Content-Type*: application/json
+
+### Authorization
+
+*Type*: Bearer
+
+Use your [API Token](token.md)
+
+### Body
+
+Provide all your needed incident data (see mapping -> new Incident) within the *data* attribute.
+
+### Sample Request
+
+POST:https://*api-fqdn*/v1/incidents
+
+{% highlight json linenos %}
+{
+    "data": {
+        "summary": "New Incident",
+        "detailedDescription": "Here are the details"
+    }
+}
+{% endhighlight %}
+
+### Sample Response
+
+{% highlight json linenos %}
+{
+    "data": {
+        "id": "INC000000000217",
+        "opsCat1": null,
+        "opsCat2": null,
+        "opsCat3": null,
+        "resolutionCat1": null,
+        "resolutionCat2": null,
+        "resolutionCat3": null,
+        "prodCat1": null,
+        "prodCat2": null,
+        "prodCat3": null,
+        "productName": null,
+        "manufacturer": null,
+        "detailedDescription": "Here are the details",
+        "summary": "New Incident",
+        "statusReason": null,
+        "status": "Assigned",
+        "assignedGroup": "SGP000000000011",
+        "ownerGroup": "SGP000000000011",
+        "vendorGroup": null,
+        "customerId": "PPL000000000013",
+        "contactId": null,
+        "impact": "4-Minor/Localized",
+        "urgency": "4-Low",
+        "priority": "Low",
+        "vendorTicketId": null
+    },
+    "included": {
+        "persons": [
+            "PPL000000000013"
+        ],
+        "organisations": [],
+        "supportgroups": [
+            "SGP000000000011"
+        ]
+    }
+}
+{% endhighlight %}
+
+# Read an Incident
+
+We can query every incident we have access to with a simple get request.
+
+## Request Definition
+
+To read an incident you need to do a GET request to the /v1/incidents/*incidentId* endpoint of your API
+
+### URL
+
+*URL*: https://*api-fqdn*/v1/incidents/*incidentId*
+
+*api-fqdn*: The hostname of your API Server
+
+*incidentId*: The id of the incident you want to read.
+
+### Headers
+
+*Content-Type*: application/json
+
+### Authorization
+
+*Type*: Bearer
+
+Use your [API Token](token.md)
+
+### Sample Response
+
+GET:https://*api-fqdn*/v1/incidents/INC000000000217
+
+{% highlight json linenos %}
+{
+    "data": {
+        "id": "INC000000000217",
+        "opsCat1": null,
+        "opsCat2": null,
+        "opsCat3": null,
+        "resolutionCat1": null,
+        "resolutionCat2": null,
+        "resolutionCat3": null,
+        "prodCat1": null,
+        "prodCat2": null,
+        "prodCat3": null,
+        "productName": null,
+        "manufacturer": null,
+        "detailedDescription": "Here are the details",
+        "summary": "New Incident",
+        "statusReason": null,
+        "status": "Assigned",
+        "assignedGroup": "SGP000000000011",
+        "ownerGroup": "SGP000000000011",
+        "vendorGroup": null,
+        "customerId": "PPL000000000013",
+        "contactId": null,
+        "impact": "4-Minor/Localized",
+        "urgency": "4-Low",
+        "priority": "Low",
+        "vendorTicketId": null
+    },
+    "included": {
+        "persons": [
+            "PPL000000000013"
+        ],
+        "organisations": [],
+        "supportgroups": [
+            "SGP000000000011"
+        ]
+    }
+}
+{% endhighlight %}
+
+# Update an Incident
+
+You can update an Incident by sending a PUT request. Let's assume you want to resolve the incident that we created earlier. We need to set the status to "Resolved", provide a valid status reason and a Resolution.
+
+## Request Definition
+
+To up an incident you need to do a PUT to the /v1/incidents/*incidentId* endpoint of your API
+
+### URL
+
+*URL*: https://*api-fqdn*/v1/incidents/*incidentId*
+
+*api-fqdn*: The hostname of your API Server
+
+*incidentId*: Id of the incident that you want to update
+
+### Headers
+
+*Content-Type*: application/json
+
+### Authorization
+
+*Type*: Bearer
+
+Use your [API Token](token.md)
+
+### Body
+
+Provide all the attributes you want to update.
+
+### Sample Request
+
+PUT:https://*api-fqdn*/v1/incidents/INC000000000217
+
+{% highlight json linenos %}
+{
+    "data": {
+        "status": "Resolved",
+        "statusReason" : "No Further Action Required", 
+        "resolution": "Please restart your computer."
+    }
+}
+{% endhighlight %}
+
+### Sample Response
+
+{% highlight json linenos %}
+{
+    "data": {
+        "id": "INC000000000217",
+        "opsCat1": null,
+        "opsCat2": null,
+        "opsCat3": null,
+        "resolutionCat1": null,
+        "resolutionCat2": null,
+        "resolutionCat3": null,
+        "prodCat1": null,
+        "prodCat2": null,
+        "prodCat3": null,
+        "productName": null,
+        "manufacturer": null,
+        "detailedDescription": "Here are the details",
+        "summary": "New Incident",
+        "statusReason": "No Further Action Required",
+        "status": "Resolved",
+        "assignedGroup": "SGP000000000011",
+        "ownerGroup": "SGP000000000011",
+        "vendorGroup": null,
+        "customerId": "PPL000000000013",
+        "contactId": null,
+        "impact": "4-Minor/Localized",
+        "urgency": "4-Low",
+        "priority": "Low",
+        "vendorTicketId": null
+    },
+    "included": {}
+}
+{% endhighlight %}