Best practice relative alle funzioni

Prev Next

Who can use Functions

As of r380, Functions is generally available.

Read more in the Community thread.


Utilizza Functions per scrivere nelle tabelle

Approccio consigliato

Creare funzioni quando più app o passaggi di app scrivono nella stessa tabella e quando è necessario applicare:

  • Campi obbligatori
  • Valori validi (ad esempio, lo stato deve essere compreso in un elenco approvato)
  • Metadati coerenti (autore, data di creazione)

Perché è importante

Quando gli sviluppatori non professionisti creano record di tabella direttamente nei trigger, potrebbero:

  • Non rispettare le convenzioni di denominazione degli ID
  • Dimenticare i campi obbligatori
  • Scrivere in modo errato i valori dei campi ("in progress" anziché "in-progress")
  • compilare i metadati in modo incoerente

Una funzione impone lo stesso schema e previene questi errori.

Esempio

Invece di lasciare che ogni sviluppatore di app crei record "Campione" con campi e contenuti incoerenti, crea una funzione "Crea campione " che:

  • Richieda input coerenti (ID lavoro, tipo di campione, quantità, data e ora, utente, nome dell’app)
  • Verifichi che il tipo di campione sia presente in un elenco approvato

Funzione:CreateSampleInputs: - job_id (testo) - sample_type (testo) - quantity (numero) - nome dell’app (testo) - utente richiedente (utente)

Logica: 1. Verifica che sample\_type sia in ["A", "B", "C"] 2. Se non valido, restituisca un messaggio di errore 3. Crea un record nella tabella con: - ID: generato all’interno della funzione - ID lavoro: dato in ingresso - Tipo di campione: dato in ingresso - Quantità: dato in ingresso - Numero di lotto: dato in ingresso (o vuoto se non fornito) - Creato da: dato in ingresso4. Restituisci un messaggio di successo

Risultati: - stato (testo): "successo" o "errore" - messaggio (testo): descrizione dell'errore in caso di fallimento

Quando è necessario creare un record di tabella per un campione, passare i dati in ingresso a una funzione, che si occuperà del resto.

Modello da evitare

Non creare una funzione per ogni operazione di scrittura nella tabella, nemmeno per quelle semplici.

Perché questo causa problemi

  • Si crea una proliferazione di funzioni (centinaia di funzioni monouso)
  • Aumenta la complessità senza alcun vantaggio per le semplici operazioni di scrittura
  • Rende più difficile il debug (più punti da controllare)

Quando evitare le funzioni per le operazioni di scrittura nelle tabelle

  • Aggiornamento di un record esistente in una tabella (ad esempio, aggiornamento dello stato o decremento della quantità)
  • Scritture da una singola applicazione su una tabella
  • Nessuna governance o convalida richiesta

Utilizzare le funzioni per logiche ripetitive in più fasi

Approccio consigliato

Se la stessa sequenza di azioni di trigger si verifica in molte fasi in più app, estrarla in una funzione.

Esempio: Ottenere il codice ZPL per la stampa di un'etichetta

Funzione: Ottienicodice ZPLInput: - ID materiale (testo)

Variabili: - Variabile codice ZPL (testo)

Uscite: - Codice ZPL (testo)

Logica: 1. Aggiorna dati: Configurazione 'Variabile codice ZPL' - Imposta su - [Espressione per il codice ZPL che include @Inputs.ID materiale] 2. Restituisci: 'Codice ZPL' Origine dati 'Variabile codice ZPL'

Modello da evitare

Non creare funzioni per logiche che si verificano solo 1-2 volte in totale in tutte le app.

Perché questo causa problemi

  • Il sovraccarico derivante dalla gestione della funzione supera i benefici
  • Obbliga gli sviluppatori di app a imparare l’interfaccia della funzione per un caso raro
  • Rende più difficile il debug, a causa del passaggio da una funzione all’altra e da un’app all’altra

Incorporare le funzioni del connettore nelle funzioni

Approccio consigliato

Quando si utilizza una funzione di connettore, passare gli input della funzione di connettore a una funzione che chiama la funzione di connettore. La funzione può quindi gestire i tentativi in caso di timeout e la gestione degli errori in modo più semplice e centralizzato, consentendo di semplificare la logica delle app in tutta la soluzione.

L’integrazione delle funzioni di connettore nelle funzioni può inoltre ridurre al minimo lo sforzo richiesto da una potenziale migrazione ERP futura, riducendo la quantità di modifiche da apportare alle singole app.

Esempio

Funzione: Aggiornaordine di processoInput: - ID ordine (testo) - Stato (testo)

Uscite: - Messaggio di errore (testo)

Variabili: - Codice HTTP (numero intero) - Tentativi in caso di timeout (numero intero) - Messaggio di errore (testo)

