Tunnel in Sage X3: aprire oggetti a più chiavi con le azioni GOBJET

Se anche tu ti sei scontrato con il problema
di aprire un oggetto da codice via tunnel in Sage X3,
magari specificando due o più chiavi di collegamento,
ebbene questo è l’articolo che fa per te.

Panoramica

Questo articolo sarà un po’ lungo,
cerco quindi di darti un primo orientamento sul percorso che faremo,
così che tu possa saltare le parti che già ben conosci.

• Introduzione sul tunnel in Sage EM
• La gestione oggetto e l’azione GOBJET
• Le azioni GOBJET*
• Tunnel verso un oggetto in Sage X3: tre modi disponibili
  • con il tipo dato in videata
  • parametrizzando un’azione GOBJET
  • da codice
• come impostare il tunnel in base al numero di chiavi

Introduzione sul tunnel in Sage EM

Il cosiddetto tunnel nel gestionale Sage X3
(in realtà Sage Erp X3 è stato rinominato Sage EM – Enterprise Management)
è una delle funzioni nativamente più utilizzate.
Fa molto comodo a tecnici e sviluppatori poter riproporre questa funzionalità nelle personalizzazioni.
La possiamo trovare praticamente ovunque,
per esempio per passare dall’articolo alla sua categoria,
cliccando sul pulsante con la freccia il cui tooltip visualizza la voce “Passa a”.

Per farti capire quanto sia una funzione basilare,
puoi osservare che il meccanismo del tunnel si trova anche
nelle maschere di parametrizzazione delle stesse maschere di Sage ERP X3.

I vantaggi di questo meccanismo in effetti sono innegabili:

• è basato su un’azione dello standard, quindi utilizzabile
  in pulsanti, bottoni, menù, funzioni e così via
• è un meccanismo nativo,
  diffuso in tutto il sistema gestionale Sage X3
• permette di aprire la gestione di oggetti in modo nidificato:
  per esempio dalla fattura puoi passare alla consegna, e da qui all’ordine

Ma la domanda più importante per me era:
ma come si fa il tunnel in Sage X3
quando per passare all’oggetto voluto è necessario specificare tre campi chiave?

Al corso non mi hanno saputo rispondere,
i consulenti nemmeno,
e, ciliegina sulla torta,
dopo che avevo aperto un ticket segnalando che
da documentazione la cosa era possibile ma non era specificato come,
il supporto mi ha risposto più o meno così:

Si, dovrebbe esserci un modo,

ma non sappiamo come

Fortunatamente al corso ero riuscito ad ottenere il codice sorgente giusto,
(ma perchè per avere un sorgente devo chiedere al consulente
di chiederlo al supporto? E dateci ‘sti codici sorgenti!)
mi sono messo a studiarlo, et voilà,
ecco che posso servirvi la soluzione in un piatto di argento.

La gestione oggetto e l’azione GOBJET

Per capire il tunnel in Sage X3 bisogna innanzitutto aver chiaro cosa sia la gestione oggetto.
Non approfondisco certo qui il tema, ma darò solo le indicazioni base per evidenziare il concetto.

Ogni volta che creiamo un oggetto (funzione GESAOB),
Sage X3 Erp crea in automatico una funzione (gestibile poi dalla funzione GESAFC).
Questa funzione creata in automatico è del tipo GESXXX, dove XXX corrisponde al nome dell’oggetto.

Per fare un esempio comune, quando clicchi sul menu Dati di Base\Articoli
quella voce di menù richiama la funzione GESITM: ITM è l’oggetto che gestisce la tabella degli articoli.

Per vedere la funzione lanciata da una voce di menu
basta sostarci sopra con il mouse il tempo che compaia il tooltip.
Puoi così vedere che la funzione chiamata per aprire la gestione dell’oggetto articolo (ITM) è GESITM.

Vai quindi a vedere come è impostata la funzione GESITM
(andando alla funzione Sviluppo\Dizionario Script- GESAFC).

Come puoi vedere la funzione che richiama le gestione dell’oggetto ITM,
con finestra, videate annesse e programmi vari,
non è altro che un richiamo all’azione GOBJET.

