Tutorial

Erste Schritte

"Wie groß ist der Aufwand, dieses Supportsystem einzubauen?" Diese Frage bekomme ich zur Zeit am häufigsten gestellt und ich möchte sie mit einem klaren: "Sehr gering!", beantworten. Das folgende Tutorial beschreibt alle nötigen Schritte, um das Supportsystem einzubinden, damit Tickets in vollem Umfang bearbeitet werden können.

Dieses Tutorial ist in PHP programmiert und verwendet eine SQLite-Datenbank als Datenquelle.

Was muss bei der Anwendung eingerichtet werden?

Das Supportsystem benötigt eine Schnittstelle bei der Anwendung - eine feste URL über die ein Datenaustausch stattfinden kann.
Beispiel: http://meine-domain/support.php

Diese support.php nimmt sämtliche Anfragen des Supportsystems entgegen und muss im JSON-Format antworten. Um lediglich Tickets über das Supportsystem bearbeiten zu können, müssen den AUTH-Befehl (Autorisierungsanfrage) und der OWNER-Befehl (Zuständigkeitsanfrage) implementiert sein.

Das kann wie folgt aussehen:

<?php

/* Return-Codes, die vom Supportsystem ausgewertet werden */ 
define("RC_OK",            1 );
define("RC_INVALID_PASS", 11 );
define("RC_INVALID_DO",   12 );
define("RC_INVALID_AUTH", 13 );
define("RC_INVALID_ID",   22 );
		
/* SQLite-Datenbank öffnen */
$db = new SQLite3("db.sqlite");


function do_auth(&$db) {
    /* Die Autorisierungsanfrage wird im weiteren Verlauf des Tutorials beschrieben */
}

function do_owner(&$db) {
    /* Die Zuständigkeitsanfrage wird im weiteren Verlauf des Tutorials beschrieben */
}

/* Passcode und Befehl auslesen */
$pass = isset($_REQUEST["pass"]) ? $_REQUEST["pass"] : "";
$do   = isset($_REQUEST["do"  ]) ? $_REQUEST["do"  ] : "";

/* Der Server-Passcode muss übereinstimmen */
if ($pass == "MEIN-PASSCODE") {
    if      ($do == "auth" ) $json = do_auth($db);
    else if ($do == "owner") $json = do_owner($db);
    else                     $json = array("rc" => RC_INVALID_DO);
}
else
    $json = array("rc" => RC_INVALID_PASS);

/* SQLite-Datenbank schließen */
$db->close();

/* Das Objekt in JSON umwandeln und ausgeben */
echo json_encode($json);

?>

Das Supportsystem sendet die Befehle als HTTP-Request. Der Passcode ($_REQUEST["pass"]) und der Befehl ($_REQUEST["do"]) werden aus dem Request ausgelesen. Danach findet ein Abgleich des Passcodes mit dem Server-Passwort statt.

Dieses Server-Passwort wird im Administrationsbereich des Supportsystems eingegeben. Durch dieses Passwort wird sichergestellt, dass nicht jeder Zugriff auf diese Schnittstelle (support.php) bekommt.

Anschließend wird der Befehl ausgewertet und die entsprechende Funktion aufgerufen. Der Rückgabewert wird im JSON-Format an das Supportsystem zurückgesendet.

Was passiert bei der Autorisierungsanfrage?

function do_auth(&$db) {
    /* Autorisierungscode auslesen */
    $auth = isset($_REQUEST["auth"]) ? $_REQUEST["auth"] : "";
    
    /* Das Supportsystem erreicht man über einen Link aus der Anwendung  */
    /* in der eine Session-ID und ein Projektcode mitgegeben wird        */
    /* (hier im Beispiel: demo):                                         */
    /* http://support.zodiac2k.de/?code=demo&auth=<SESSION-ID>           */
    $res = $db->query("SELECT id, name, profile FROM user WHERE session_id='".$db->escapeString($auth)."';");
    if ($row = $res->fetchArray())
        return array("rc"      => RC_OK,             /* Return-Code: OK                        */
                     "profile" => $row["profile"],   /* Profil des Benutzers: admin, mod, user */
                     "id"      => $row["id"     ],   /* ID des Benutzers                       */
                     "name"    => $row["name"   ]);  /* Name des Benutzers                     */
    else
        return array("rc" => RC_INVALID_AUTH);
}

Um das Supportsystem zu erreichen, stellt die Anwendung einen Link bereit. Dieser beinhaltet einen Projekt-Code (um die Anwendung zu identifizieren) und einen Autorisierungs-Code (um den Benutzer zu identifizieren). Dieser Autorisierungs-Code wird durch eine Autorisierungsanfrage überprüft.

Die Autorisierungsanfrage liest den Autorisierungs-Code ($_REQUEST["auth"]) aus und vergleicht ihn (in diesem Beispiel) mit der Session-ID der Benutzer. Die Session-ID stellt eine temporäre und eindeutige ID dar, über die ein Benutzer über einen gewissen Zeitraum identifiziert werden kann.

Das Zugriffsprofil im Supportsystem kann admin (Administrator), mod (Moderator) oder user (Benutzer) sein.

Was passiert bei der Zuständigkeitsanfrage?

function do_owner(&$db) {
    /* User-ID und Objekt-Typ auslesen, für die ein Ticket erstellt werden soll */
    $id     = isset($_REQUEST["id"    ]) ? $_REQUEST["id"    ] : "";
    $entity = isset($_REQUEST["entity"]) ? $_REQUEST["entity"] : "";
    
    /* Den Benutzer mit der Objekt-ID suchen */
    $res = $db->query("SELECT name FROM user WHERE id=".intval($id).";");
    if ($row = $res->fetchArray())
        return array("rc"     => RC_OK,             /* Return-Code: OK                */
                     "entity" => $entity,           /* Objekt-Typ                     */
                     "id"     => $entity.":".$id,   /* Eindeutige Objekt-ID           */
                     "name"   => $row["name"],      /* Name des Objekts               */
                     "uid"    => $row["id"  ],      /* ID des zuständigen Benutzers   */
                     "author" => $row["name"]);     /* Name des zuständigen Benutzers */
    else
        return array("rc" => RC_INVALID_ID);
}

Jedem Ticket im Supportsystem ist ein eindeutiges Anwendungsobjekt zugeordnet. In unserem Fall gibt es nur das Objekt user und es identifiziert den Benutzer.

Zuerst wird die Objekt-ID ($_REQUEST["id"]) und der Objekt-Typ ($_REQUEST["entity"]) ausgelesen. Über die ID wird der Benutzer gesucht, für den ein Ticket erstellt werden soll.

Wie erreichen die Benutzer das Supportsystem?

Die Benutzer erreichen das Supportsystem über einen Link, der in der Anwendung eingebaut werden muss. Um die Anwendung und den Benutzer zu identifizieren, müssen zwei Parameter mitgeschickt werden. Der Projekt-Code (Parameter: code) identifiziert die Anwendung, der Autorisierungs-Code (Parameter: auth) identifiziert den Benutzer.

Als Beispiel würde der Link mit einem Projekt-Code "game0815" und dem Authorisierungs-Code "12345678" wie folgt aussehen:
http://support.zodiac2k.de/?code=game0815&auth=12345678

Über diesen Link erreichen die Benutzer dann direkt ihre Ticketübersicht.