pixi* API und Freeboard

pixi* API liefert SOAP Array’s. Freebord benötigt Daten im JSON Format.

Durch die Descartes pixi* API erhalten wir SOAP Array’s zur Weiterverarbeitung. Zur alternativen Darstellung von Kennzahlen – Descartes hat ein eigenes KPI Dashboard – habe ich mich für Freeboard entschieden. In einem Workshop habe ich die Vorzüge erläutert (Link).

Die Array’s aus der API speichere ich zwischen und extrahiere aus den mehrstufigen Array’s die Daten, die ich darstellen möchte. Interessant ist, das der Aufbau der Antworten stark unterschiedlich ist und deshalb kein einheitliches Vorgehen anzuraten ist.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
<?php
 
require __DIR__.'/vendor/autoload.php';
use Pixi\API\Soap\Options;
use Pixi\API\Soap\Client;
$username = 'user'; // Your pixi database
$password = 'passwort'; // Your API password
$endpoint = 'https://soap.pixi.eu/soap/test/'; // Enpoint of your API
$options = new Options($username, $password, $endpoint);
$client = new Client(null, $options->getOptions());
$client->setTransportObject('\Pixi\API\Soap\Transport\CurlTransport');
$client->setResultObject('\Pixi\API\Soap\Result\ArrayResult');
//################################################################
// Liste aller Shops
$rs = $client->pixiGetShops()->getResultset();
// Verbindungsaufbau und Auswahl der Datenbank
$dbconn = pg_connect("host=localhost dbname=pixi user=a password=b")
    or die('Verbindungsaufbau fehlgeschlagen: ' . pg_last_error());
// durchlaufen aller Shops
foreach ($rs as $key => $res) {
//################################################################
    $time1 = date("Y-m-d", strtotime("-6 months"));
    $time2 = date("Y-m-d");
    $pixiParams = array('ShopID' => $rs[$key]['ShopID'],'FromTime' => $time1,'UntilTime' => $time2);
    $res2 = $client->pixiReportReceivedOrders($pixiParams)->getResultset();
//################################################################
// Postgres Insert
    $query = "Insert into orders (zeit,label,x) values('".$time2."','".$rs[$key]['ShopID']."',".$res2[0]['ReceivedOrders'].");";
    $result = pg_query($query);
//#################################################################                            
 
}
                            // Speicher freigeben
                            pg_free_result($result);
 
                            // Verbindung schließen
                            pg_close($dbconn);
 
?>

Das Listing ist ein Beispiel für das Grundgerüst. In Zeile 15 holen wir uns alle konfigurierten Shops mit der Abfrage pixiGetShops. In einer foreach Schleife rufen wir in Zeile 25 für jeden Shop (‚ShopID‘ => $rs[$key][‚ShopID‘]) pixiReportReceivedOrders auf und speichern die Daten in einer Datenbank zwischen um eventuell später Durchnittswerte errechnen zu können.

Um die Daten – welche auch immer – in Freeboard sichtbar zu machen, müssen wir aus dem Array einen Datensatz im JSON Format generieren.

1
2
3
4
5
6
7
8
9
$time1 = date("Y-m-d H:i:s", strtotime("-24 hours"));
$time2 = date("Y-m-d H:i:s");
foreach($shops as $key => $su){
    $pixiParams = array('timePeriod' => 9999,'ShopID' =>  $su,'startDateTime' => $time1,'endDateTime' => $time2);
    $rs = $client->pixiReportScanInPerTimeQuant($pixiParams)->getResultset();
    $ergebnis[$key] = array($rs[0]['SUMScanIn'],$key);
}
$JSON = json_encode($ergebnis);
print('{ "data": '.str_replace('"','',$JSON).'}');

Ändern wir den Code einmal wie oben beschrieben ab und rufen die Werte der letzten 24 Stunden für pixiReportScanInPerTimeQuant auf. Entscheidend ist Zeile 9. Freebord kann in einer Linien- oder Balkengrafik nur „{ data: [5,0],[1,1],[5,2]}“ verarbeiten.

Wir werden hier noch genauer darauf eingehen. Freeboard hätte gerne für die verschiedenen grafischen Möglichkeiten, einen unterschiedlichen Datensatzaufbau. Es ist noch damit zu spielen, welche Zahl bzw. API Auswertung Sinn auf einem KPI macht und wie wir die Daten aufbereiten müssen.

Dashboard

Eines von vielen Dashboards näher betrachtet. Nebenbei kann man hier einiges über Datenbeschaffung und Verarbeitung zeigen. Hier die Zusammenfassung unseres Workshops.

Freeboard hat einige Vorteile. Es ist schlicht, komplett offen programmierbar und leicht mit HTML oder JavaScript einstellbar. Um den Workshop nachvollziehen zu können, hier ein paar Eckpunkte.
Nach der Installation von Freeboard auf unserem Debian 9 System mit Apache2, muss noch eine Weile gesucht werden um sinnvolle Erweiterungen zu finden – je nachdem welche Darstellungen man zeigen möchte.

Im Bild oben ist unsere Finale index.html in der verschiedene JavaScript Widgets eingebunden sind. Das altgauge.js haben wir verändert.

zu grün ändernde Anzeige

In Zeile 29 ändern wir die Farbreihenfolge von rot über gelb nach grün. Besonderst interessant sind das HighChart, das einzelne Werte auf einer Zeitachse darstellt und die FLOT Widgets, die saubere Linien und Balkendiagramme ermöglicht. Grundsätzlich „versteht“ Freeboard JSON Datenquellen und ist per JavaScript einstellbar. JSON Datensätze sehen grundsätzlich gleich aus, unterscheiden sich aber je nach eingesetztem Chart. Mal werden einzelne Werte erwartet, mal x,y Werte.Einzelne Werte für Tachoanzeigen und/oder Text/HTML. Geschachtelte Werte für Linien- oder Balkengrafik.

Natürlich versteht Freeboard auch mehrdimensionale JSON Array’s. In der Praxis haben wir die Daten aus https://warnung.bund.de/bbk.dwd/unwetter.json genutzt. Dort werden Warnmeldungen nach Art und Ort ausgegeben. Es empfiehlt sich die Daten vor Darstellung lokal aufzuarbeiten, da die Darstellung aller Daten in einer nicht vorhersehbaren Reihenfolge nicht empfehlenswert ist. Wie sieht das im einzelnen aus:

Im PHP Code durchsuchen wir das Array in der ersten und zweiten Dimension – die Menge können wir nicht beeinflussen. Wir nehmen Unwetterwarnungen nur für unsere Geolokation die so übergeben wird: value“094780000000″. Welcher Ort welchem Wert entspricht kann unter (Link) gesucht werden. In unserem Fall rufen wir nur Unwettermeldungen für den Rheinisch-Bergischen-Kreis heraus.

Das Dashboard (Link) bleibt auf dem Server und wer Einzelheiten aus dem Code wissen möchte oder noch Fragen zur Datenaufbereitung hat, mag mich einfach fragen. Sendet doch Beispiele eurer Dashboards – wir können sie hier veröffentlichen.