A differenza di quello che può sembrare al primo impatto
l’azione GOBJET non ha due bensì tre parametri.
Per verificarlo vai al dizionario delle azioni (funzione GESACT)
a vedere come è impostata l’azione GOBJET.

Si vede bene che i parametri sono tre.
Il secondo e il terzo sono gli stessi che abbiamo visto impostati nella funzione GESITM,
il primo viene passato implicitamente perchè è indicato come campo corrente
(in questo caso il campo corrente è quello della categoria).
Nel nostro caso, cioè partendo dalla voce di menù, il campo corrente sarà vuoto.

Capito questo diventa ovvio anche il concetto di tunnel del gestionale Sage X3.

Il tunnel in Sage X3 non è altro che il lancio della gestione di un oggetto
a partire dalla gestione di un altro oggetto o da qualsiasi altra finestra.

In pratica dovremo lanciare la funzione GOBJET con gli opportuni parametri
in modo che Sage apra la finestra di gestione dell’oggetto che ci interessa.

Abbiamo già indicato all’inizio l’esempio per cui dall’oggetto ITM
possiamo aprire la gestione delle categorie articolo,
cioè la gestione dell’oggetto ITG.

La cosa interessante sta nel fatto che è possibile,
non solo aprire la gestione dell’oggetto voluto, ma farla aprire su uno SPECIFICO oggetto.
Lo puoi vedere passando dall’articolo alla sua categoria con il pulsante “Passa a”.

Questo si fa impostando opportunamente i parametri dell’azione GOBJET,
ed è il punto chiave di questo articolo.

Prima di continuare ti chiedo di supportami
nel mantenere questo blog su Sage ERP X3:
se non lo hai ancora fatto iscriviti!

Iscritto? Ottimo! Non ti perderai utili info su Sage X3!
Sappi che c’è anche il gruppo Sage X3 Italia in LinkedIn,
è un ottimo posto dove far domande!

Le azioni GOBJET*

Sage X3 prevede una ventina di azioni (GESACT) che iniziano per GOBJET.

Perchè ne preveda così tante lo vedremo dopo, intanto diamogli un’occhiata.

Tutte le azioni hanno in genere tre parametri:

1. OBJCLEC: primo parametro per campi chiave
2. OBJETC: è il codice (l’abbreviazione) dell’oggetto da gestire (oggetti che trovi in GESAOB), per esempio ITM per gli articoli
3. OBJZONC: secondo parametro per campi chiave
   

Quindi quando si collega un’azione GOBJET ad un bottone o ad un’azione campo dovremo impostare anche questi parametri, come abbiamo già visto nell’esempio del campo “Categoria” della funzione Articoli (GESITM).

Il tunnel in Sage X3 e il primo indice della tabella

Una cosa fondamentale da ricordare è che il tunnel in Sage X3
si basa sul primo indice della tabella a cui fa riferimento l’oggetto.

Pertanto i valori chiavi del tunnel,
che passiamo attraverso i tre parametri appena visti,
devono essere impostati tenendo bene a mente la struttura del primo indice della tabella dell’oggetto.

Se il primo indice della tabella (ovviamente non deve avere omonimie) è composto da un solo valore realizzare il tunnel è semplice, e probabilmente lo avrai già fatto molte volte.

Il problema nasce quando questo indice è composto da più campi.

Tunnel in Sage X3 verso un oggetto: tre modi disponibili

Vediamo quindi come e dove è possibile inserire un tunnel in Sage X3, in particolare vedremo:

• la parametrizzazione sulle maschere attraverso un tipo dato (da funzione GESAMK)
• la parametrizzazione di un’azione GOBJET
  (per i bottoni delle finestre, le azioni campo, o in tutti i posti
  in cui si possa inserire un’azione in modo parametrico)
• la realizzazione da codice

Tunnel in videata di Sage X3 tramite un Tipo dato

La parametrizzazione di un tunnel basandosi su un campo di una videata è molto semplice. Infatti si può fare andando a specificare un tipo dato legato ad un oggetto, e abilitando il tunnel.

