Zum Inhalt

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 Tickets.

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önnne 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

Zur Nutzung der API ist ein Access-Token erforderlich. Dieser wird über das OAuth Service erzeugt. Dafür benötigt werden client_id, client_secret und Scopes. Zur besseren Nachvollziehbarkeit benötigen wir client_id und Scopes. Auf keinen Fall darf die client_secret übermittelt werden - ist ja schließlich geheim.

Access Token ist NICHT GLEICH der client_secret

Ein Beispiel für die Erzeugung des Access-Token Request findet sich hier.

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, 192.168.x.x oder 172.x.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.

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", "entitiy": "foo"}

Zugangsdaten

Im Beispiel wird der Autorisierungs-Token genannt. Auch wenn dieser nach einer Zeit abläuft, bitte nicht übermitteln. client_id und Scopes reichen aus. Oder - damit es wirklich vollständig ist - gleich den OAuth Request aber OHNE client_secret mit angeben!.

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äcuhlich. Falls nicht anders möglich sollten diese Begriffe erläutert und klar beschrieben werden.

Reproduzierbarkeit

Ist das Verhalten reproduzierbar? Welche Schritte müssen ausgeführt werden, um es nachzuvollziehen?

Access-Token

Unsere APIs erfordern einen gültigen Access-Token. Diesen erhält man über die Zugangsdaten. Wichtig sind hier client_id, scopes und genutzte URL zur Authentifizierung.

Keinesfalls darf client_secret übermittelt werden!

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.