Vai al contenuto

Formatted Search (Ricerche Formattate)

Le Formatted Search (abbreviate in FMS, o Ricerche Formattate in italiano) sono uno degli strumenti più potenti per personalizzare SAP Business One senza (o con pochissimo) codice. Si tratta di query SQL collegate a specifici campi dell'interfaccia utente che, al verificarsi di determinate condizioni, eseguono la query e inseriscono il risultato nel campo stesso.

A cosa servono?

  • Calcolare valori di default al caricamento di una form.
  • Compilare automaticamente un campo (es. Descrizione) quando ne viene modificato un altro (es. Codice).
  • Filtrare i valori inseribili (usate come validazione).
  • Recuperare dati correlati tramite l'uso di query dinamiche.

Sintassi di Riferimento

La potenza delle FMS risiede nella capacità di leggere i valori correnti presenti sulla maschera (Form) prima che vengano salvati nel database. Per fare questo, si utilizza una speciale sintassi con le parentesi quadre e i simboli del dollaro:

$[$FormUID.ItemUID.ColUID.0]

Dove: - FormUID: (Opzionale) L'ID della form. Se omesso, fa riferimento alla form attiva (spesso si omette o si usa $ per la form corrente). - ItemUID: L'ID del controllo (es. il numero del campo di testo, o della matrice/grid). - ColUID: L'ID della colonna (necessario solo se il controllo è una Matrix o una Grid). - 0: Valore finale richiesto dalla sintassi.

Esempio di query FMS: 

-- Legge il valore del campo "CardCode" (che poniamo abbia ItemUID '4') sulla form corrente
SELECT CardName FROM OCRD WHERE CardCode = $[$4.0.0]

-- Legge il valore della colonna 'ItemCode' nella riga attiva di una Matrix (ItemUID '38')
SELECT ItemName FROM OITM WHERE ItemCode = $[$38.ItemCode.0]

Creazione tramite l'Interfaccia Utente (UI) di SAP

Per creare e collegare una FMS manualmente: 1. Apri la form di interesse (es. Ordine di Vendita). 2. Posiziona il cursore sul campo in cui vuoi inserire il risultato. 3. Dal menu in alto: Strumenti (Tools) > Funzione di ricerca (Search Function) > Definire... (Define...) (oppure premi Alt + Shift + F2). 4. Seleziona "Ricerca per Valori Formattati in base alla Query" (Search by Saved Query). 5. Scegli la query desiderata dal Query Manager. 6. Imposta i trigger di aggiornamento (vedi sotto).

I Trigger: Quando si esegue la FMS?

Le FMS possono essere scatenate in vari modi, configurabili tramite la UI o da codice: - Su click del bottone (Lente di ingrandimento): Appare un'icona di fianco al campo. L'utente clicca per eseguire la query. Se ci sono più risultati, appare un popup di selezione. - Aggiornamento automatico (Auto-Refresh): - Uscita dal campo modificato (On Field Change): La query viene eseguita automaticamente quando l'utente modifica il valore di un campo specifico e ne esce (con Tab o click altrove). - Alla visualizzazione (On Form Load/Refresh): Aggiorna il valore ogni volta che il record viene visualizzato.

Creazione Programmatica (Tramite SDK)

Se stai sviluppando un Addon, è buona norma installare e collegare le FMS automaticamente via codice, senza richiedere l'intervento dell'utente. Utilizzando l'API DI (Data Interface), puoi usare gli oggetti UserQueries e FormattedSearches.

Esempio pratico utilizzando un ipotetico modulo helper (come FormattedSearches.cs):

// 1. Creare la Query Utente nel database
string sqlQuery = "SELECT CardName FROM OCRD WHERE CardCode = $[$4.0.0]";
string queryDesc = "Recupera Nome Cliente da CardCode";
int queryCategory = 1; // Categoria delle query (ID della categoria nel Query Manager)

// Salva la query e ottiene il suo ID interno (IntrnalKey)
int queryId = FormattedSearches.CreateUserQuery(sqlQuery, queryDesc, queryCategory, toUpdate: true);

if (queryId > 0)
{
    // 2. Collegare la Query al campo (FMS)
    string formId = "139";      // 139 = Ordine di Vendita (ORDR)
    string itemUid = "MioCampo"; // Il campo di destinazione

    // Configurazione del trigger
    SAPbobsCOM.BoYesNoEnum refresh = SAPbobsCOM.BoYesNoEnum.tYES; // Attiva l'Auto-Refresh
    SAPbobsCOM.BoYesNoEnum regularUpdate = SAPbobsCOM.BoYesNoEnum.tNO;
    SAPbobsCOM.BoYesNoEnum byHeaderField = SAPbobsCOM.BoYesNoEnum.tYES;
    string triggerFieldId = "4"; // Il campo CardCode che fa scattare l'aggiornamento

    // Collega la FMS
    bool success = FormattedSearches.LinkUserQuery(
        formId, 
        itemUid, 
        queryId, 
        refresh, 
        regularUpdate, 
        byHeaderField, 
        triggerFieldId
    );

    if (success) {
        // FMS collegata con successo!
    }
}

Comportamento dell'Auto-Refresh da codice

Quando colleghi una FMS da codice impostando l'Auto-Refresh (Refresh = tYES) su un campo specifico (triggerFieldId), stai automatizzando la compilazione. Nel momento in cui l'utente digiterà un valore in triggerFieldId e premerà Tab, il campo target verrà popolato in autonomia.

Esempio Completo End-to-End

Scenario: In una UDO (User Defined Object) personalizzata (FormType "MIA_UDO"), abbiamo un campo Codice Articolo (ItemUID "TxtItem") e un campo Descrizione (ItemUID "TxtDesc"). Vogliamo che la descrizione si compili da sola all'inserimento dell'articolo.

  1. La Query: SELECT ItemName FROM OITM WHERE ItemCode = $[$TxtItem.0.0]
  2. Il Collegamento: Leghiamo la query al campo TxtDesc.
  3. Il Trigger: Impostiamo l'Auto-Refresh sul cambiamento del campo TxtItem.

Quando l'utente scrive "A0001" nel campo TxtItem e preme Tab, SAP esegue la query sostituendo $[$TxtItem.0.0] con 'A0001', ottiene il nome dell'articolo e lo scrive in TxtDesc.

Tips per il Debugging

Controlla la sintassi delle variabili

Il 90% degli errori nelle FMS dipende da riferimenti errati come $[$Item.Col.0]. Assicurati che l'UID dell'Item e della colonna siano esattamente quelli mostrati nelle Informazioni di Sistema (Visualizza > Informazioni di Sistema).

Tipi di Dati e Tipi Numerici

Se la FMS restituisce un valore numerico (es. un prezzo) per un campo testo, SAP potrebbe restituire un errore o troncare i decimali a seconda delle impostazioni regionali. Prova ad usare funzioni SQL come CAST o CONVERT nella query per formattare l'output come stringa nel formato atteso.

Testare la query in SQL Server / HANA

Non puoi eseguire SELECT * FROM OITM WHERE ItemCode = $[$4.0.0] direttamente in SSMS o HANA Studio! Devi sostituire manualmente le variabili con dei valori fittizi per testare che la logica SQL funzioni prima di salvarla in SAP.