Con il tipo dato i tre parametri dell’azione in pratica vengono impostati in automatico nel caso ci sia una sola chiave.

Con questa modalità si può anche abilitare il legame breve o esteso per recuperare il campo definito come descrizione nella definizione della tabella, ma questo è un altro discorso.
Un esempio è il tipo dato UOM, che rappresenta l’unità di misura: la troviamo nella videata Unità (ITM3) degli articoli:

Se si va a vedere la parametrizzazione della schermata ITM3
(funzione GESAMK) si nota che quel campo ha come tipo dato proprio UOM.

Se vai al tipo dato UOM vedrai che è legato all’oggetto TUN,
che altro non è che l’oggetto che gestisce le unita di misura della tabella TABUNIT.

Non sempre è possibile utilizzare questa via, infatti per vari motivi talvolta è necessario utilizzare un tipo dato non collegato direttamente all’oggetto:
un esempio è il tipo dato WST usato per i Centri di lavoro al posto del “normale” tipo dato MWS (collegato cioè all’oggetto omonimo MWS).

Questo modo porta con se delle comodità, come il legame breve o esteso (in pratica la descrizione) e le opzioni di selezione dell’oggetto.

Tunnel in videata con più campi chiave

Come fare se i campi sono due o più?
Il meccanismo appena visto ha il difetto di basare il collegamento all’oggetto da aprire sul campo stesso in cui si parametrizza il tunnel.
In pratica se per individuare l’oggetto (in base al primo indice) servono due o più campi il gioco non funziona.

Per ovviare a questo bisogna utilizzare i campi “Tabella collegata” e “Espressione legame”, ed indicare i campi corrispondenti al primo indice da usare per legarsi alla tabella collegata. Qui sotto il caso del campo FLYCAT nella tabella ITMMASTER:

Se abbiamo la necessità di guidare la selezione o di fare controlli particolari dovremo inserire sul tipo dato delle azioni specifiche. Il menù contestuale “Parametri” che apparirà sul tipo dato conterrà i parametri delle azioni collegati al tipo dato.

Un caso a cui si può fare riferimento è quello del tipo dati ADI (Tabelle diverse).

Parametrizzare l’azione GOBJET

La realizzazione dei tunnel avviene attraverso l’utilizzo delle azioni che iniziano con GOBJET.
Lo puoi vedere per esempio nella configurazione del pulsante “Articolo Deposito” nella finestra Articolo-Sito (finestra OITF alla funzione GESAWI).

I tre parametri dell’azione GOBJETC1 sono così impostati:

• OBJCLEC: primo parametro è il campo chiave
• OBJETC: è il codice (l’abbreviazione) dell’oggetto da aprire ITW
• OBJZONC: “” (stringa vuota)

Che sia un bottone di una finestra o un’azione campo le modalità di parametrizzazione è sempre questa.

Perchè molte azioni GOBJET

Come abbiamo visto nei casi concreti precedenti,
le azioni usano dei parametri attraverso cui passare dei valori.
Quando è necessario inserire due azioni di questo tipo nello stesso posto ci troveremmo con il dover impostare valori diversi allo stesso parametro.

Se per esempio vogliamo impostare nella stessa videata:

• un azione campo per aprire l’oggetto ITM,
• un’altra azione campo per aprire l’oggetto SOH,

attraverso il parametro OBJETC dovremo fa passare due valori:
“ITM” in un caso, “SOH” nell’altro, cosa logicamente impossibile.

Per ovviare a questo il nostro ERP Sage X3 mette a disposizione le azioni già viste prima, molto simili tra loro ma configurate con parametri diversi.
Così ogni configurazione avrà i propri parametri da impostare.

Le differenze tra un’azione e l’altra riguarda solo la modalità di passaggio dei parametri:

• per valore
• per indirizzo
• l’eventuale uso del campo corrente
• l’impostazione di azione prima/dopo campo

Azioni GOBJET* con due campi chiave

