Dart Wrapper für PROFFIX REST-API

Dieser Wrapper wird von der Pedrett IT+Web AG - dem unabhängigen und innovativen Proffix Px5 Partner - unterhalten und entwickelt.

Übersicht

• Installation
  • Konfiguration
• Optionen
  • Methoden
  • Spezielle Endpunkte
• Weitere Beispiele

Installation

dart pub add dart_proffix_rest

Konfiguration

Die Konfiguration wird dem Client mitgegeben:

Beispiel:

import 'package:dart_proffix_rest/dart_proffix_rest.dart';


var pxClient = ProffixClient(
        database: 'DEMODBPX5',
        restURL: 'https://myserver.ch:12299',
        username: 'USR',
        password: 'b62cce2fe18f7a156a9c719c57bebf0478a3d50f0d7bd18d9e8a40be2e663017',
        modules: ["VOL"],
        options: null);

    var request =
        await pxClient.get(endpoint: "ADR/Adresse", params: {"Limit": "1"});

Hinweis zu VOL: Wenn das Modul "VOL" genutzt wird (oder volumeLicence == true gesetzt ist), führt logout() standardmäßig keinen Aufruf an die REST-API aus. Bei Bedarf können Sie einen Logout mit forceLogout: true erzwingen und mit clearSessionCache steuern, ob ein aktivierter Session-Cache geleert werden soll. Siehe Abschnitt „Logout“ weiter unten.

Optionen

Optionen sind fakultativ und werden in der Regel nicht benötigt:

Session Caching (optional)

Ab Version X.X kann die PxSessionId optional gecached werden, um unnötige Logins zu vermeiden. Der Cache wird solange verwendet, bis eine Anfrage mit HTTP 401 (Unauthorized) fehlschlägt. In diesem Fall wird die Session automatisch invalidiert, neu eingeloggt und die Anfrage einmalig wiederholt.

Es gibt zwei Möglichkeiten:

1. Einfach aktivieren (Default: Datei-basierter Cache)

Ohne eigene Callbacks wird automatisch ein Datei-basierter Cache verwendet:

• Windows: %APPDATA%/dart_proffix_rest
• Sonst: systemTemp/dart_proffix_rest

final client = ProffixClient(
  database: 'DEMO',
  restURL: 'https://myserver.ch:12299',
  username: 'USR',
  password: '...SHA256... ',
  options: ProffixRestOptions(
    enableSessionCaching: true, // aktiviert den Cache
  ),
);

1. Eigene Speicherlogik verwenden

Sie können eigene Callbacks zum Laden/Speichern/Löschen der Session-ID übergeben (z. B. Secure Storage, SharedPreferences, etc.):

final myStore = MySessionStore(); // ihre eigene Implementierung

final client = ProffixClient(
  database: 'DEMO',
  restURL: 'https://myserver.ch:12299',
  username: 'USR',
  password: '...SHA256... ',
  options: ProffixRestOptions(
    enableSessionCaching: true,
    loadSessionId: () async => await myStore.read(),
    saveSessionId: (sid) async => await myStore.write(sid),
    clearSessionId: () async => await myStore.clear(),
  ),
);

Verhalten im Überblick:

• Der Client lädt beim ersten Zugriff auf getPxSessionId() einen vorhandenen Cache, falls aktiviert.
• Jeder erfolgreiche Request aktualisiert die intern gespeicherte Session und persistiert sie (falls aktiviert).
• Bei HTTP 401 wird der Cache invalidiert, neu eingeloggt und die Anfrage einmal wiederholt.

Methoden

Folgende unterschiedlichen Methoden sind mit dem Wrapper möglich:

Get / Query

    var request =
        await pxClient.get(endpoint: "ADR/Adresse/1", params: {"Fields": "AdressNr"});

Put / Update

    var request =
        await pxClient.put(endpoint: "ADR/Adresse/1", {
  "Name":   "Muster GmbH",
  "Ort":    "Zürich",
  "Zürich": "8000",
 });

Patch / Update

 var request =
        await pxClient.patch(endpoint: "ADR/Adresse/1", {
  "Name":   "Muster GmbH",
  "Ort":    "Zürich",
  "Zürich": "8000",
 });

Post / Create

 var request =
        await pxClient.post(endpoint: "ADR/Adresse/1", {
  "Name":   "Muster GmbH",
  "Ort":    "Zürich",
  "Zürich": "8000",
 });

Delete / Delete

  var request =
        await pxClient.delete(endpoint: "ADR/Adresse/1");

Spezielle Endpunkte

Check

Prüft die Login - Credentials und gibt bei Fehlern eine Exception aus.

 var check = await pxClient.check();

 // If statusCode = 200 -> Success
 if(check.statusCode = 200){
  print("OK")
// Else show exception
 } else {
  print(check)
 }

