Technischer Support

Was tun, wenn's mal nicht so klappt?

Am Wichtigsten ist die qualifizierte Beschreibung und eindeutige Eingrenzung.
Ist sichergestellt, dass die Ursache ein Service von uns ist, kann mit der Erfassung der Support Anfrage begonnen werden. Eine klare Beschreibung erleichtert Nachvollziehbarkeit und rasche Lösungsfindung.

Wir helfen gerne!

Gestaltung Support Anfrage

Support Anfragen benötigen wenige, jedoch essenzielle Informationen.
Die wichtigsten Regeln sind:

Sprechender Titel (Subjekt)

Kurze und prägnant. Das betroffene Service und der Grund der Anfrage sollten daraus hervorgehen.

Zum Beispiel ist Datenbank mystore aus Firmen-LAN nicht erreichbar aussagekräftiger als ~~Ich kann nicht arbeiten~~.

EIN Thema = EIN Ticket

Unterschiedliche Themen (Probleme, Anfragen, ...) immer in ein eigenes Ticket.

Stellt sich später heraus, dass Tickets zusammen gehören, können wir diese mergen (zusammenfügen ist leichter als zu trennen).

Relevante Informationen

Die hier dargestellte Auflistung ist eine Empfehlung und kann - je nach Problemstellung - ergänzt oder auch gekürzt werden. Ein guter Ansatz ist alles zu senden, was man selbst - auf Experten-Ebene - zur Lösung des Problems erwarten würde. Dabei sollte man bedenken, dass der Ticketempfänger nicht anbei sitzt. Handlungen und/oder Austausch mit Kollegen (ein implizites Wissen) sind nicht bekannt.

Format der Meldung

Am besten ist einfacher, unformatierter Text!

Damit können wir das Verhalten reproduzieren, Inhalte für eigene Tests kopieren, ...
Screenshots nur dann, wenn sie dem besseren Verständnis dienen (und falls, dann bitte als PNG).

Zeitpunkt

Wann genau oder über welchen Zeitraum wurde die Aktion durchgeführt? Zeitangaben sollten im ISO 8601 Format (z.B. 2022-01-13T13:40:52+01:00) sein. Auf jeden Fall absolut, also mit Datum und Uhrzeit.

Relative Angaben wie gestern Abend, heut Morgen, ... sind nicht geeignet.

Client / Nutzer

Die meisten Services verlangen eine Authentifizierung. Der verwendet User (Client) ist relevant und sollte daher unbedingt angegeben werden.

Client bei APIs

Welche client_id und scopes wurden verwendet? Diese Angaben werden zusammen mit dem client_secret benötigt, um das access token zu generieren, das für den Zugriff auf die API benötigt wird. Geben Sie bitte nur die client_id und scopes an - nicht das client_secret oder access_token.

✅ Senden	❌ Nicht Senden
`client_id`	`client_secret`
`scopes`	`access_token`

Client IP

Von welcher public Client IP wurde die Aktion durchgeführt? Im lokalen Netz werden zumeist private IP Adressen vergeben. Wichtig ist nur jene, von der aus ins Internet geroutet wird. Private IP-Adressen wie bspw. 10.x.x.x, 172.x.x.x oder 192.168.x.x helfen also nicht weiter.

Sind mehrere Systeme in Verwendung (z.B. Load Balanced Cluster) sollte geprüft werden, ob das Problem auf allen Systemen besteht. In solchen Fällen liegt es meist an der Firewall.

Wie man die Public IP findet

Sie können Ihre public IP Adresse schnell online ermitteln.

Aktion / Request

Welche Aktion wurde durchgeführt - hier benötigen wir eine Beschreibung jener Schritte, die durchgeführt wurden. Wichtig sind hier nicht nur jene Aktion, die dann zum Fehler führte, sondern auch die davor durchgeführten einzelnen Aktionen der gesamten Transaktion.

Ideal ist es alle Schritte zu nennen, die eine einfache Reproduzierbarkeit des Fehlers ergeben. Damit nicht zusammenhängende Aktionen können weggelassen werden.

