Best Practices für Funktionen

Verwenden Sie „Functions“ zum Schreiben in Tabellen

Empfohlene Vorgehensweise

Erstellen Sie Funktionen, wenn mehrere Apps oder App-Schritte in dieselbe Tabelle schreiben und wenn Sie Folgendes durchsetzen müssen:

• Pflichtfelder
• Gültige Werte (z. B. muss der Status aus einer genehmigten Liste stammen)
• Konsistente Metadaten (Erstellt von, Erstellt am)

Warum dies wichtig ist

Wenn Citizen-Developer Tabelleneinträge direkt in Triggern erstellen, kann es vorkommen, dass sie:

• die Namenskonventionen für IDs nicht einhalten
• erforderliche Felder vergessen
• Feldwerte falsch schreiben („in progress“ statt „in-progress“)
• Metadaten inkonsistent ausfüllen

Eine Funktion sorgt für die Einhaltung des gleichen Schemas und verhindert diese Fehler.

Beispiel

Anstatt jeden App-Entwickler „Beispiel“-Datensätze mit inkonsistenten Feldern und Inhalten erstellen zu lassen, erstellen Sie eine Funktion „Beispiel erstellen“, die:

• konsistente Eingaben erfordert (Auftrags-ID, Probentyp, Menge, Zeitstempel, Benutzer, App-Name)
• überprüft, ob der Probentyp aus einer genehmigten Liste stammt

Funktion:CreateSampleEingaben: - job_id (Text) - sample_type (Text) - quantity (Zahl) - app name (Text) - user requesting (Benutzer)

Logik: 1. Überprüfen, ob „sample_type“ in [„A“, „B“, „C“] enthalten ist. 2. Falls ungültig, Fehlermeldung ausgeben. 3. Erstellt einen Tabelleneintrag mit: - ID: innerhalb der Funktion generiert - Job-ID: Eingabe - Probentyp: Eingabe - Menge: Eingabe - Chargennummer: Eingabe (oder leer, falls nicht angegeben) - Erstellt von: Eingabe4. Gibt eine Erfolgsmeldung zurück

Ausgaben: - Status (Text): „success“ oder „error“ - Meldung (Text): Fehlerbeschreibung bei Fehlschlag

Wenn Sie einen Tabelleneintrag für eine Probe erstellen müssen, übergeben Sie die Eingaben an eine Funktion, und die Funktion erledigt den Rest.

Zu vermeidendes Muster

Erstellen Sie nicht für jeden Tabellenschreibvorgang eine eigene Funktion, auch nicht für einfache Vorgänge.

Warum dies zu Problemen führt

• Es entsteht ein Funktionswust (Hunderte von Einmal-Funktionen)
• Erhöht die Komplexität ohne Nutzen bei einfachen Schreibvorgängen
• Erschwert die Fehlersuche (mehr Stellen, die überprüft werden müssen)

Wann sollten Funktionen für Tabellenschreibvorgänge vermieden werden?

• Aktualisierung eines bestehenden Tabelleneintrags (z. B. Aktualisierung des Status oder Verringerung der Menge)
• Schreibvorgänge einer einzelnen App in eine Tabelle
• Keine Governance oder Validierung erforderlich

Verwenden Sie Funktionen für sich wiederholende, mehrstufige Logik

Empfohlener Ansatz

Wenn dieselbe Abfolge von Trigger-Aktionen in vielen Schritten über mehrere Apps hinweg auftritt, extrahieren Sie diese in eine Funktion.

Beispiel: ZPL-Code zum Drucken eines Etiketts abrufen

Funktion:ZPL-Code abrufenEingaben: – Material-ID (Text)

Variablen: – ZPL-Code-Variable (Text)

Ausgaben: - ZPL-Code (Text)

Logik: 1. Daten aktualisieren: Konfiguration „ZPL-Code-Variable“ – Setzen auf – [Ausdruck für den ZPL-Code einschließlich @Inputs.Material-ID] 2. Zurückgeben: „ZPL-Code“ Datenquelle „ZPL-Code-Variable“