Logica: 1. Esegui la funzione del connettore 2. Se il codice HTTP indica un esito positivo, termina la funzione 3. Se il codice HTTP indica un timeout e il parametro «Tentativi in caso di timeout» è minore o uguale a un valore specificato, incrementare il parametro «Tentativi in caso di timeout» e tornare a «Eseguire la funzione del connettore»4. Se il codice HTTP non può essere risolto dalla logica della funzione, restituire un messaggio di aiuto nell’output «Messaggio di errore»

Passare gli ID dei record, non i singoli campi dei record della tabella

Approccio consigliato

Quando una funzione necessita di dati da un record di una tabella, passare l’ID del record e caricare il record all’interno della funzione.

Esempio

Sebbene l’esempio seguente sia logicamente corretto (dove “ID ordine” è l’ID della tabella Ordini e gli altri campi sono colonne di quella tabella), esiste una configurazione più semplice.

Funzione: Elaboraordine Input: - ID ordine (testo) - Nome cliente (testo) - ID prodotto (testo) - Quantità (numero) - Data di scadenza (data e ora) - Priorità (testo)

Logica: 1. [Eseguire la logica utilizzando i campi di input]

L’esempio riportato di seguito utilizza un numero minimo di input per ottenere lo stesso risultato:

Funzione: Elaboraordine. Dati in ingresso: - ID ordine (testo)

Logica: 1. Recupera il record della tabella: tabella Ordini dove ID = input "ID ordine" 2. [Esegui la logica utilizzando i campi del record della tabella]

Perché il secondo esempio rappresenta un approccio migliore:

  • Meno input (1 invece di 6+)
  • La funzione può adattarsi facilmente se lo schema della tabella cambia
  • Chiamate di funzione più chiare nelle app
  • Riduce la possibilità di associare il campo sbagliato all’input sbagliato

Assegnare nomi e descrivere le funzioni e gli argomenti in modo coerente

Approccio consigliato

Utilizza una convenzione di denominazione coerente per tutte le funzioni nel tuo spazio di lavoro.

Nomi delle funzioni

  • Utilizzare verbo + sostantivo: Crea campione, Aggiorna stato lavoro, Convalida numero di serie
  • Non utilizzare solo sostantivi: Campione, Lavoro, Numero di serie

Descrizione della funzione

  • Scrivi una descrizione intuitiva di ciò che fa la funzione. Ad esempio, per una funzione denominata "Crea difetto", scrivi una descrizione del tipo "Crea un nuovo record nella tabella Difetti con lo stato APERTO".

Nomi degli input

  • Utilizza una terminologia coerente: sempre ID ordine di lavoro (non a volte ID ordine o Work_id)
  • Allineare i nomi dei campi della tabella quando possibile

Nomi dei blocchi logici

  • Sii esplicito: "Recupera record lavoro" anziché "Recupera record tabella"
  • Aiutate i futuri lettori: "Convalida tipo campione" anziché "Controlla valore"

Perché è importante

  • Chi sviluppa le app capisce subito lo scopo delle funzioni
  • Riduce il carico cognitivo quando si utilizzano più funzioni
  • Rende più semplice l’analisi “dove viene utilizzato”
  • Migliora la documentazione e la formazione

Gestisce la convalida degli input e i messaggi di errore per l’utente in modo fluido

Approccio consigliato

Contrassegnare sempre gli input delle funzioni come campi obbligatori e utilizzare le regole di convalida degli input dove opportuno. Non convalidare gli input all’interno delle funzioni.

Perché è importante

  • Gli utenti dell'app ricevono un feedback chiaro durante l'inserimento dei valori
  • Si semplifica la logica delle funzioni, poiché è l'app a gestire la convalida degli input e la funzione viene eseguita con input di cui è nota la validità
  • Si previene la corruzione dei dati causata da input errati

Modello da evitare

Non convalidare gli input all'interno della funzione.

Perché questo causa problemi

  • È ridondante rispetto alle funzionalità di convalida degli input disponibili nell’editor dell’app
  • Latenza aggiuntiva e non necessaria dovuta alla verifica della validità degli input all'interno della funzione
NOTE

App builders can bypass the system by passing blank static values in function inputs. For functions where validated data is critical, it may be best practice to validate inputs in the function itself (in addition to marking required fields in the app).

Ridurre al minimo le query sulle tabelle all'interno dei cicli

Se la funzione esegue un ciclo su un array, evitare di eseguire query sulle tabelle ad ogni iterazione. Eseguire invece una sola query prima del ciclo e fare riferimento al risultato.

Utilizza le funzioni per la logica, non per semplici riferimenti

Non creare funzioni che si limitino a recuperare un singolo record da una tabella: a questo servono le istruzioni record placeholders. Riserva le funzioni alla logica che trasforma i dati.

Limitare la dimensione dell'output

Se la funzione restituisce oggetti o array di grandi dimensioni, valuta la possibilità di restituire solo i campi necessari all’app, anziché l’intero array di oggetti.


Risorse aggiuntive

{{snippet.Hai trovato quello che cercavi?}}