Request bei APIs

Welcher Request wurde gesendet? Benötigt werden HTTP Aufruf, Zieladresse (URL), Payload, Methode, ...

Wird lokal eine eigene Software eingesetzt, dann nur die tatsächlich abgeschickten Daten. Die meisten API Clients können die gesendeten Inhalte als Text anzeigen oder exportieren.

Beispiel für Request

Der genaue Request in HTTP Form oder der entsprechende cURL Aufruf sind am besten geeignet. Wichtig ist, dass der Request zuvor auch so selbst durchgeführt wurde!

### request new object
POST https://api.mystorage.at/v1/objects/
Accept: application/json
Content-Type: application/json
Authorization: Bearer {{auth_token}}

{"tenant": "mystore.baa", "entity": "foo"}

Zugangsdaten

Im Beispiel wird der Autorisierungs-Token genannt. Auch wenn dieser nach einer Zeit abläuft, bitte nicht übermitteln.

Response / Systemantwort

Wie hat der Service darauf reagiert, welche Antwort kam retour? Kam es zu einem Timeout, oder hat der Service eine qualifizierte Fehlermeldung geschickt?

Bei APIs empfiehlt es sich hier den exakten HTTP Response wiederzugeben!

Beispiel für Response

https://api.mystorage.at/v1/objects/345/

HTTP/1.1 401 Unauthorized
Date: Tue, 22 Mar 2022 11:12:06 GMT

{
"status_code": 401,
"message": "Unauthorized",
"detail": "Signature has expired.",
"hint": "Contact support"
}

Expectation / erwartete Antwort

Welches Ergebnis wurde erwartet, was hätte retour kommen sollen?

Hat der Server zwar mit 200 OK reagiert, aber die Antwort entsprach dennoch nicht der Erwartung. Was genau (z.B. welches Feld) hätte anders sein sollen?

Intention

Warum bzw. welcher Zweck sollte damit erreicht werden? Hier sollte eine nicht-technische Beschreibung stehen, aus der der Zweck der Aktion aus geschäftlicher Sicht hervorgeht, z.B.:

Wir wollen die Liste aller unserer Codes ziehen.

Wir benötigen 50 neue OAIDs.

Babelfish

Oft sind unternehmensintern oder in der Kommunikation mit Dritten andere Begriffe gebräuchlich. Falls nicht anders möglich sollten diese Begriffe erläutert und klar beschrieben werden.

Reproduzierbarkeit

Ist das Verhalten reproduzierbar? Um das Problem besser zu erkennen, bitte klären:

Tritt das unerwartete Verhalten bei einer bestimmten Anfrage oder bei mehreren Anfragen auf?
Welche Schritte führte zu der unerwarteten Antwort?

Dokumentation

Wurden Request und Response mit der Dokumentation verglichen. Gibt es zwischen dem Verhalten des Systems und der Dokumentation eine nicht nachvollziehbare Diskrepanz? Ist die Beschreibung zwar richtig, aber irreführend?

Eine Dokumentation ist im Gegensatz zu Code rasch geändert, also einfach her damit!

Vorlage

Im Dropdown sind die o.a. Punkte als Textvorlage enthalten. Über das Symbol rechts oben kann die Vorlage in die Zwischenablage kopiert werden.

Beschreibung als Vorlage

### ERKLÄRENDER TITEL / SUBJEKT ###

-- Handelt es sich um "EIN" Thema  --
-- Werden bekannte Begriffe und Bezeichnungen verwendet --

## Zeitpunkt

## Client / Nutzer

## Client IP

## Request / Schritte zum Fehler

## Response / tatsächliche Antwort des Systems

## Expectation / erwartete Antwort des Systems

## Intention

## Reproduzierbarkeit

## Verweis auf Dokumentation

Wohin mit der Anfrage?

Sobald alle Informationen zusammen sind bitte direkt an unser Support Ticket System senden. So ist sichergestellt, dass nichts verloren geht.

Ein weiterer Vorteil ist, dass so alle Tickets der Organisation einem selbst zur Verfügung stehen.