Upload / Download File

Lädt eine Datei auf PRO/Datei hoch und gibt die DateiNr als String zurück

  // Upload File
  final File file = File("_assets/dart-proffix.png");

  var bytes = file.readAsBytesSync();
  var dataUpload = Uint8List.fromList(bytes);

  var dateiNr = await pxClient.uploadFile("testDate.png",dataUpload);

  // Download File (again)
  var fileAgain = await pxClient.downloadFile(dateiNr: dateiNr.toString());

Logout

Loggt den Client von der PROFFIX REST-API aus und gibt die Session / Lizenz damit wieder frei. Zusätzlich wird der Dart Client geschlossen.

Ab dieser Version berücksichtigt der Client die PROFFIX Volumenlizenzierung (VOL):

• Wenn die Volumenlizenz aktiv ist (Option volumeLicence == true oder das Modul "VOL" gesetzt ist), wird standardmässig kein Logout ausgeführt, da dies nicht erforderlich ist.
• Mit dem Parameter forceLogout: true können Sie dennoch einen Logout erzwingen.
• Mit clearSessionCache: false können Sie steuern, ob ein aktivierter Session-Cache beim Logout geleert werden soll (Standard: true).

Parameter der Methode logout():

• forceLogout (bool, default false): Erzwingt den Logout auch bei VOL.
• clearSessionCache (bool, default true): Löscht bei aktivem Session-Caching die persistierte PxSessionId.

// Standard-Logout (bei VOL wird nichts gemacht)
var logoutResp = await pxClient.logout();

// Logout erzwingen, auch wenn VOL aktiv ist
var forcedLogoutResp = await pxClient.logout(forceLogout: true);

// Logout erzwingen, aber den Session-Cache behalten (z. B. zur Wiederverwendung)
var forcedLogoutKeepCache = await pxClient.logout(
  forceLogout: true,
  clearSessionCache: false,
);

Der Wrapper führt den Logout auch automatisch bei Fehlern durch, damit keine Lizenz geblockt wird. Bei aktivem Session-Caching wird der Cache im Fehlerfall invalidiert und beim nächsten Request automatisch neu eingeloggt.

getPxSessionId()

Gibt die aktuelle PxSessionId zurück

 var pxSessionId = await pxClient.getPxSessionId();

setPxSessionId()

Setzt die PxSessionId manuell

Hinweis: Diese Methode wird nur für Servicelogins (z.b. via Extension oder Proffix WebView benötigt)

 pxClient.setPxSessionId("99753429-9716-cf41-066a-8c98edc5e928");

GET List

Gibt direkt die Liste der PROFFIX REST API aus (ohne Umwege)

var list = await pxClient.getList(listeNr: 1232,data: {});

Hinweis: Der Dateityp (zurzeit nur PDF) kann über den Header File-Type ermittelt werden*

Hilfsfunktionen

convertPxTimeToTime

Konvertiert einen Zeitstempel der PROFFIX REST-API in time.Time

var tim = ProffixHelpers().convertPxTimeToTime('2004-04-11 00:00:00')

convertTimeToPxTime

Konvertiert einen time.Time in einen Zeitstempel der PROFFIX REST-API

// Create DateTime from now
var timeNow = DateTime tmpDateTime = DateTime.now();

// Convert to PxTime
var tm = ProffixHelpers().convertTimeToPxTime(timeNow);

convertLocationId

Extrahiert die ID aus dem Header Location der PROFFIX REST-API

// Example Create Address
  var postReq =
        await tempClient.post(endpoint: "ADR/Adresse", data: {
    "Name": "Test",
    "Vorname": "Rest",
    "Ort": "Zürich",
    "PLZ": "8000",
    "Land": {"LandNr": "CH"},
  });

  // Get LocationID from Header --> returns newly created AdressNr from posted Address
 createdAdressNr = ProffixHelpers().convertLocationId(postReq.headers);

getFilteredCount

Extrahiert die Anzahl Ergebnisse aus dem Header PxMetaData der PROFFIX REST-API

// Example Get Address with Filter PLZ == Münchwilen
    var getReq = await tempClient.get(endpoint: "ADR/Adresse", params: {
      "Filter": "PLZ=='Münchwilen'",
      "Fields": "AdressNr,Name,Vorname,Ort,PLZ"
    });

  // Get FilteredCount from Header --> returns the total amount of filtered Addresses
 countAddresses = ProffixHelpers().getFilteredCount(getReq.headers);

Weitere Beispiele

Im Ordner /example finden sich weitere, auskommentierte Beispiele.

Proof of Work

Dieser Wrapper wird produktiv mit allen pfx Apps - den Apps für Proffix eingesetzt.