Zu vermeidendes Muster

Erstellen Sie keine Funktionen für Logik, die insgesamt nur 1–2 Mal in allen Apps vorkommt.

Warum dies zu Problemen führt

• Der Aufwand für die Verwaltung der Funktion übersteigt den Nutzen
• App-Entwickler müssen sich für einen seltenen Fall mit der Funktionsschnittstelle vertraut machen
• Erschwert die Fehlersuche, da zwischen Funktionen und Apps gewechselt werden muss

Betten Sie Connector-Funktionen in Funktionen ein

Empfohlener Ansatz

Wenn Sie eine Connector-Funktion verwenden, übergeben Sie die Eingaben der Connector-Funktion an eine Funktion, die die Connector-Funktion aufruft. Die Funktion kann dann Zeitüberschreitungsversuche und die Fehlerbehandlung einfacher und zentralisiert handhaben, wodurch Sie die App-Logik in Ihrer gesamten Lösung vereinfachen können.

Das Einbetten von Connector-Funktionen in Funktionen kann zudem den Aufwand einer möglichen zukünftigen ERP-Migration minimieren, da dadurch die Anzahl der Änderungen reduziert wird, die an einzelnen Apps vorgenommen werden müssen.

Beispiel

Funktion: „Update ProcessOrder“Eingaben: - Auftrags-ID (Text) - Status (Text)

Ausgaben: - Fehlermeldung (Text)

Variablen: – HTTP-Code (Ganzzahl) – Zeitüberschreitungs-Wiederholversuche (Ganzzahl) – Fehlermeldung (Text)

Logik: 1. Connector-Funktion ausführen 2. Wenn der HTTP-Code erfolgreich ist, die Funktion beenden 3. Wenn der HTTP-Code ein Timeout ist und „Timeout-Wiederholversuche“ kleiner oder gleich einem festgelegten Wert ist, „Timeout-Wiederholversuche“ erhöhen und zu „Connector-Funktion ausführen“ zurückkehren4. Wenn der HTTP-Code ein Code ist, der durch die Funktionslogik nicht aufgelöst werden kann, eine hilfreiche Meldung in der Ausgabe „Fehlermeldung“ zurückgeben

Übergeben Sie Datensatz-IDs, nicht einzelne Tabellenfeldwerte

Empfohlene Vorgehensweise

Wenn eine Funktion Daten aus einem Tabellendatensatz benötigt, übergeben Sie die Datensatz-ID und laden Sie den Datensatz innerhalb der Funktion.

Beispiel

Das folgende Beispiel ist zwar logisch korrekt (wobei „Auftrags-ID“ die ID aus der Tabelle „Aufträge“ ist und die anderen Felder Spalten in dieser Tabelle sind), es gibt jedoch eine einfachere Konfiguration.

Funktion:Bestellung verarbeitenEingaben: - Bestell-ID (Text) - Kundenname (Text) - Produkt-ID (Text) - Menge (Zahl) - Fälligkeitsdatum (Datum/Uhrzeit) - Priorität (Text)

Logik: 1. [Logik anhand der Eingabefelder ausführen]

Das folgende Beispiel verwendet nur wenige Eingaben, um dasselbe Ergebnis zu erzielen:

Funktion:Bestellung verarbeitenEingaben: - Bestell-ID (Text)

Logik: 1. Tabelleneintrag abrufen: Tabelle „Orders“, wobei ID = Eingabe „Auftrags-ID“ 2. [Logik anhand der Felder des Tabelleneintrags ausführen]

Warum das zweite Beispiel der bessere Ansatz ist:

• Weniger Eingaben (1 statt 6+)
• Die Funktion lässt sich leicht anpassen, wenn sich das Tabellenschema ändert
• Übersichtlichere Funktionsaufrufe in Apps
• Verringert das Risiko, das falsche Feld der falschen Eingabe zuzuordnen