Nel caso si debba parametrizzare un’azione GOBJET veso un oggetto con due campi chiave i tre parametri dell’azione GOBJETC1 vanno impostati così:

• OBJCLEC: primo parametro è il SECONDO campo chiave
• OBJETC: è il codice (l’abbreviazione) dell’oggetto da aprire
• OBJZONC: primo parametro è il PRIMO campo chiave

Esempio con DUE CAMPI CHIAVE

Un esempio di utilizzo lo si trova nella videata CONSOPX2, campo NBLIG.
L’azione collegata GOBJETC0 va sull’oggetto MWS il cui primo indice ha come chiave due campi (il primo di tipo WST, il secondo di tipo FCY):
vedi la tabella corrispondente WORKSTATIO.
La parametrizzazione sarà pertanto:

OBJCLEC   [M:OPX1]FCY                SECONDA CHIAVE (campo di tipo FCY) OBJETC    "MWS" 
OBJZONC   [M:OPX2]EXTWST(nolign-1)   PRIMA CHIAVE   (campo di tipo WST) 

Richiamare un oggetto in tunnel da codice

L’ultimo modo, e il più importante dal punto di vista delle possibilità di personalizzazione di Sage x3 è realizzare il tunnel direttamente da codice.

Capire che chiamate usare è tutto sommato facile, basta andare a spulciare qualche sorgente di quelli creati in automatico dall’ERP (i sorgenti che iniziano per W).

La chiamata da fare è:

Call OBJET(OBJETC,OBJZONC,OBJCLEC) From GOBJET 

Attenzione che i parametri non sono nel solito ordine, ma il primo parametro è quello che contiene l’oggetto da aprire.

Vediamo quindi direttamente un esempio; la seguente chiamata apre la finestra degli ordini di vendita sull’ordine “XXX2501128”:

Local Char CLEC(4)(10), ZONC(10)
CLEC(0) = ""
CLEC(1) = ""
CLEC(2) = ""
CLEC(3) = ""
ZONC = "XXX2501128"   # PRIMA chiave
Call OBJET("SOH",ZONC,CLEC) From GOBJET 

Questo codice aprirà la gestione dell’oggetto SOH (ordini di vendita), visualizzando direttamente l’ordine specificato nella variabile ZONC.

ATTENZIONE: nativamente Sage X3 visualizza l’elemento specificato tramite il campo chiave con il browser a sinistra vuoto.
Se però l’utente aggiorna la videata (col tasto apposito o con F5)
il browser viene riempito permettendo all’utente di visualizzare altri elementi,
e si è in modalità scritttura, non in sola lettura.

Tunnel da codice con due campi chiave

Similmente a quanto già visto nel caso della parametrizzazione delle azioni GOBJET, anche da codice va modificato l’impostazione dei parametri che si passano alla chiamata.

Esempio con DUE CHIAVI

Un esempio lo possiamo provare con l’articolo sito

Local Char CLEC(30)(0..3), ZONC(10)
#tabella articolo sito ITMFACILIT
#primo indice ITF0 = ITMREF + STOFCY
CLEC(0) = "KOK4432"   # PRIMA chiave (cod.articolo)   
CLEC(1) = ""      
CLEC(2) = ""   
CLEC(3) = ""    
ZONC = "SIT1"        #SECONDA chiave  (sito)
Call OBJET("ITF",ZONC,CLEC) From GOBJET 

Tunnel con più valori chiave

Ebbene siamo arrivati al dunque, al punto più succoso.

Ma questa volta facciamo uno scambio alla pari:
in cambio del mio lavoro
e del tempo che risparmierai grazie alle mie dritte
ti chiedo di iscriverti!

Se ti iscrivi tramite il form qui sotto
ti arriverà, assieme a tutti gli altri bonus,
lo schema sintetico
sul tunnel in Sage X3 con 1, 2, 3 o più elementi chiave!

Cosa aspetti?

Ottimo!
Se sei arrivato fin qui ora fai l’ultimo sforzo:
aiutami a far conoscere SageDev ai tuoi colleghi e consulenti!

Alla prossima
Francesco