Funktionen und Eingaben einheitlich benennen und beschreiben

Empfohlene Vorgehensweise

Verwenden Sie eine einheitliche Namenskonvention für alle Funktionen in Ihrem Arbeitsbereich.

Funktionsnamen

• Verwenden Sie Verb + Substantiv: „Beispiel erstellen“, „Auftragsstatus aktualisieren“, „Seriennummer validieren“
• Verwenden Sie keine reinen Substantive: „Beispiel“, „Auftrag“, „Seriennummer“

Funktionsbeschreibung

• Verfassen Sie eine intuitive Beschreibung der Funktionsweise. Schreiben Sie beispielsweise für eine Funktion namens „Create Defect“ eine Beschreibung wie „Erstellt einen neuen Datensatz in der Tabelle ‚Defects‘ mit dem Status ‚OPEN‘“.

Bezeichnungen für Eingaben

• Verwenden Sie eine einheitliche Terminologie: immer „Auftrags-ID“ (nicht manchmal „Auftrags-ID“ oder „Work_id“)
• Passen Sie die Feldnamen der Tabellen nach Möglichkeit an

Namen von Logikblöcken

• Formulieren Sie eindeutig: „Auftragsdatensatz abrufen“ statt „Tabellendatensatz abrufen“
• Helfen Sie zukünftigen Lesern: „Probentyp validieren“ statt „Wert prüfen“

Warum das wichtig ist

• App-Entwickler verstehen den Zweck der Funktionen schnell
• Reduziert die kognitive Belastung bei der Verwendung mehrerer Funktionen
• Erleichtert die „Wo-wird-verwendet“-Analyse
• Verbessert die Dokumentation und Schulung

Nahtlose Handhabung von Eingabevalidierung und Benutzerfehlermeldungen

Empfohlene Vorgehensweise

Kennzeichnen Sie Funktionseingaben stets als Pflichtfelder und wenden Sie gegebenenfalls Regeln zur Eingabevalidierung an. Führen Sie keine Validierung von Eingaben innerhalb von Funktionen durch.

Warum dies wichtig ist

• App-Benutzer erhalten bei der Eingabe von Werten klares Feedback
• Vereinfacht die Funktionslogik, da die App die Eingabevalidierung übernimmt und die Funktion mit bekanntermaßen gültigen Eingaben ausgeführt wird
• Verhindert fehlerhafte Daten durch ungültige Eingaben

Zu vermeidendes Muster

Validieren Sie Eingaben nicht innerhalb der Funktion.

Warum dies zu Problemen führt

• Dies ist redundant, da im App-Editor bereits Funktionen zur Eingabevalidierung verfügbar sind
• Zusätzliche unnötige Verzögerung durch die erneute Überprüfung der Eingaben auf Gültigkeit innerhalb der Funktion

Minimieren Sie Tabellenabfragen innerhalb von Schleifen

Wenn Ihre Funktion ein Array durchläuft, vermeiden Sie es, bei jeder Iteration Tabellen abzufragen. Führen Sie stattdessen vor der Schleife eine einmalige Abfrage durch und greifen Sie auf das Ergebnis zurück.

Verwenden Sie Funktionen für Logik, nicht für einfache Verweise

Erstellen Sie keine Funktionen, die lediglich einen einzelnen Tabelleneintrag abrufen – dafür sind „ record placeholders “ da. Reservieren Sie Funktionen für Logik, die Daten transformiert.

Begrenzen Sie die Ausgabegröße

Wenn Ihre Funktion große Objekte oder Arrays zurückgibt, sollten Sie in Erwägung ziehen, nur die Felder zurückzugeben, die die App benötigt, und nicht das gesamte Objekt-Array.

Weitere Ressourcen

{{snippet.Haben Sie gefunden, wonach Sie gesucht haben?}}